使用 JSDoc 为 n8n 代码节点添加 TypeScript 级别的智能提示 - n8n 工作流

高级 n8n 用户: 频繁使用 n8n 代码节点编写自定义逻辑的开发者。
自动化专家: 需要构建复杂 n8n 工作流系统并要求强大调试工具的人员。
技术内容创作者: 需要记录或分享高效 n8n 开发最佳实践的人员。
所有人: 希望提高 n8n 模板中的代码质量并减少错误的开发者。

在使用 JavaScript 的 n8n 代码节点时，如果没有适当的自动补全功能，调试和访问复杂输入对象（例如从 n8n 节点或 API 操作返回的对象）可能会很棘手。这个特定的 n8n 示例通过利用 JavaScript 生态系统广泛使用的方法——JSDoc 注解——解决了这个问题。

通过定义对象的预期结构（例如通过 n8n API 节点检索到的 Workflow 对象），你可以为 n8n 编辑器内置的代码功能提供强类型的提示。这会带来 TypeScript 级别的智能提示，使在你 n8n 工作流中编写、维护和调试复杂的自定义脚本的效率和可靠性大大提高。这项技术对于提升任何健壮的 n8n 模板的开发速度都非常有价值。

这个演示性的 n8n 工作流利用了四个关键步骤来说明智能提示技术：

1. 触发器 (On form submission): 流程启动使用一个基础的表单 n8n 触发器，方便手动启动 n8n 工作流进行测试。


2. 获取工作流数据 (Get This Workflow): n8n 节点被配置为使用 get 操作来检索当前正在运行的 n8n 工作流的完整元数据结构。这个复杂的 JSON 对象被传递给下一个 n8n 节点。


3. 应用智能提示 (Code With Intellisense): 这个代码 n8n 节点是核心演示。它定义了两个 JSDoc 类型定义（@typedef {Object} Node 和 / @typedef {Object} Workflow /）。然后，使用内联 JSDoc 注释（/ @type {Workflow} /）将传入的 JSON 强制转换为 wf 变量。这个操作为在代码节点中访问像 wf.id、wf.name 以及遍历 wf.nodes 这样的属性提供了完美的智能提示。


4. 显示结果 (Display Results): 最后一个表单 n8n 节点将上一步代码节点解析的输出（使用新启用的智能提示提取）以整齐的 HTML 格式显示出来，直观地证明了 n8n 工作流逻辑的有效性。

要在你自己的 n8n 模板中安装和使用这种强大的开发技术：

1. 导入: 复制提供的 n8n 工作流 JSON，并通过“从 JSON 导入”(Import from JSON) 选项将其粘贴到你的 n8n 实例中。


2. n8n API 凭据: “获取此工作流”(Get This Workflow) n8n 节点需要名为 n8n unio API v1 的有效 n8n API 凭据。请确保你已经在 n8n 中设置了有效的 API 密钥。


3. 运行: 执行“表单提交时”(On form submission) 的 n8n 触发器或手动测试 n8n 工作流。在编辑“带智能提示的代码”(Code With Intellisense) n8n 节点时留意：鼠标悬停或输入对象属性（如 wf.）时，现在应该会出现有用的代码建议。

On form submission (n8n 触发器): 作为测试此 n8n 工作流的起点。它是一个标准的 HTTP n8n 触发器机制。
Get This Workflow (n8n 节点): 使用内部 n8n API 来检索当前执行的 n8n 工作流的完整 JSON 表示。这提供了 JSDoc 示例所需的复杂对象结构。
Code With Intellisense (代码 n8n 节点): 核心组件。它使用 JSDoc 定义复杂类型，特别是 Workflow 和 Node 类型。关键配置在于内联类型转换：const wf = / @type {Workflow} / ($input.first().json);，这对于在 n8n 模板中编码时激活强大的智能提示功能至关重要。

• Display Results (表单 n8n 节点): 将代码 n8n 节点的执行结果输出到一个格式整洁的 HTML 页面，为 n8n 工作流逻辑的成功提供即时可视化反馈。