n8n智能体开发：构建声明式节点

本教程将引导您构建一个声明式风格的节点。开始之前，请确认这是您需要的节点类型。更多信息请参考选择节点构建方法。

王国平

405人浏览 · 2025-11-01 07:24:58

王国平 · 2025-11-01 07:24:58 发布

本教程将引导您构建一个声明式风格的节点。开始之前，请确认这是您需要的节点类型。更多信息请参考选择节点构建方法。

先决条件#

您的开发机器上需要安装以下软件：

git
Node.js 和 npm。最低版本要求 Node 18.17.0。Linux、Mac 和 WSL 用户可以通过 nvm (Node Version Manager) 安装，具体步骤参见此处。Windows 用户请参考微软的在 Windows 上安装 NodeJS指南。

您需要了解以下知识：

JavaScript/TypeScript
REST API
git

构建您的节点#

在本节中，您将克隆 n8n 的节点启动仓库，并构建一个集成 NASA API 的节点。您将创建一个使用 NASA 两项服务的节点：APOD（每日天文图片）和火星探测器照片。为了保持代码示例简洁，该节点不会实现火星探测器照片端点的所有可用选项。

现有节点

n8n 已内置了一个 NASA 节点。为避免与现有节点冲突，您需要为您创建的版本使用不同的名称。

第一步：项目设置#

n8n 为节点开发提供了一个启动仓库。使用这个启动模板能确保您拥有所有必要的依赖项，同时还提供了代码检查工具。

克隆仓库并进入目录：

从模板仓库生成新仓库

克隆您的新仓库：

git clone https://github.com/<your-organization>/<your-repo-name>.git n8n-nodes-nasa-pics
cd n8n-nodes-nasa-pics

启动模板包含示例节点和凭据。请删除以下目录和文件：

nodes/ExampleNode
nodes/HTTPBin
credentials/ExampleCredentials.credentials.ts
credentials/HttpBinApi.credentials.ts

现在创建以下目录和文件：

nodes/NasaPics
nodes/NasaPics/NasaPics.node.json
nodes/NasaPics/NasaPics.node.ts
credentials/NasaPicsApi.credentials.ts

这些是任何节点所需的关键文件。更多关于必需文件和推荐组织方式的信息，请参考节点文件结构。

现在安装项目依赖：

npm i

第二步：添加图标#

从这里下载 NASA SVG 标志，保存为 nodes/NasaPics/nasapics.svg。

n8n 推荐使用 SVG 格式作为节点图标，但也可以使用 PNG 格式。如果使用 PNG，图标分辨率应为 60x60 像素。节点图标应保持正方形或接近正方形的宽高比。

不要引用 Font Awesome

如果要在节点中使用 Font Awesome 图标，请下载并嵌入该图像。

第三步：创建节点#

每个节点都必须有一个基础文件。有关基础文件参数的详细信息，请参考节点基础文件。

在本示例中，文件名为 NasaPics.node.ts。为了使本教程简洁，我们将所有节点功能都放在这一个文件中。当构建更复杂的节点时，您应考虑将功能拆分到不同模块中。更多信息请参阅节点文件结构。

第三步.1：导入声明#

首先添加导入语句：

import { INodeType, INodeTypeDescription } from 'n8n-workflow';

第三步.2：创建主类#

节点必须导出一个实现 INodeType 的接口。该接口必须包含 description 接口，而该接口又包含 properties 数组。

类名与文件名

确保类名与文件名匹配。例如，给定类名 NasaPics，则文件名必须为 NasaPics.node.ts。

export class NasaPics implements INodeType {
	description: INodeTypeDescription = {
		// 基础节点信息将放在这里
		properties: [
		// 资源和操作将放在这里
		]
	};
}

步骤 3.3：添加节点详情#

所有节点都需要一些基本参数，例如显示名称、图标以及使用该节点发起请求的基本信息。在 description 中添加以下内容：

displayName: 'NASA Pics',
name: 'NasaPics',
icon: 'file:nasapics.svg',
group: ['transform'],
version: 1,
subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
description: '从NASA API获取数据',
defaults: {
	name: 'NASA Pics',
},
inputs: ['main'],
outputs: ['main'],
credentials: [
	{
		name: 'NasaPicsApi',
		required: true,
	},
],
requestDefaults: {
	baseURL: 'https://api.nasa.gov',
	headers: {
		Accept: 'application/json',
		'Content-Type': 'application/json',
	},
},

n8n 使用 description 中设置的某些属性在编辑器 UI 中渲染节点。这些属性包括 displayName、icon、description 和 subtitle。

步骤 3.4：添加资源#

资源对象定义了节点使用的 API 资源。在本教程中，您将创建一个访问 NASA 两个 API 端点的节点：planetary/apod 和 mars-photos。这意味着您需要在 NasaPics.node.ts 中定义两个资源选项。更新 properties 数组中的资源对象：

