N8N HelloWorld Demo 插件项目

这是一个完整的N8N自定义节点项目，用于演示如何创建、开发和发布N8N社区节点。该插件提供简单的问候消息功能，支持多种问候风格和时间戳选项。

📋 目录

• 项目概述
• 功能特性
• 项目结构
• 文件详解
• 安装使用
• 开发指南
• API参考
• 故障排除
• 贡献指南
• 许可证

🚀 项目概述

这个项目是一个标准的N8N社区节点包，展示了从开发到发布的完整流程。它包含：

• ✅ TypeScript开发环境 - 类型安全的开发体验
• ✅ ESLint代码检查 - 保证代码质量
• ✅ Prettier代码格式化 - 统一代码风格
• ✅ 自动化构建 - 编译TypeScript到JavaScript
• ✅ 图标资源管理 - 自定义节点图标
• ✅ NPM包发布 - 完整的包管理配置
• ✅ 文档完备 - 详细的使用和开发文档

✨ 功能特性

核心功能

• 个性化问候 - 支持自定义姓名的问候消息
• 多种风格 - 提供简单、正式、友好三种问候风格
• 时间戳选项 - 可选择在消息中包含当前时间
• 错误处理 - 完善的错误处理和恢复机制

技术特性

• TypeScript支持 - 完整的类型定义
• 模块化设计 - 清晰的代码结构
• 测试友好 - 易于测试和调试
• 国际化准备 - 支持多语言扩展

📁 项目结构

n8n-learn/
├── 📁 nodes/                          # 节点源码目录
│   └── 📁 HelloWorld/                 # HelloWorld节点
│       ├── 📄 HelloWorld.node.ts      # 节点主要实现文件
│       ├── 📄 HelloWorld.node.json    # 节点元数据配置
│       └── 🖼️ helloworld.svg           # 节点图标
├── 📁 dist/                           # 编译输出目录
│   ├── 📁 HelloWorld/                 # 复制的图标资源
│   └── 📁 nodes/HelloWorld/           # 编译后的JS文件
├── 📄 package.json                    # 项目配置和依赖
├── 📄 tsconfig.json                   # TypeScript编译配置
├── 📄 .eslintrc.js                    # ESLint代码检查配置
├── 📄 .prettierrc.js                  # Prettier格式化配置
├── 📄 gulpfile.js                     # Gulp构建任务
├── 📄 index.ts                        # 包入口文件
├── 📄 .gitignore                      # Git忽略文件配置
├── 📄 README.md                       # 项目说明文档
├── 📄 USAGE.md                        # 使用指南
├── 📄 CHANGELOG.md                    # 版本变更记录
└── 📄 LICENSE.md                      # 开源许可证

📖 文件详解

核心文件

📄 nodes/HelloWorld/HelloWorld.node.ts

节点的核心实现文件，这是最重要的文件：

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

export class HelloWorld implements INodeType {
    description: INodeTypeDescription = {
        // 节点的显示配置
        displayName: 'Hello World',
        name: 'helloWorld',
        icon: 'file:helloworld.svg',
        group: ['output'],
        version: 1,
        // ... 更多配置
    };

    async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
        // 节点的执行逻辑
    }
}

主要功能：

• 定义节点的UI界面（参数、选项等）
• 实现节点的执行逻辑
• 处理输入数据和生成输出
• 错误处理和异常管理

📄 nodes/HelloWorld/HelloWorld.node.json

节点元数据配置文件：

{
  "node": "n8n-nodes-helloworld-demo.HelloWorld",
  "nodeVersion": "1.0",
  "codexVersion": "1.0.0",
  "categories": ["Miscellaneous"],
  "resources": {
    "primaryDocumentation": [...]
  },
  "alias": ["greeting", "hello", "message"]
}

作用：

• 定义节点在N8N中的分类
• 设置搜索别名
• 配置文档链接
• 版本信息管理

🖼️ nodes/HelloWorld/helloworld.svg

自定义节点图标：

• 60x60像素的SVG格式图标
• 在N8N工作流编辑器中显示
• 支持自定义颜色和设计

