该技能用于指导开发者用 TypeScript 构建、测试和发布 n8n 自定义节点及社区节点包(用于 npm)。内容围绕开发规范与常见错误预防展开。
一、用途与快速参考 提供从脚手架到发布的任务清单:克隆 n8n-io/n8n-nodes-starter 模板,执行 npm install 安装依赖;npm run dev 进入开发模式(在 http://localhost:5678 热重载);npm run build 编译到 dist/;npm run lint 检查代码;npm publish 发布(包名必须以 n8n-nodes- 开头)。
二、实现方式选择 技能给出决策树:若节点是对 REST API 的标准增删改查封装,应采用声明式风格(在 properties 中配置 routing,不写 execute() 方法);若需要复杂数据转换、自定义逻辑,或需调用多个 API、组合数据源,则应采用编程式风格(通过 execute() 方法完全控制执行逻辑)。
三、项目结构 标准目录包括 package.json(通过 n8n 字段注册节点,关键)、tsconfig.json、credentials/(凭证定义)、nodes/(节点实现、可选的 .node.json 元数据、声明式资源描述)、icons/(SVG 或 PNG,建议最大 60x60px)以及构建生成的 dist/。
四、package.json 的 n8n 字段(关键) 需设置 keywords 为 ["n8n-community-node-package"] 以便被 n8n 发现;n8n.nodes 与 n8n.credentials 必须指向 dist/ 下编译后的 .js 文件,绝不能指向 .ts 源文件;包名必须使用 n8n-nodes- 前缀;n8n-workflow 必须声明为 peerDependencies 而非普通依赖;files 字段包含 ["dist"]。
五、节点描述(INodeTypeDescription) 必须定义 displayName、name(驼峰唯一名)、icon、group、version、description、defaults(name 与 displayName 一致)、inputs/outputs(使用 n8n-workflow 的 NodeConnectionTypes.Main,不硬编码 'main')、credentials、properties。触发器节点需将 group 设为 ['trigger'] 且 inputs 为空数组。
六、编程式节点规则 遍历全部输入项(this.getInputData());调用 this.getNodeParameter() 时传入项索引 i 以按项解析表达式;在 catch 中处理 this.continueOnFail();推送错误项时包含 pairedItem: { item: i };返回二维数组(单输出为 [returnData],双输出为 [trueItems, falseItems])。示例中通过 this.helpers.httpRequest 发起请求并读取 this.getCredentials('myApi')。
七、声明式节点规则 不得定义 execute() 方法;通过 requestDefaults.baseURL 设置 API 基础地址;在操作选项上用 routing.request 定义 HTTP 方法与 URL;在参数属性上用 routing.send 将值映射到请求体或查询参数。
八、凭证定义 凭证 name 必须与节点 credentials 中引用的名称一致;敏感字段(API Key、Token、密码)必须设置 typeOptions: { password: true };声明式节点使用 authenticate 自动注入认证;编程式节点在 execute() 中通过 await this.getCredentials('myApi') 获取凭证。
九、图标处理 优先 SVG,PNG 作为回退;放在项目根 icons/ 目录或节点文件旁;引用格式为 icon: 'file:myIcon.svg';主题图标可用 { light, dark } 对象;也可使用有限集合的 FontAwesome 图标如 'fa:clock';建议最大 60x60 像素。
十、开发与发布流程 克隆模板并移除 .git 后安装依赖;npm run dev 加载节点并热重载;build 与 lint 后再发布;可用 npm link 在本地 n8n 安装目录中链接测试并重启 n8n。测试可使用 WorkflowTestData:用 nock 模拟外部 API 调用、定义期望的 nodeData 输出、指定 nodeExecutionOrder 验证执行顺序。发布检查清单包括包名前缀、keywords、n8n 字段指向 dist/*.js、peerDependencies、files 字段、构建与 lint 通过、包含图标、README 说明安装与可用节点。
十一、适用场景与限制 适用于开发 n8n 社区节点包及自定义节点。资料未提供具体收费、价格、平台支持范围或效果数据;参考资料为 n8n-nodes-starter 模板与 n8n 官方创建节点、社区节点文档。