properties: [
	{
		displayName: '资源',
		name: 'resource',
		type: 'options',
		noDataExpression: true,
		options: [
			{
				name: '每日天文图片',
				value: 'astronomyPictureOfTheDay',
			},
			{
				name: '火星探测器照片',
				value: 'marsRoverPhotos',
			},
		],
		default: 'astronomyPictureOfTheDay',
	},
	// 操作选项将放在这里

]

type 控制 n8n 为资源显示的 UI 元素，并告知 n8n 预期从用户那里接收的数据类型。options 会导致 n8n 添加一个下拉菜单，允许用户选择一个选项。更多信息请参考节点UI元素。

步骤 3.5：添加操作#

operations 对象定义了资源上可用的操作。

在声明式节点中，operations 对象包含 routing（位于 options 数组内）。这部分设置了 API 调用的详细信息。

在 resource 对象之后，向 properties 数组添加以下内容：

{
	displayName: '操作',
	name: 'operation',
	type: 'options',
	noDataExpression: true,
	displayOptions: {
		show: {
			resource: [
				'astronomyPictureOfTheDay',
			],
		},
	},
	options: [
		{
			name: '获取',
			value: 'get',
			action: '获取 APOD',
			description: '获取当天的天文图片',
			routing: {
				request: {
					method: 'GET',
					url: '/planetary/apod',
				},
			},
		},
	],
	default: 'get',
},
{
	displayName: '操作',
	name: 'operation',
	type: 'options',
	noDataExpression: true,
	displayOptions: {
		show: {
			resource: [
				'marsRoverPhotos',
			],
		},
	},
	options: [
		{
			name: '获取',
			value: 'get',
			action: '获取火星探测器照片',
			description: '从火星探测器获取照片',
			routing: {
				request: {
					method: 'GET',
				},
			},
		},
	],
	default: 'get',
},
{
	displayName: '探测器名称',
	description: '选择要从哪个火星探测器获取照片',
	required: true,
	name: 'roverName',
	type: 'options',
	options: [
		{name: 'Curiosity', value: 'curiosity'},
		{name: 'Opportunity', value: 'opportunity'},
		{name: 'Perseverance', value: 'perseverance'},
		{name: 'Spirit', value: 'spirit'},
	],
	routing: {
		request: {
			url: '=/mars-photos/api/v1/rovers/{{$value}}/photos',
		},
	},
	default: 'curiosity',
	displayOptions: {
		show: {
			resource: [
				'marsRoverPhotos',
			],
		},
	},
},
{
	displayName: '日期',
	description: '地球日期',
	required: true,
	name: 'marsRoverDate',
	type: 'dateTime',
	default:'',
	displayOptions: {
		show: {
			resource: [
				'marsRoverPhotos',
			],
		},
	},
	routing: {
		request: {
			// 您已经设置了 URL。qs 将字段值作为查询字符串附加
			qs: {
				earth_date: '={{ new Date($value).toISOString().substr(0,10) }}',
			},
		},
	},
},
// 可选/附加字段将放在这里

这段代码创建了两个操作：一个用于获取当天的 APOD 图片，另一个用于发送获取火星探测器照片的 GET 请求。名为 roverName 的对象要求用户选择他们想要获取照片的火星探测器。火星探测器操作中的 routing 对象引用此值来创建 API 调用的 URL。

步骤 3.6：可选字段#

大多数 API（包括本示例中使用的 NASA API）都包含可选字段，可用于优化查询。

为避免用户界面过于复杂，n8n 将这些字段显示在 UI 的 Additional Fields（附加字段）部分。

在本教程中，您将添加一个附加字段，允许用户为 APOD 端点选择日期。将以下代码添加到 properties 数组中：

{
	displayName: 'Additional Fields',
	name: 'additionalFields',
	type: 'collection',
	default: {},
	placeholder: 'Add Field',
	displayOptions: {
		show: {
			resource: [
				'astronomyPictureOfTheDay',
			],
			operation: [
				'get',
			],
		},
	},
	options: [
		{
			displayName: 'Date',
			name: 'apodDate',
			type: 'dateTime',
			default: '',
			routing: {
				request: {
					// 您已经设置了 URL。qs 会将字段值作为查询字符串附加
					qs: {
						date: '={{ new Date($value).toISOString().substr(0,10) }}',
					},
				},
			},
		},
	],									
}

步骤4：设置认证#

NASA API 要求用户使用 API 密钥进行认证。

将以下代码添加到 nasaPicsApi.credentials.ts 文件中：

import {
	IAuthenticateGeneric,
	ICredentialType,
	INodeProperties,
} from 'n8n-workflow';