配置文件

📄 package.json

NPM包配置文件，包含：

{
  "name": "n8n-nodes-helloworld-demo",
  "version": "1.0.0",
  "description": "N8N custom node for sending simple greeting messages",
  "main": "index.js",
  "n8n": {
    "n8nNodesApiVersion": 1,
    "nodes": ["dist/nodes/HelloWorld/HelloWorld.node.js"]
  },
  "scripts": {
    "build": "tsc && gulp build:icons",
    "dev": "tsc --watch",
    "lint": "eslint \"nodes/**/*.ts\"",
    "format": "prettier nodes --write"
  }
}

关键配置说明：

• n8n 字段：告诉N8N这是一个社区节点包
• scripts：定义构建、开发、检查脚本
• files：指定发布到NPM的文件
• keywords：NPM搜索关键词

📄 tsconfig.json

TypeScript编译器配置：

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2019",
    "outDir": "./dist",
    "strict": true,
    "declaration": true
  },
  "include": ["nodes/**/*"],
  "exclude": ["dist/**/*", "node_modules/**/*"]
}

配置说明：

• outDir：输出目录设置为 dist
• strict：启用严格类型检查
• declaration：生成 .d.ts 类型定义文件

📄 .eslintrc.js

ESLint代码质量检查配置：

module.exports = {
  parser: '@typescript-eslint/parser',
  extends: ['eslint:recommended'],
  plugins: ['@typescript-eslint'],
  rules: {
    'no-console': 'warn',
    '@typescript-eslint/no-unused-vars': 'warn'
  }
};

📄 .prettierrc.js

代码格式化配置：

module.exports = {
  semi: true,
  trailingComma: 'all',
  singleQuote: true,
  printWidth: 100,
  useTabs: true
};

构建文件

📄 gulpfile.js

Gulp构建任务配置：

const { src, dest } = require('gulp');

function buildIcons() {
    return src('nodes/**/*.{png,svg}')
        .pipe(dest('dist/'));
}

exports['build:icons'] = buildIcons;

作用：

• 复制图标文件到输出目录
• 可扩展其他构建任务

📄 index.ts

包的入口文件：

import { HelloWorld } from './nodes/HelloWorld/HelloWorld.node';

export { HelloWorld };

文档文件

📄 README.md

当前文件 - 项目的主要说明文档

📄 USAGE.md

详细的使用指南，包含：

• 安装方法
• 配置说明
• 开发指南
• 故障排除

📄 CHANGELOG.md

版本变更记录：

• 新功能介绍
• Bug修复记录
• 破坏性变更说明

📄 LICENSE.md

MIT开源许可证文件

💾 安装使用

在N8N中安装

方法1: 通过N8N界面（推荐）

1. 打开N8N管理界面
2. 进入 Settings > Community Nodes
3. 点击 Install
4. 输入包名：n8n-nodes-helloworld-demo
5. 点击安装并重启N8N

方法2: 通过命令行

# 全局安装N8N
npm install n8n -g

# 安装插件
npm install n8n-nodes-helloworld-demo

# 启动N8N
n8n start

方法3: Docker环境

version: '3.8'
services:
  n8n:
    image: n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      - N8N_COMMUNITY_PACKAGES_ENABLED=true
    volumes:
      - n8n_data:/home/node/.n8n
volumes:
  n8n_data:

使用节点

1. 在工作流编辑器中搜索 "Hello World"
2. 拖拽节点到工作流中
3. 配置节点参数：
   • Name: 输入要问候的姓名
   • Message Type: 选择问候风格
   • Include Timestamp: 是否包含时间戳
4. 执行工作流查看结果

🛠️ 开发指南

环境准备

1. 安装Node.js (版本 ≥ 16.0.0)
2. 克隆项目：

   git clone <your-repo-url>
   cd n8n-learn

3. 安装依赖：

   npm install

开发流程

1. 开发模式

# 启动监听模式，代码变更自动编译
npm run dev

2. 构建项目

# 编译TypeScript并复制资源文件
npm run build

3. 代码检查

# 运行ESLint检查
npm run lint

