还在用 HTTP 节点“凑合”？是时候手搓一个专属节点了
做 n8n 自动化的时候，你是不是经常遇到这种情况：想对接一个新工具，翻遍了官方节点库，没找到；退而求其次，用 HTTP Request 节点硬写 API 调用。参数要手动拼 JSON，返回结果还得用 Set 节点一层层解析。
凑合能用，但体验极差。每次复用都得重新配置，既不优雅，维护起来也头疼。
作为 N8N大学 的主编，我必须告诉你一个硬核事实：n8n 最强大的地方，不是它自带了多少节点，而是它允许你**造节点**。今天，笔者就带你从零开始，手写一个真正的 n8n 核心节点。这不仅能解决你的特定需求，更是你进阶 n8n 高手的必修课。
准备工作：磨刀不误砍柴工
在开始写代码之前，我们需要准备一个标准的开发环境。这并不复杂，但每一个工具都有它的用处。
- Node.js (v16+)：这是 n8n 运行的基础，也是我们开发节点的语言环境。建议安装 LTS 版本。
- Git：用于拉取 n8n 的官方仓库模板。
- 代码编辑器：VS Code 是笔者的首选，它的 TypeScript 提示非常友好。
- 一个 n8n 实例：本地开发最好使用源码启动的 n8n，方便调试。
这里有一个新手常犯的错误：直接在 n8n 的 Docker 容器里开发。强烈不建议这样做，文件挂载和权限问题会让你痛不欲生。请直接在宿主机上克隆 n8n 的源码仓库。
核心实操：从“复制粘贴”到“创造节点”
我们将以开发一个“简易汇率查询”节点为例。虽然市面上可能有类似的节点，但亲手造一个，你才能掌握它的灵魂。
步骤一：克隆官方模板并初始化
n8n 团队非常贴心，提供了一个官方的节点开发模板仓库。打开终端，执行以下命令：
git clone https://github.com/n8n-io/n8n-nodes-starter.git
进入目录，安装依赖：
cd n8n-nodes-starter
npm install
这个模板仓库已经帮我们配置好了 TypeScript 环境和打包工具。你只需要专注于编写业务逻辑即可。
步骤二：定义节点描述符 (Node Descriptor)
在 n8n 的架构中，节点是由一个 JSON 对象描述的。它决定了节点在画布上长什么样，以及有哪些参数。在 nodes 目录下创建一个新文件，比如 Currency.node.ts。
我们需要定义它的基本属性：
- displayName：节点在界面显示的名字（如“汇率查询”）。
- name：节点的内部标识符（如“currency”）。
- icon：节点的图标，可以使用 n8n 内置的图标库。
- inputs/outputs：定义节点的输入输出端口。
代码结构大致如下：
export class Currency implements INodeType {
description: INodeTypeDescription = {
displayName: '汇率查询',
name: 'currency',
icon: 'fa:exchange-alt',
color: '#00FF00',
inputs: ['main'],
outputs: ['main'],
properties: [
// 这里定义参数
],
};
}
步骤三：编写参数配置与逻辑处理
这是最关键的一步。我们需要在 properties 数组中定义用户可配置的字段。例如，我们需要用户输入“基础币种”和“目标币种”。
n8n 提供了丰富的 UI 组件，比如 string（文本框）、options（下拉框）等。为了演示，我们用下拉框让用户选择币种。
接下来，我们需要编写 execute 方法。这是节点运行时的核心逻辑。在这里，我们调用外部 API（比如免费的汇率接口），获取数据，并通过 items.push() 将结果传递给下一个节点。
笔者提示：在编写逻辑时，请务必处理好异步操作。n8n 节点的
execute方法必须返回 Promise 或使用 async/await。
步骤四：编译与本地调试
代码写好了，如何让它出现在 n8n 的界面里？
我们需要修改 package.json，添加节点的引用。然后运行构建命令：
npm run build
构建完成后，你会得到一个 dist 目录。此时，你需要在启动 n8n 时，通过环境变量告诉 n8n 去哪里找这个新节点：
export N8N_NODES_CUSTOM=/path/to/your/n8n-nodes-starter/dist
n8n start
重启 n8n，打开画布，搜索“汇率”，你亲手打造的节点应该已经静静躺在那里了。
避坑指南：新手最容易踩的坑
开发节点看似简单，但实际操作中总有几个“隐形陷阱”。
1. TypeScript 类型地狱
n8n 大量使用 TypeScript。如果你在编写 execute 方法时，对 items 或 nodeData 的类型理解不深，编辑器会爆出满屏红字。建议多参考官方节点的源码（在 n8n 仓库的 packages/nodes-base 目录下），模仿它们的写法。
2. 环境变量没生效
修改了代码，编译了，但 n8n 界面里没出现新节点？90% 的情况是环境变量没设置对，或者 n8n 进程没有重启。Docker 用户更要注意，需要把本地的 custom nodes 目录映射到容器内，并正确设置 N8N_NODES_CUSTOM。
3. 依赖缺失
如果你的节点需要第三方库（比如 axios 或 lodash），一定要在模板仓库的 package.json 里安装并添加到 dependencies 中，否则编译后的代码在 n8n 运行时会报 Module not found。
FAQ 问答
Q1: 我不懂 TypeScript，能开发 n8n 节点吗？
虽然 n8n 是用 TypeScript 写的，但如果你只是写一些简单的逻辑，JavaScript 也是可以的。不过，笔者强烈建议你学习 TypeScript 的基础。因为 n8n 的类型定义非常完善，利用好类型提示能帮你避免很多运行时错误。
Q2: 开发好的节点可以发布吗？
当然可以！这正是 n8n 社区的魅力所在。你可以将节点打包发布到 npm，然后分享给社区。N8N大学 也在整理优秀的第三方节点库，欢迎提交你的作品。
Q3: 为什么我的节点在界面上没有图标？
检查 description 中的 icon 属性。n8n 支持 FontAwesome 和 Material Icons。如果你的图标名字拼写错误，或者使用了不支持的图标库，节点就会显示默认的方块图标。
总结与资源
从使用 HTTP Request 节点“凑合”，到手写一个专属节点，这不仅是技术的提升，更是思维的转变。你不再受限于现有的工具，而是开始创造工具。
虽然开发过程需要一点耐心，尤其是面对 TypeScript 和复杂的配置时。但一旦你的节点跑通，那种成就感是无与伦比的。
参考资料：
- n8n 官方文档 - Nodes Development
- N8N大学 - 进阶开发实战教程 (n8ndx.com)
我是 N8N大学 的首席主编，致力于让自动化触手可及。如果你在开发过程中遇到任何报错，欢迎随时回来查阅本文，或者在社区留言。