export class NasaPicsApi implements ICredentialType {
	name = 'NasaPicsApi';
	displayName = 'NASA Pics API';
	// 使用本教程链接作为示例
	// 构建自己的节点时请替换为您自己的文档链接
	documentationUrl = 'https://docs.n8n.io/integrations/creating-nodes/build/declarative-style-node/';
	properties: INodeProperties[] = [
		{
			displayName: 'API Key',
			name: 'apiKey',
			type: 'string',
			default: '',
		},
	];
	authenticate = {
		type: 'generic',
		properties: {
			qs: {
				'api_key': '={{$credentials.apiKey}}'
			}
		},
	} as IAuthenticateGeneric;
}

有关凭据文件和选项的更多信息，请参阅凭据文件。

步骤5：添加节点元数据#

关于节点的元数据存储在节点根目录下的 JSON 文件中。n8n 将其称为 codex 文件。在本示例中，文件名为 NasaPics.node.json。

将以下代码添加到 JSON 文件中：

{
	"node": "n8n-nodes-base.NasaPics",
	"nodeVersion": "1.0",
	"codexVersion": "1.0",
	"categories": [
		"Miscellaneous"
	],
	"resources": {
		"credentialDocumentation": [
			{
				"url": ""
			}
		],
		"primaryDocumentation": [
			{
				"url": ""
			}
		]
	}
}

有关这些参数的更多信息，请参阅节点 codex 文件。

步骤6：更新 npm 包信息#

您的 npm 包信息位于项目根目录的 package.json 文件中。必须包含带有凭证和基础节点文件链接的 n8n 对象。更新该文件以包含以下信息：

{
	// 所有节点名称必须以 "n8n-nodes-" 开头
	"name": "n8n-nodes-nasapics",
	"version": "0.1.0",
	"description": "用于调用 NASA APOD 和火星探测器照片服务的 n8n 节点",
	"keywords": [
		// 此关键词是社区节点必需的
		"n8n-community-node-package"
	],
	"license": "MIT",
	"homepage": "https://n8n.io",
	"author": {
		"name": "Test",
		"email": "test@example.com"
	},
	"repository": {
		"type": "git",
		// 将 git 远程仓库更改为您自己的仓库
		// 在此处添加新的 URL
		"url": "git+<your-repo-url>"
	},
	"main": "index.js",
	"scripts": {
		// 无需更改
	},
	"files": [
		"dist"
	],
	// 链接凭证和节点
	"n8n": {
		"n8nNodesApiVersion": 1,
		"credentials": [
			"dist/credentials/NasaPicsApi.credentials.js"
		],
		"nodes": [
			"dist/nodes/NasaPics/NasaPics.node.js"
		]
	},
	"devDependencies": {
		// 无需更改
	},
	"peerDependencies": {
		// 无需更改
	}
}

您需要更新 package.json 以包含您自己的信息，例如您的姓名和仓库 URL。有关 npm package.json 文件的更多信息，请参阅 npm 的 package.json 文档。

测试您的节点#

在构建节点时，您可以通过在本地 n8n 实例中运行来测试它。

使用 npm 安装 n8n：
npm install n8n -g

准备测试节点时，将其发布到本地：

# 在您的节点目录中
npm run build
npm link

将节点安装到本地 n8n 实例：
# 在 n8n 安装目录内的 nodes 文件夹中 # node-package-name 是 package.json 中的名称 npm link <node-package-name>
检查目录

确保您在 n8n 安装目录内的 nodes 文件夹中运行 npm link <node-name>。可能的路径包括：
- ~/.n8n/custom/
- ~/.n8n/<your-custom-name>：如果您的 n8n 安装使用 N8N_CUSTOM_EXTENSIONS 设置了不同的名称。
启动 n8n：
n8n start
在浏览器中打开 n8n。在节点面板中搜索时应该能看到您的节点。

节点名称

请确保使用节点名称而非包名称进行搜索。例如，如果您的 npm 包名是 n8n-nodes-weather-nodes，而包中包含名为 rain、sun、snow 的节点，您应该搜索 rain 而不是 weather-nodes。

故障排除#

本地安装的 ~/.n8n 中没有 custom 目录

您需要手动创建 custom 目录并运行 npm init

# 在 ~/.n8n 目录中运行
mkdir custom 
cd custom 
npm init

后续步骤#

部署您的节点
查看声明式节点示例：n8n 的 Brevo 节点。请注意主节点采用声明式，而触发器节点采用编程式风格
了解节点版本控制

《DeepSeek高效数据分析：从数据清洗到行业案例》聚焦DeepSeek在数据分析领域的高效应用，是系统讲解其从数据处理到可视化全流程的实用指南。作者结合多年职场实战经验，不仅深入拆解DeepSeek数据分析的核心功能——涵盖数据采集、清洗、预处理、探索分析、建模（回归、聚类、时间序列等）及模型评估，更通过金融量化数据分析、电商平台数据分析等真实行业案例，搭配报告撰写技巧，提供独到见解与落地建议。助力职场人在激烈竞争中凭借先进技能突破瓶颈，实现职业进阶，开启发展新篇。