# 自动修复可修复的问题
npm run lintfix

4. 格式化代码

# 使用Prettier格式化代码
npm run format

5. 本地测试

# 创建本地链接
npm link

# 在N8N中链接
npm link n8n-nodes-helloworld-demo

# 启动N8N测试
n8n start

添加新功能

1. 添加新参数

在 HelloWorld.node.ts 的 properties 数组中添加：

{
  displayName: 'New Parameter',
  name: 'newParam',
  type: 'string',
  default: '',
  description: 'Description of the new parameter'
}

2. 实现参数逻辑

在 execute 方法中获取和使用参数：

const newParam = this.getNodeParameter('newParam', i) as string;
// 使用参数实现逻辑

3. 更新文档

• 更新 README.md
• 更新 CHANGELOG.md
• 添加使用示例

发布流程

1. 更新版本号：

   npm version patch  # 或 minor, major

2. 构建并测试：

   npm run build
   npm run lint

3. 发布到NPM：

   npm publish

📚 API参考

节点配置

输入参数

| 参数名 | 类型 | 必需 | 默认值 | 描述 | |--------|------|------|--------|------| | name | string | ✅ | '' | 要问候的姓名 | | messageType | options | ❌ | 'simple' | 问候风格类型 | | includeTimestamp | boolean | ❌ | false | 是否包含时间戳 |

问候风格选项

| 值 | 说明 | 示例 | |----|------|------| | simple | 简单问候 | "Hello, John!" | | formal | 正式问候 | "Good day, John. I hope this message finds you well." | | friendly | 友好问候 | "Hey there, John! Hope you're having a great day! 😊" |

输出格式

{
  "success": true,
  "message": "Hello, John!",
  "recipient": "John",
  "messageType": "simple",
  "timestamp": "2023-12-07T10:30:00.000Z"  // 可选
}

错误处理

当节点遇到错误时，会返回：

{
  "success": false,
  "error": "错误描述信息"
}

🔧 故障排除

常见问题

1. 节点不显示在N8N中

解决方法：

• 检查N8N是否启用了社区节点：N8N_COMMUNITY_PACKAGES_ENABLED=true
• 重启N8N服务
• 检查包是否正确安装：npm list n8n-nodes-helloworld-demo

2. TypeScript编译错误

解决方法：

• 检查TypeScript版本兼容性
• 运行 npm install 重新安装依赖
• 检查 tsconfig.json 配置

3. ESLint检查失败

解决方法：

• 运行 npm run lintfix 自动修复
• 检查 .eslintrc.js 配置
• 手动修复代码问题

4. 图标不显示

解决方法：

• 检查SVG文件格式是否正确
• 运行 npm run build 重新构建
• 确认图标文件路径正确

调试技巧

1. 使用console.log：

   console.log('Debug info:', parameter);

2. 检查N8N日志：

   # 启动N8N时查看详细日志
   N8N_LOG_LEVEL=debug n8n start

3. 浏览器开发者工具：

   • 打开F12开发者工具
   • 查看Network和Console标签
   • 检查API请求和响应

🤝 贡献指南

贡献流程

1. Fork项目
2. 创建功能分支：git checkout -b feature/new-feature
3. 提交更改：git commit -am 'Add new feature'
4. 推送分支：git push origin feature/new-feature
5. 创建Pull Request

代码规范

• 使用TypeScript进行开发
• 遵循ESLint规则
• 使用Prettier格式化代码
• 添加适当的注释和文档
• 编写测试用例（如适用）

问题报告

提交Issue时请包含：

• 问题描述
• 重现步骤
• 期望结果
• 实际结果
• 环境信息（N8N版本、Node.js版本等）

📄 许可证

本项目采用 MIT许可证。

🙏 致谢

• N8N团队 - 提供优秀的工作流自动化平台
• TypeScript团队 - 类型安全的JavaScript
• 所有为开源社区做出贡献的开发者们

📞 联系方式

• GitHub Issues: [项目Issues页面]
• 邮箱: [email protected]

🔗 相关链接

• N8N官方文档
• N8N社区节点指南
• NPM包页面