“这个需求内置的 HTTP Request 节点也能做啊为什么还要自己开发一个 n8n 自定义节点”这是过去半年里我被问得最多的一句话。我每次的答案都一样因为当你需要把同一个业务逻辑在十个工作流里复用又要保证参数校验、错误处理、权限配置都一致的时候复制粘贴 HTTP 配置和维护一坨 Webhook 地址就成了灾难。我最早接触 n8n 的时候也以为靠现有节点拼一拼就够了直到某个客户内部系统的接口要求消息先做签名、再按分钟级窗口重试、失败还要落库我才老老实实打开 TypeScript 文档走上了开发自定义节点的路。这篇文章就是写给那些想在 n8n 里写自己节点的朋友。我会用我自己实际写过的一个“企业微信机器人消息”节点作为完整例子把从工程初始化、节点结构、执行逻辑、本地联调到最终发布的完整链路都过一遍。适合已经跑通过 n8n 基础工作流、但对节点内部机制还不够清楚的人。看完之后你应该能独立写出第一个能上生产环境的 n8n 自定义节点而不是只会停留在“改改官方模板”的阶段。1. 为什么非要自己写节点内置能力与自定义节点的边界1.1 从“能跑通”到“用得顺手”什么时候该考虑自定义节点n8n 的节点生态其实已经相当丰富了光是官方节点库里就有 HTTP Request、Webhook、Code、Set、IF、Switch 这些通用积木。很多场景下你确实不需要自定义节点比如只是调一个公开 APIHTTP Request 节点加个 Header 就能搞定比如只需要做简单的数据清洗Code 节点写几行 JavaScript 也可以。但问题在于用通用节点搭出来的流程经常是“能跑通但非常脆”。我举一个真实例子接入某个企业内部的 ITSM 系统发送工单创建请求。官方 HTTP Request 节点能做但需要每个调用者都记住请求头要带三个签名参数、超时时间必须设 20 秒、失败重试三次且每次间隔递增、状态码 200 之外都算失败。这套逻辑如果分散在各个工作流里一旦签名规则改了你就要去改十条甚至几十条流。而且别人看你工作流的时候根本看不懂那个代码段的意图。自定义节点的第一个核心价值就是封装。你把公司的业务规则、签名算法、错误重试全部写进一个节点里工作流里只暴露几个必要的配置参数。后续规则变更你只改节点代码然后升级版本所有引用这个节点的工作流自动获得新行为。第二个价值是类型安全。你可以给字段配置固定的 JSON Schema 类型比如数字字段n8n 会在界面上做校验不允许用户随便填一个字符串进去。第三个价值是统一的错误语义。节点内部可以精确控制什么样的情况抛异常、什么样的返回值继续走后续分支这比在 Code 节点里手写各种 throw 要规矩得多。1.2 自定义节点的结构description 加 execute 的二分法进入代码之前得先理解 n8n 节点的底层设计。任何一个节点本质上都只有两个部分。第一部分是description节点描述它负责告诉 n8n 编辑器“我这个节点长什么样”。节点叫什么名字、属于什么分组、需要哪些输入输出线、左侧配置面板要显示哪些参数字段、每个字段的类型和默认值是什么全部由 description 定义。你拖一个节点到画布上双击打开的配置界面就是从description.properties渲染出来的。第二部分是execute执行函数它负责告诉运行引擎“当用户点击 Execute Node 或 Runner 跑到这一格时这段代码要做什么”。它会收到上游传过来的itemsn8n 里统一用数组表示一批数据处理完以后再把新的items返回出去。就像工厂流水线上的一道工序流入一批半成品流出另一批半成品中间你的逻辑就是那台机器。理解这个二分法之后你就明白为什么 n8n 节点特别容易上手你不需要参与整个工作流引擎的调度只需要把“配置界面”和“处理逻辑”写好剩下的连接线、重试、并发、上下文传递全都不用你操心。这也意味着如果你打算写节点真正的工作量其实集中在 description 和 execute 的代码组织上而不是去研究什么分布式调度。1.3 官方包生态n8n-nodes-base 和社区包规律n8n 的节点一般被打包成 npm 包发布。官方源码仓库里有packages/nodes-base里面躺着几百个官方节点代码结构非常清晰是最值得参考的“标准答案”。社区节点则一般命名为n8n-nodes-xxxx发布后会通过n8n-npm等平台被用户搜索和安装。我强烈建议你在动手写之前先去 GitHub 上打开nodes-base里某一个你熟悉的节点读一遍源码。比如 HTTP Request 节点它的 description 有几十个字段execute 方法里面的逻辑分支特别多初看会头大。建议不要从这种复杂节点开始而是先看Set节点或NoOp节点几十行代码把骨架弄清楚。我的经验是先抄着写一个“什么都不干只管把输入返回出去”的节点跑通了再往里面加逻辑这是最稳的学习路径。2. 环境准备与项目骨架把本地开发链路跑通2.1 工具版本与全局依赖开发 n8n 节点本质上就是开发一个 npm 包所以 Node.js 和 npm 是必须的。我自己目前用的是 Node.js 20 LTSnpm 10.x。n8n 本身对 Node 版本兼容范围较宽但社区的许多构建工具对更高版本支持会滞后所以建议尽量使用 LTS 版本不要追新。你需要全局或者项目内安装的包主要是两类。一类是编译工具因为 n8n 节点源码通常用 TypeScript 编写发布前需要编译成 JavaScript。早期常用n8n-node-dev这个工具集成了模板、编译、链接到本地 n8n 等功能但现在官方仓库已经把相关脚本收拢到packages/nodes-base里了。我的建议是直接使用n8n-node-dev也行它依然可以工作但更省心的做法是自己用 TypeScript 的tsc编译把编译产物指向 n8n 的custom目录。后面我会给出一套具体的做法。还要提一下types/node、types/express这类类型声明包。n8n 内部很多类型定义来自n8n-workflow包你的代码只要import { INodeType, INodeTypeDescription, INodeExecutionData } from n8n-workflow就能拿到大部分类型的声明所以项目中需要显式安装n8n-workflow作为 peer dependency确保类型同步。2.2 用 npm 初始化节点项目初始化一个空目录比如叫n8n-nodes-demomkdir n8n-nodes-demo cd n8n-nodes-demo npm init -y npm install --save-dev typescript types/node types/express npm install --save n8n-workflow注意n8n-workflow平时最好作为peerDependencies放进 package.json而不是直接打包进你的节点产物因为 n8n 运行环境里已经有这个包了。如果直接放进 dependencies可能造成版本冲突。这点我在踩坑阶段遇到过后面会在第六节专门说。然后创建一个tsconfig.json核心配置如下{ compilerOptions: { target: ES2021, module: CommonJS, rootDir: src, outDir: dist, strict: true, esModuleInterop: true, skipLibCheck: true, declaration: true }, include: [src/**/*.ts] }为什么这里用 CommonJS因为 n8n 运行时是通过require加载自定义节点的ESModule 需要额外的互操作处理没必要给自己找麻烦。target 选 ES2021 是因为 n8n 支持较新的 Node 语法特性但也不要选太激进的免得在社区其他用户的旧版 Node 上跑不了。2.3 package.json 里对 n8n 最关键的部分package.json里有一项n8n字段这是 n8n 识别自定义节点包的核心依据。它的格式长这样{ name: n8n-nodes-demo, version: 0.1.0, main: dist/index.js, scripts: { build: tsc, dev: tsc --watch }, n8n: { credentials: [dist/credentials/MyCredential.credentials.js], nodes: [dist/nodes/DemoNode/DemoNode.node.js] } }看到main指向的是dist/index.js了吗这里要保证dist/index.js会自行导出你所有的节点和凭据。通常我会在src/index.ts里做统一聚合导出import { DemoNode } from ./nodes/DemoNode/DemoNode.node; export { DemoNode };n8n 加载自定义节点时并不是整个包按照普通 Node 模块逻辑去加载它会专门读取package.json里的n8n.nodes数组把这些路径拿到逐个 require。所以如果你漏掉了n8n字段或者路径写的和编译产物不一致那么 n8n 就会静默地跳过你的包界面上什么也看不到。3. 写一个真实节点企业微信机器人消息节点3.1 需求说明与字段设计我挑的这个例子很典型很多公司内部会搭一个企业微信群群里挂一个自定义机器人通过 Webhook 地址接收消息。业务人员希望 n8n 工作流跑完以后自动把结果推送到群里最好能支持“部分字段动态替换”“手动 某些人”这类需求。所以节点需求定义如下输入上游任意数据比如故障告警数据、订单通知数据。配置项一Webhook Key这个比较敏感我会放到 credentials 里后面讲。配置项二消息标题固定字符串也可以支持表达式比如“订单创建成功”。配置项三消息内容模板支持 n8n 表达式模板里能引用{{ $json.xxx }}。配置项四是否需要 所有人布尔开关。配置项五需要 的指定用户手机号列表固定列表逗号分隔。这些字段看起来很多但每个都很必要。字段设计阶段就要想清楚哪些应该暴露给普通用户哪些应该藏到凭据里比如 Webhook Key 属于敏感信息如果直接暴露在节点参数里用户导出工作流时 key 就会跟着导走肯定不行所以要设计成 credentials。消息内容模板之所以用表达式支持是为了让节点可以适应不同业务字段而不是写死字段名。3.2 在左侧配置面板node description 与 properties现在写src/nodes/WecomBot/WecomBot.node.ts。第一步是定义description让 n8n 把配置界面渲染出来。import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription, } from n8n-workflow; export class WecomBot implements INodeType { description: INodeTypeDescription { displayName: 企业微信机器人消息, name: wecomBot, group: [output], version: 1, description: 发送文本消息到企业微信群机器人, defaults: { name: 企业微信机器人消息, }, inputs: [main], outputs: [main], properties: [ { displayName: 消息标题, name: title, type: string, default: n8n 通知, required: true, description: 消息的标题部分, }, { displayName: 消息内容模板, name: contentTemplate, type: string, typeOptions: { rows: 5, }, default: 任务 {{ $json.taskName }} 已完成, description: 支持 n8n 表达式引用上游数据字段, }, { displayName: 所有人, name: atAll, type: boolean, default: false, }, { displayName: 指定 用户手机号列表, name: atMobileList, type: string, default: , placeholder: 13800000000,13900000000, displayOptions: { show: { atAll: [false], }, }, }, ], }; }这里有几个点值得展开说。第一type: string字段的default如果以开头n8n 会把它当成表达式处理比如default: 任务 {{ $json.taskName }} 已完成实际渲染出来的不是字面量而是表达式。第二displayOptions是非常实用的控制能力比如“指定 用户手机号列表”这个字段只有atAll为 false 时才显示这样界面不会把无字段一股脑堆给用户。第三group: [output]表示这个节点不会单独被当作触发器在画布上它会偏向右侧一般作为流程末尾的输出节点使用。3.3 执行逻辑execute() 内部的工作接下来是 execute 方法它是节点真正干活的入口。n8n 在运行时会调用它参数是this上下文里面包含节点参数、凭据、上游数据等。实现如下async execute(this: IExecuteFunctions): PromiseINodeExecutionData[][] { const items this.getInputData(); const returnData: INodeExecutionData[] []; for (let i 0; i items.length; i) { const title this.getNodeParameter(title, i) as string; const contentTemplate this.getNodeParameter(contentTemplate, i) as string; const atAll this.getNodeParameter(atAll, i, false) as boolean; const rawMobileList this.getNodeParameter(atMobileList, i, ) as string; const credentials await this.getCredentials(wecomWebhook); const webhookKey credentials.webhookKey as string; const item items[i]; const jsonData item.json; // 渲染模板中的表达式 const renderedTitle this.helpers.evaluateExpression(title, jsonData, i); const renderedContent this.helpers.evaluateExpression(contentTemplate, jsonData, i); let mobileList: string[] []; if (!atAll rawMobileList.trim() ! ) { mobileList rawMobileList.split(,).map((m) m.trim()); } const payload { msgtype: text, text: { content: ${renderedTitle}\n${renderedContent}, mentioned_list: mobileList, mentioned_mobile_list: atAll ? undefined : mobileList, }, }; // 发送请求 const response await this.helpers.httpRequest({ method: POST, url: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key${webhookKey}, headers: { Content-Type: application/json, }, body: payload, json: true, }); if (response.errcode response.errcode ! 0) { throw new Error(企业微信机器人发送失败: ${response.errmsg}); } returnData.push({ json: { success: true, response, originalItem: item.json, }, }); } return this.prepareOutputData(returnData); }这段代码有几个关键的设计决策。第一n8n 每次执行可能拿到多条数据items 是个数组所以必须用for循环逐条处理绝对不能只处理items[0]。我见过不少人只处理第一条平时数据单条没问题一旦上游批量输出就会静默丢数据。第二getNodeParameter的第二个参数是itemIndex它的语义是“从哪一个 item 上取参数”这允许每个 item 可以有不同的参数值当字段使用表达式并引用当前 item 时尤其重要。第三我在发送完以后再一次检查了errcode这是企业微信 API 的规范必须显式处理不能只依赖 HTTP 状态码。3.4 数据格式约定n8n 的 items 如何处理你应该注意到了我从 execute 方法返回的是PromiseINodeExecutionData[][]而INodeExecutionData的标准结构是interface INodeExecutionData { json: IDataObject; binary?: BinaryData; error?: NodeError; }n8n 的 executor 拿到这个返回值以后会把它拆成多个输出分支。不同输入分支的数量和顺序取决于你在 description 里怎么定义inputs和outputs。我们这个节点只有一个main输入和一个main输出所以返回的就是一个二维数组外层只有一个元素。你在returnData里 push 的对象最终会成为下游节点的$json内容。这里有个容易被忽略的细节this.prepareOutputData(returnData)会把 returnData 包一层。如果你不调用它而直接返回[returnData]大多数情况下也能工作但官方推荐统一用prepareOutputData因为它会处理空数据、丢失数据等边缘情况。4. 本地联调与调试把自定义节点挂到 n8n 里4.1 编译、链接或本地目录方式写完代码只是第一步真正让 n8n 加载到节点才是关键。常见做法有三种。第一种是本地目录映射。n8n 支持通过环境变量N8N_CUSTOM_EXTENSIONS指定自定义节点目录。比如你把编译好的dist目录设为一个固定路径然后启动 n8n 时加上这个环境变量N8N_CUSTOM_EXTENSIONS/home/me/n8n-nodes-demo/dist n8n start第二种是npm link。在节点项目根目录执行npm link然后在 n8n 项目里执行npm link n8n-nodes-demo再启动 n8n。这个方法的问题在于 n8n 官方文档更推荐使用自定义目录方式因为npm link在 Windows 上偶尔会有符号链接解析问题。第三种是直接放在 n8n 自带的 custom 目录。很多基于 Docker 部署的团队会把dist目录映射进容器里的/home/node/.n8n/nodes。我实际用下来最稳的是第一种加第三种结合本地开发用环境变量指向目录生产部署直接复制 dist 到容器节点目录。我自己在开发阶段的体验是先设置N8N_CUSTOM_EXTENSIONS指向编译输出目录然后用tsc --watch监听源码变化每次保存自动重新编译。不过要注意n8n 只在启动时扫描自定义节点所以编译完成后必须重启 n8n 才能看到新改动。4.2 在 n8n 工作流里加载与测试n8n 重启完成之后你在画布上新建节点搜索“企业微信机器人”应该就能搜到它了。我建议测试流程用三段式开始节点用 Manual Trigger 或 Webhook 节点- 你新写的节点 - 一个 Set 节点看一下下游拿到什么数据。以本地测试为例你可以用 n8n 自带的Execute Workflow按钮它会跑整个流程然后把每一步的 input/output 展示在右侧面板上。对自定义节点的测试我习惯这样操作先只把输入节点和自己的节点连起来不要连下游这样专门看这个节点的输出。点击 Execute Node只看当前节点的执行结果。在输出面板里展开json检查布尔字段、数组字段是否符合预期。测试时最常遇到的问题是表达式模板渲染错误。比如{{ $json.taskName }}如果上游数据里没有taskName字段模板渲染得到的是空字符串但节点不会报错肉眼很难察觉。所以我给内容模板字段加了required: false然后又在 execute 里做一次判断如果渲染结果为空就抛一个明确的错误提示。4.3 看日志、断点与常见错误定位n8n 自身有日志输出。你在命令行启动 n8n 时控制台会打印每个节点执行时的错误堆栈。当你发现节点执行失败但界面提示又不够明确时第一件事就是看启动 n8n 的终端窗口错误信息通常就藏在里面。如果你在 execute 方法里写console.log这些输出会直接出现在 n8n 服务端的 stdout 里不会展示在浏览器界面。所以本地调试我也经常用console.log来观察中间变量尤其是凭据对象结构、模板渲染结果这些界面看不到的东西。比 console.log 更高效的办法是在代码里使用try/catch把关键步骤包起来把错误信息连同这段上下文一起抛到前端比如try { const response await this.helpers.httpRequest({...}); } catch (error) { throw new Error(企业微信请求失败原始错误: ${error.message}); }这样 n8n 的执行面板会直接把友好错误信息展示给用户而不是只给一个抽象的 “Request failed with status code 400”。这一点对团队协作特别重要因为别人不见得愿意去翻服务端日志。5. 进阶credentials、市场发布与版本维护5.1 给节点加上敏感信息凭据企业微信的 Webhook Key 算是轻度敏感信息但你肯定不希望它被写死在工作流里。n8n 的凭据系统可以帮你管理这类密钥。实现凭据也分两步定义类型描述以及在 execute 里读取。第一步在src/credentials/WecomWebhook.credentials.ts里定义一个凭据类import { ICredentialType, INodeProperties } from n8n-workflow; export class WecomWebhook implements ICredentialType { name wecomWebhook; displayName 企业微信机器人 Webhook; properties: INodeProperties[] [ { displayName: Webhook Key, name: webhookKey, type: string, default: , required: true, typeOptions: { password: true, }, }, ]; }typeOptions: { password: true }会让输入框以密码形式展示避免别人围观时泄露。第二步在节点 description 里增加credentials字段credentials: [ { name: wecomWebhook, required: true, }, ],然后 execute 里通过this.getCredentials(wecomWebhook)读取。读取到的对象里webhookKey就是用户填的那个值。很多新手会问凭据到底怎么保存的简单说n8n 会把凭据加密存储在一个本地数据库中不放进工作流 JSON。所以你导出工作流、分享给别人时密钥不会跟着走。别人使用这个节点时必须自己创建一份凭据并关联到节点上。5.2 发布到 npm 与 n8n 社区节点目录节点开发和测试完成之后你可以选择只在自己团队内部使用或者发布到 npm 供更多人使用。发布 npm 包没有什么特别的就是npm publish。但我建议先确认包名。n8n 社区约定的命名规则是n8n-nodes-你的功能比如n8n-nodes-wecom-bot。如果你的包没有以n8n-nodes-开头n8n 的社区节点搜索一般不会收录它。发布后如果你希望节点出现在 n8n 的 Community Nodes 列表里需要到 n8n 的社区节点仓库提交一份 PR把 npm 包地址加进去。这个过程一般要求你提供带 logo 的图标、README 文档、以及测试通过证明。我的建议是如果没有强烈的对外分发需求可以先在自己的私有 npm registry 或者直接打包 tar 文件给团队使用没必要过早提交社区审核。5.3 版本兼容n8n API 版本变化n8n 本身迭代很快节点 API 也在变。我第一次开发的节点是为 n8n 0.x 写的后来升级到 1.x发现部分方法签名变了。比如早期INodeType里某些字段的位置有调整。所以你在写节点时最好把n8n-workflow和n8n-core的版本锁定在某个范围内并且在 package.json 里使用 peerDependencies 声明兼容的 n8n 版本范围。发布新版本时记得同步修改n8n字段里的version和你包本身的version。n8n 加载节点的逻辑是如果工作流里保存的节点version是 1而你发布的包只支持 version 2那么老工作流在升级后会遇到兼容性问题。解决方法是尽量在同一个version: 1里做向后兼容非必要不 bump 大版本。6. 我踩过的坑与提速建议6.1 开发阶段一定要先想清楚的任务边界我第一个自定义节点是拍脑袋从“给某个内部系统写一个完整的业务节点”开始的。结果那个系统本身 API 文档不清晰参数边界一直在变我反反复改写了两周也没有稳定下来。后来我换了一种思路每次只封装一个非常小的能力比如“读取某个配置中心的一个配置项”一天就搞定了。所以我的第一个建议是第一版自定义节点要做窄不要试图一口吃成业务全集。你可以在节点内部把业务逻辑写厚但暴露出来的输入输出要尽量简单。比如我上面那个企业微信机器人消息节点它只处理文本消息不处理图片、文件、markdown。一开始有人劝我把所有消息类型都做了我明确拒绝因为一旦支持 markdown字段和布尔开关就会多好几倍维护成本立刻上升。6.2 类型定义别过度设计n8n 的字段类型有很多string、number、boolean、options、collection、fixedCollection等等。选项和集合类型确实能构建很漂亮的界面但代价是代码复杂度成倍上升。比如fixedCollection支持嵌套多个分组你在 execute 里拿到的数据结构经常要跟“默认值是否存在”做各种if判断。我的建议是能用简单类型表达的需求绝不使用集合类型。等用户真实使用之后你有足够数据证明哪个字段组合是常见的再升级成集合也来得及。6.3 测试场景覆盖自测不能只测“正常情况”。在企业微信那个例子里我至少测过以下几种异常场景Webhook Key 为空、内容模板引用了不存在的字段、上游传入 0 条数据、上游传入 1000 条数据、企业微信接口超时。尤其是空数据这个场景很隐蔽如果上游节点在条件不满足时不产生任何输出你的 execute 方法会拿到一个空数组for循环就不会执行返回的也是空数组。这在业务上可能符合预期但也可能让你误以为节点没被调用。所以我在 execute 开头加了一行日志逻辑记录输入条数方便排查。再有一个常见坑是响应体积过大或超时。企业微信 Webhook 对消息内容有长度限制超过 2048 字节会返回错误。这种限制属于外部 API 的硬约束你最好在代码里明确检查并抛出可读错误而不是把原始文本整个塞进去等对方驳回。我在生产上遇到过一次消息模板里拼了一个很大的 JSON 字符串结果发送失败排查了半小时才发现是长度问题。6.4 调试技巧最后分享一个比较进阶的调试技巧在 execute 里故意抛一个错误观察 n8n 用什么错误格式展示。n8n 对节点错误处理很宽容节点抛出的错误会被包装成ExecutionError展示在执行面板里。如果你在内部 catch 以后返回{ json: { error: ... } }那么这个错误不会停止流程而会当作正常数据往下游传递。这两个行为的业务意义完全不同。我开发的节点里有个内部配置用来控制“发送失败是继续还是中断整个工作流”。实现方式就是失败时根据配置决定是throw还是 push 一条包含error字段的 json。这个设计在数据抽取类任务里特别重要你不想因为一条脏数据中断整批次处理但你希望在出现系统性问题时快速暴露。写在后面的一些经验文章写到这我想你已经能跟着搭出一个可以运行的自定义节点了。如果让我用一句话总结这个过程的难点那就是“n8n 的节点开发本身不难难的是你想清楚它到底应该解决什么问题”。我自己技能提升最快的阶段不是在看文档的时候而是被生产环境逼着给节点加日志、加超时、加重试、加版本兼容的那几周。所以建议你也别等到把文档全部看懂才开始选一个真实工作中的小需求从一个只做一件事的节点开始跑通以后你会发现之前很多靠拼装内置节点绕路的地方现在都变得特别直接。最后分享一个小技巧每次改完节点发布新版本之前手动把node_modules里的旧包清干净再安装很多“为什么改了但没生效”的诡异问题都出在缓存上。我吃过这个亏就不止一次。