n8n JavaScript 脚本开发指南

# n8n Code JavaScript 在 n8n Code 节点中编写 JavaScript 代码的专家指南。 --- ## 目的 教授如何在 n8n Code 节点中编写高效的 JavaScript，避免常见错误，并有效利用内置函数。 --- ## 激活条件 **触发关键词**： - "javascript code node" - "write javascript in n8n" - "code node javascript" - "$input syntax" - "$json syntax" - "$helpers.httpRequest" - "DateTime luxon" - "code node error" - "webhook data code" - "return format code node" **常见场景**： - 在 Code 节点中编写 JavaScript 代码 - 排除 Code 节点错误 - 从代码中发起 HTTP 请求 - 处理日期和时间 - 访问 Webhook 数据 - 在“所有项目 (All Items)”和“每个项目 (Each Item)”模式之间做出选择 --- ## 你将学到什么 ### 快速入门 - 模式选择（所有项目 vs 每个项目） - 数据访问模式（$input.all(), $input.first(), $input.item） - 正确的返回格式：`[{json: {...}}]` - Webhook 数据结构（.body 嵌套） - 内置函数概览 ### 数据访问精通 - $input.all() - 批量操作（最常用） - $input.first() - 单个项目操作 - $input.item - “每个项目”模式下的处理 - $node - 引用其他工作流节点 - **关键陷阱**：Webhook 数据位于 `.body` 属性下 ### 常用模式（生产环境验证） 1. 多源数据聚合 2. 正则表达式过滤与模式匹配 3. Markdown 解析与结构化提取 4. JSON 比较与验证 5. CRM 数据转换 6. 发布信息处理 7. 带上下文的数组转换 8. Slack Block Kit 格式化 9. 前 N 项过滤与排名 10. 字符串聚合与报告 ### 错误预防 需避免的前 5 类错误： 1. **空代码 / 缺少返回**（38% 的失败原因） 2. **表达式语法混淆**（在代码中使用 `{{}}`） 3. **错误的返回格式**（缺少数组包装或 json 属性） 4. **括号不匹配**（字符串转义问题） 5. **缺少空值检查**（在 undefined 上操作导致崩溃） ### 内置函数 - **$helpers.httpRequest()** - 发起 HTTP 请求 - **DateTime (Luxon)** - 高级日期/时间操作 - **$jmespath()** - 查询 JSON 结构 - **$getWorkflowStaticData()** - 持久化存储 - 标准 JavaScript 全局变量（Math, JSON, console） - 可用的 Node.js 模块（crypto, Buffer, URL） --- ## 文件结构 ``` n8n-code-javascript/ ├── SKILL.md (500 行) │ 概览、快速入门、模式选择、最佳实践 │ - 模式选择指南（所有项目 vs 每个项目） │ - 数据访问模式概览 │ - 返回格式要求 │ - 关键 Webhook 陷阱 │ - 错误预防概览 │ - 快速参考清单 │ ├── DATA_ACCESS.md (400 行) │ 完整的数据访问模式 │ - $input.all() - 最常用 (26% 使用率) │ - $input.first() - 非常常用 (25% 使用率) │ - $input.item - 每个项目模式 (19% 使用率) │ - $node - 引用其他节点 │ - Webhook 数据结构 (.body 嵌套) │ - 选择正确的模式 │ - 需避免的常见错误 │ ├── COMMON_PATTERNS.md (600 行) │ 10 个生产环境验证的模式 │ - 模式 1：多源聚合 │ - 模式 2：正则过滤 │ - 模式 3：Markdown 解析 │ - 模式 4：JSON 比较 │ - 模式 5：CRM 转换 │ - 模式 6：发布处理 │ - 模式 7：数组转换 │ - 模式 8：Slack Block Kit │ - 模式 9：前 N 项过滤 │ - 模式 10：字符串聚合 │ - 模式选择指南 │ ├── ERROR_PATTERNS.md (450 行) │ 前 5 类错误及其解决方案 │ - 错误 #1：空代码 / 缺少返回 (38%) │ - 错误 #2：表达式语法混淆 (8%) │ - 错误 #3：错误的返回包装 (5%) │ - 错误 #4：括号不匹配 (6%) │ - 错误 #5：缺少空值检查 │ - 错误预防清单 │ - 快速错误参考 │ - 调试技巧 │ ├── BUILTIN_FUNCTIONS.md (450 行) │ 完整的内置函数参考 │ - $helpers.httpRequest() API 参考 │ - DateTime (Luxon) 完整指南 │ - $jmespath() JSON 查询 │ - $getWorkflowStaticData() 持久化存储 │ - 标准 JavaScript 全局变量 │ - 可用的 Node.js 模块 │ - 不可用的内容 │ └── README.md (本文件) 技能元数据和概览 ``` **总计**：6 个文件，约 2,400 行 --- ## 覆盖范围 ### 模式选择 - **为所有项目运行一次 (Run Once for All Items)** - 推荐用于 95% 的用例 - **为每个项目运行一次 (Run Once for Each Item)** - 仅限特殊情况 - 决策指南及性能影响 ### 数据访问 - 带有使用统计的最常用模式 - Webhook 数据结构（关键的 .body 陷阱） - 带有空值检查的安全访问模式 - 何时使用哪种模式 ### 错误预防 - 涵盖 62% 以上失败原因的前 5 类错误 - 清晰的错误 vs 正确示例对比 - 错误预防清单 - 调试技巧和 console.log 使用方法 ### 生产模式 - 来自真实工作流的 10 个模式 - 完整的运行示例 - 用例和核心技术 - 模式选择指南 ### 内置函数 - 完整的 $helpers.httpRequest() 参考 - DateTime/Luxon 操作（格式化、解析、算术运算） - 用于 JSON 查询的 $jmespath() - 使用 $getWorkflowStaticData() 进行持久化存储 - 标准 JavaScript 和 Node.js 模块 --- ## 重点强调的陷阱 ### #1: Webhook 数据结构 **最常见的错误**：Webhook 数据位于 `.body` 下 ```javascript // ❌ 错误 const name = $json.name; // ✅ 正确 const name = $json.body.name; ``` ### #2: 返回格式 **至关重要**：必须返回带有 json 属性的数组 ```javascript // ❌ 错误 return {json: {result: 'success'}}; // ✅ 正确 return [{json: {result: 'success'}}]; ``` ### #3: 表达式语法 **不要在 Code 节点中使用 `{{}}`** ```javascript // ❌ 错误 const value = "{{ $json.field }}"; // ✅ 正确 const value = $json.field; ``` --- ## 与其他技能的集成 ### n8n 表达式语法 - **区别**：在“其他”节点中使用 `{{}}` 表达式 - **Code 节点**：直接使用 JavaScript（不含 `{{}}`） - **何时使用**：Code 节点 vs 表达式的决策指南 ### n8n MCP 工具专家 - 查找 Code 节点：`search_nodes({query: "code"})` - 获取配置：`get_node_essentials("nodes-base.code")` - 验证代码：`validate_node_operation()` ### n8n 节点配置 - 模式选择（所有项目 vs 每个项目） - 语言选择（JavaScript vs Python） - 理解属性依赖关系 ### n8n 工作流模式 - 转换步骤中的 Code 节点 - Webhook → Code → API 模式 - 工作流中的错误处理 ### n8n 验证专家 - 验证 Code 节点配置 - 处理验证错误 - 自动修复常见问题 --- ## 何时使用 Code 节点 **在以下情况下使用 Code 节点：** - ✅ 需要多个步骤的复杂转换 - ✅ 自定义计算或业务逻辑 - ✅ 递归操作 - ✅ 具有复杂结构的 API 响应解析 - ✅ 多步条件判断 - ✅ 跨项目的数据聚合 **考虑使用其他节点的情况：** - ❌ 简单的字段映射 → 使用 **Set** 节点 - ❌ 基础过滤 → 使用 **Filter** 节点 - ❌ 简单条件判断 → 使用 **IF** 或 **Switch** 节点 - ❌ 仅发起 HTTP 请求 → 使用 **HTTP Request** 节点 **Code 节点的优势**：处理那些需要链接许多简单节点才能实现的复杂逻辑。 --- ## 成功指标 **使用本技能前**： - 用户对模式选择感到困惑 - 频繁出现返回格式错误 - 表达式语法错误 - Webhook 数据访问失败 - 缺少空值检查导致崩溃 **使用本技能后**： - 清晰的模式选择指导 - 理解返回格式要求 - 区分 JavaScript 与表达式 - 正确的 Webhook 数据访问 - 安全的空值处理模式 - 生产就绪的代码模式 --- ## 快速参考 ### 核心规则 1. 选择 "All Items" 模式（推荐） 2. 访问数据：`$input.all()`, `$input.first()`, `$input.item` 3. **必须返回**：`[{json: {...}}]` 格式 4. **Webhook 数据**：位于 `.body` 属性下 5. **无 `{{}}` 语法**：直接编写 JavaScript ### 最常用模式 - 批量处理 → $input.all() + map/filter - 单个项目 → $input.first() - 聚合 → reduce() - HTTP 请求 → $helpers.httpRequest() - 日期处理 → DateTime (Luxon) ### 错误预防 - 始终返回数据 - 检查 null/undefined - 对高风险操作使用 try-catch - 使用空输入进行测试 - 使用 console.log() 进行调试 --- ## 相关文档 - **n8n Code 节点指南**: https://docs.n8n.io/code/code-node/ - **内置方法参考**: https://docs.n8n.io/code-examples/methods-variables-reference/ - **Luxon 文档**: https://moment.github.io/luxon/ --- ## 作者 构思者：Romuald Członkowski - [www.aiadvisors.pl/en](https://www.aiadvisors.pl/en) n8n-skills 集合的一部分。