n8n 社区节点创建
构建生产就绪的 n8n 社区节点作为 npm 包。该技能涵盖了声明式（REST API 封装）和程序式（自定义逻辑）节点样式。
参考：CREDENTIAL_PATTERNS.md | TRIGGER_PATTERNS.md | EXAMPLES.md | COMMON_MISTAKES.md
快速参考：声明式与程序式方面
声明式 | 程序式
适合 | 简单的 REST API 封装 | 自定义逻辑、转换、多次调用流
HTTP 处理 | 自动通过路由键 | 在 execute() 方法中手动
关键属性 | requestDefaults 在描述中 | 异步 execute() 方法
需要导入 | INodeType, INodeTypeDescription + IExecuteFunctions, INodeExecutionData
复杂度 | 较低 — 声明路由，n8n 处理请求 | 较高 — 对执行的完全控制
分页 | 通过 operations.pagination 配置 | 在 apiRequestAllItems 辅助函数中手动循环
何时选择 | API 与操作 1:1 映射，无转换 | 需要数据操作、条件逻辑或链式调用
决策规则：如果每个操作都是一个简单的 HTTP 请求，具有简单的输入 → 正文映射，并且响应可以按原样使用（或带有轻微的 postReceive 转换），则使用声明式。否则，使用程序式。
入门
重要：始终从克隆官方 n8n-nodes-starter 存储库开始。不要从头开始搭建一个项目。启动器提供了 n8n 期望的正确 TypeScript 配置、构建工具、linting 和项目结构。
- 克隆 n8n-nodes-starter（强制第一步）
# 克隆官方启动器 — 这是第一步
git clone https://github.com/n8n-io/n8n-nodes-starter.git n8n-nodes-
cd n8n-nodes-
# 删除启动器的 git 历史记录并重新初始化
rm -rf .git
git init
# 安装依赖
npm install
启动器存储库提供：
针对 n8n 的预配置 tsconfig.json，具有正确的编译器选项
具有构建脚本（build、dev、lint、lintfix）的工作包 json
与 n8n 约定匹配的 ESLint/Prettier 配置
可以用作起始参考的示例节点和凭证文件
在 package.json 中指向 dist/ 输出的正确 n8n 对象结构
克隆后，将示例节点和凭证文件重命名/替换为您自己的，并在 package.json 中更新包名称（n8n-nodes-）、描述和 n8n.nodes / n8n.credentials 数组。
文件 | 目的
nodes//.node.ts | 主节点类（逻辑 + 描述）
nodes//.node.json | 编码文件（类别、文档链接）
nodes//.svg | 节点图标（SVG，推荐 60×60px）
credentials/Api.credentials.ts | 凭证/身份验证定义
package.json | npm 配置，链接 n8n 对象节点和凭证
关键规则：
npm 包名称必须以 n8n-nodes- 开头
类名称必须与文件名匹配（类 MyService → MyService.node.ts）
图标文件名为小写（myservice.svg）
{
"name": "n8n-nodes-myservice",
"version": "0.1.0",
"n8n": {
"n8nNodesApiVersion": 1,
"nodes": [
"dist/nodes/MyService/MyService.node.js"
],
"credentials": [
"dist/credentials/MyServiceApi.credentials.js"
]
}
}
节点类结构
每个节点都实现了 INodeType，并带有一个描述对象：
import { INodeType, INodeTypeDescription, NodeConnectionType } from 'n8n-workflow';
export class MyService implements INodeType {
description: INodeTypeDescription = {
displayName: 'My Service',
name: 'myService',
icon: 'file:myservice.svg',
group: ['transform'],
version: 1,
subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
description: '与 My Service API 交互',
defaults: {
name: 'My Service'
},
inputs: [NodeConnectionType.Main],
outputs: [NodeConnectionType.Main],
credentials: [
{
name: 'myServiceApi',
required: true
},
],
properties: [
// 资源和操作选择器，然后是参数字段
],
};
}
必需的描述属性
属性 | 类型 | 注释
displayName | string | 在节点面板中显示
name | string | 内部 ID，跨所有节点唯一
icon | string | 'file:icon.svg' — 引用节点文件夹中的 SVG
group | string[] | ['transform']、['output']、['input'] 或 ['trigger']
version | number | 从 1 开始，破坏性更改时递增
subtitle | string | 节点名称下方显示的表达式模板
description | string | 节点面板的简要一句话
defaults | object | { name: '显示名称' }
inputs | array | [NodeConnectionType.Main] — 空 [] 表示触发器
outputs | array | [NodeConnectionType.Main]
credentials | array | [{ name: 'credName', required: true }]
properties | INodeProperties[] | UI 字段 — 资源、操作、参数
资源和操作模式
组织具有多个 API 资源的节点的标准方式：
properties: [
// 1. 资源选择器
{
displayName: '资源',
name: 'resource',
type: 'options',
noDataExpression: true, // 必须在资源/操作选择器上
options: [
{
name: '联系人',
value: 'contact'
},
by