n8n自定义节点完全指南：从社区节点到自主开发

n8n作为一款强大的工作流自动化工具，其节点系统是其核心功能之一。虽然n8n已经内置了大量实用节点，但有时我们仍需要使用自定义节点来满足特定需求。本文将详细介绍n8n中自定义节点的两种使用方式：社区节点和自主开发节点，帮助您扩展n8n的功能边界。

什么是n8n自定义节点？

在n8n中，"自定义节点"通常指两类东西：

1. 社区节点（Community Node）：别人已经写好并发布到npm的包，您只需在UI里一键安装即可使用。
2. 自己开发的节点（Custom Node Package）：完全由您编写，发布到私有或公共npm，然后像社区节点一样安装。

下面我们将分别说明这两种做法的具体步骤。

一、使用别人已经写好的社区节点（最简单）

使用社区节点是扩展n8n功能最简单的方式，无需编写任何代码，只需几个简单步骤即可完成安装和使用。

安装步骤：

1. 打开n8n的「Settings → Community Nodes」。
2. 点击「Install」，输入包名（例如@n8n/n8n-nodes-telegram）。
3. 安装完成后刷新页面，左侧节点面板就会出现新节点。

注意：

• 社区节点必须发布到npm，且包名以n8n-nodes-开头。
• 如果您用的是n8n Cloud，官方白名单之外的包无法安装；需要自建或本地Docker。

二、开发并安装自己的节点（完整流程）

当社区节点无法满足您的特定需求时，开发自己的自定义节点是理想选择。下面是完整的开发流程。

1. 准备环境

# 全局安装脚手架
npm install -g n8n-node-dev

2. 生成节点骨架

n8n-node-dev new
# 交互式填写：节点名称、作者、描述等
# 会在当前目录生成一个文件夹，例如 n8n-nodes-myfirst

3. 编写节点逻辑

进入目录后主要改两个文件：

• nodes/MyFirst/MyFirst.node.ts：节点核心逻辑（输入参数、API调用、返回数据）。
• package.：确认"name"以n8n-nodes-开头，例如"n8n-nodes-myfirst"。

4. 本地调试（Docker场景）

把节点挂到n8n容器里：

# 假设你项目目录在 ~/n8n-nodes-myfirst
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/n8n-nodes-myfirst:/home/node/.n8n/custom \
  -e N8N_CUSTOM_EXTENSIONS=/home/node/.n8n/custom \
  docker.n8n.io/n8nio/n8n

启动后访问 http://localhost:5678，左侧就能看到您的节点。

5. 发布到npm（可选）

npm login
npm publish

发布后，任何n8n实例都可以通过「Community Nodes」安装您的包。

6. 私有仓库安装（不想公开）

自建Verdaccio或GitHub Packages，然后在n8n容器里配置registry：

npm config set registry https://your-registry.example.com
npm install -g n8n-nodes-myfirst

三、常见问题速查

节点图标不显示在节点目录放icon.svg或icon.png，并在.node.ts里icon: 'file:icon.svg'。节点不生效确认包名前缀、确认N8N_CUSTOM_EXTENSIONS路径正确、重启容器。需要调用第三方SDK在节点目录正常npm install axios等依赖即可，n8n会自动打包。

总结

通过本文，我们了解了n8n自定义节点的两种使用方式："社区节点"= npm安装即用；"自定义节点"= 用n8n-node-dev生成骨架 → 写代码 → 挂到容器 → 发布/安装。无论您是希望快速扩展n8n功能，还是需要开发特定解决方案，自定义节点都能为您提供强大支持。希望本文能帮助您更好地利用n8n构建自动化工作流！