n8n Code 节点常见错误排查指南

# 错误模式 - JavaScript Code 节点 避免最常见 Code 节点错误的完整指南。 --- ## 概览 本指南涵盖了 n8n Code 节点中遇到的 **前 5 类错误模式**。理解并避免这些错误将为你节省大量的调试时间。 **错误频率**： 1. 代码为空 / 缺少 Return - **38% 的失败原因** 2. 表达式语法混淆 - **8% 的失败原因** 3. 返回包装器格式错误 - **5% 的失败原因** 4. 表达式括号不匹配 - **6% 的失败原因** 5. 缺少空值检查 - **常见的运行时错误** --- ## 错误 #1：代码为空或缺少 Return 语句 **发生频率**：最常见的错误（占所有验证失败的 38%） **现象**： - 工作流执行失败 - 后续节点接收不到数据 - 报错："Code cannot be empty" 或 "Code must return data" ### 问题所在 ```javascript // ❌ 错误：完全没有代码 // (代码字段为空) ``` ```javascript // ❌ 错误：代码执行了但没有返回任何内容 const items = $input.all(); // 处理项目 for (const item of items) { console.log(item.json.name); } // 忘记写 return 了！ ``` ```javascript // ❌ 错误：存在早期返回路径，但并非所有路径都有返回 const items = $input.all(); if (items.length === 0) { return []; // ✅ 此路径有返回 } // 处理项目 const processed = items.map(item => ({json: item.json})); // ❌ 忘记返回 processed 了！ ``` ### 解决方案 ```javascript // ✅ 正确：始终返回数据 const items = $input.all(); // 处理项目 const processed = items.map(item => ({ json: { ...item.json, processed: true } })); return processed; // ✅ 存在 return 语句 ``` ```javascript // ✅ 正确：如果没有项目则返回空数组 const items = $input.all(); if (items.length === 0) { return []; // 有效：无数据时返回空数组 } // 处理并返回 return items.map(item => ({json: item.json})); ``` ```javascript // ✅ 正确：所有代码路径都有返回 const items = $input.all(); if (items.length === 0) { return []; } else if (items.length === 1) { return [{json: {single: true, data: items[0].json}}]; } else { return items.map(item => ({json: item.json})); } // 覆盖了所有路径 ``` ### 检查清单 - [ ] 代码字段不为空 - [ ] 存在 Return 语句 - [ ] 所有代码路径（if/else 分支）都有返回数据 - [ ] 返回格式正确 (`[{json: {...}}]`) - [ ] 即使报错也能返回（使用 try-catch） --- ## 错误 #2：表达式语法混淆 **发生频率**：8% 的验证失败 **现象**： - 代码执行时出现语法错误 - 报错："Unexpected token" 或 "Expression syntax is not valid in Code nodes" - 模板变量未被解析 ### 问题所在 n8n 有两种截然不同的语法： 1. **表达式语法** `{{ }}` - 用于其他节点（Set, IF, HTTP Request） 2. **JavaScript** - 用于 CODE 节点（不使用 `{{ }}`） 许多开发者误在 Code 节点内使用表达式语法。 ```javascript // ❌ 错误：在 Code 节点中使用 n8n 表达式语法 const userName = "{{ $json.name }}"; const userEmail = "{{ $json.body.email }}"; return [{ json: { name: userName, email: userEmail } }]; // 结果：得到的是字面量字符串 "{{ $json.name }}"，而不是具体的值！ ``` ```javascript // ❌ 错误：尝试解析表达式 const value = "{{ $now.toFormat('yyyy-MM-dd') }}"; ``` ### 解决方案 ```javascript // ✅ 正确：直接使用 JavaScript（不带 {{ }}） const userName = $json.name; const userEmail = $json.body.email; return [{ json: { name: userName, email: userEmail } }]; ``` ```javascript // ✅ 正确：使用 JavaScript 模板字符串（使用反引号） const message = `Hello, ${$json.name}! Your email is ${$json.email}`; return [{ json: { greeting: message } }]; ``` ```javascript // ✅ 正确：直接访问变量 const item = $input.first().json; return [{ json: { name: item.name, email: item.email, timestamp: new Date().toISOString() // 使用 JavaScript Date，而非 {{ }} } }]; ``` ### 对比表 | 上下文 | 语法 | 示例 | |---------|--------|---------| | Set 节点 | `{{ }}` 表达式 | `{{ $json.name }}` | | IF 节点 | `{{ }}` 表达式 | `{{ $json.age > 18 }}` | | HTTP Request URL | `{{ }}` 表达式 | `{{ $json.userId }}` | | **Code 节点** | **JavaScript** | `$json.name` | | **Code 节点字符串** | **模板字符串** | `` `Hello ${$json.name}` `` | ### 快速转换指南 ```javascript // 错误 → 正确 转换 // ❌ "{{ $json.field }}" // ✅ $json.field // ❌ "{{ $now }}" // ✅ new Date().toISOString() // ❌ "{{ $node['HTTP Request'].json.data }}" // ✅ $node["HTTP Request"].json.data // ❌ `{{ $json.firstName }} {{ $json.lastName }}` // ✅ `${$json.firstName} ${$json.lastName}` ``` --- ## 错误 #3：返回包装格式不正确 **发生频率**：5% 的验证失败 **现象**： - 报错："Return value must be an array of objects" - 报错："Each item must have a json property" - 后续节点接收到格式错误的数据 ### 问题所在 Code 节点必须返回： - 对象的**数组** - 每个对象必须包含 **`json` 属性** ```javascript // ❌ 错误：返回对象而不是数组 return { json: { result: 'success' } }; // 缺少数组包装器 [] ``` ```javascript // ❌ 错误：返回数组但没有 json 包装器 return [ {id: 1, name: 'Alice'}, {id: 2, name: 'Bob'} ]; // 缺少 json 属性 ``` ```javascript // ❌ 错误：返回纯值 return "processed"; ``` ```javascript // ❌ 错误：未映射直接返回 items return $input.all(); // 如果 items 已经有 json 属性则可行，但无法保证始终如此 ``` ```javascript // ❌ 错误：结构不完整 return [{data: {result: 'success'}}]; // 应该是 {json: {...}}，而不是 {data: {...}} ``` ### 解决方案 ```javascript // ✅ 正确：单个结果 return [{ json: { result: 'success', timestamp: new Date().toISOString() } }]; ``` ```javascript // ✅ 正确：多个结果 return [ {json: {id: 1, name: 'Alice'}}, {json: {id: 2, name: 'Bob'}}, {json: {id: 3, name: 'Carol'}} ]; ``` ```javascript // ✅ 正确：转换数组 const items = $input.all(); return items.map(item => ({ json: { id: item.json.id, name: item.json.name, processed: true } })); ``` ```javascript // ✅ 正确：空结果 return []; // 无数据返回时有效 ``` ```javascript // ✅ 正确：条件返回 if (shouldProcess) { return [{json: {result: 'processed'}}]; } else { return []; } ``` ### 返回格式检查清单 - [ ] 返回值是一个数组 `[...]` - [ ] 数组中的每个元素都有 `json` 属性 - [ ] 结构为 `[{json: {...}}]` 或 `[{json: {...}}, {json: {...}}]` - [ ] 不是 `{json: {...}}`（缺少数组包装） - [ ] 不是 `[{...}]`（缺少 json 属性） --- ## 错误 #4：表达式括号不匹配 **发生频率**：6% 的验证失败 **现象**： - 保存时解析错误 - 报错："Unmatched expression brackets" - 代码看起来正确但验证失败 ### 问题所在 此错误通常发生在： 1. 字符串包含不平衡的引号 2. 包含特殊字符的多行字符串 3. 带有嵌套括号的模板字符串 ```javascript // ❌ 错误：字符串中引号未转义 const message = "It's a nice day"; // 单引号破坏了字符串结构 ``` ```javascript // ❌ 错误：正则中括号不平衡 const pattern = /{(w+)}/; // JSON 存储问题 ``` ### 解决方案 ```javascript // ✅ 正确：转义引号 const message = "It\'s a nice day"; // 或者使用不同的引号 const message = "It's a nice day"; // 双引号可行 ``` ```javascript // ✅ 正确：使用模板字符串处理多行 const html = ` `; // 反引号可以处理多行和引号 ``` --- ## 错误 #5：缺少空值检查 / 访问未定义属性 **发生频率**：非常常见的运行时错误 **现象**： - 工作流执行停止 - 报错："Cannot read property 'X' of undefined" - 报错："Cannot read property 'X' of null" - 数据缺失时崩溃 ### 解决方案 ```javascript // ✅ 正确：可选链 (Optional chaining) const email = item.json?.user?.email || '[email protected]'; ``` ```javascript // ✅ 正确：检查数组长度 const items = $input.all(); if (items.length === 0) { return []; } const firstItem = items[0].json; ``` ```javascript // ✅ 正确：守卫子句 (Guard clauses) const data = $input.first().json; if (!data.address) { return [{json: {error: 'No address provided'}}]; } const city = data.address.city; ``` --- ## 错误预防检查清单 在部署 Code 节点前使用此清单： ### 代码结构 - [ ] 代码字段不为空 - [ ] 存在 Return 语句 - [ ] 所有代码路径都有返回数据 ### 返回格式 - [ ] 返回数组：`[...]` - [ ] 每个项目都有 `json` 属性：`{json: {...}}` - [ ] 格式为 `[{json: {...}}]` ### 语法 - [ ] 没有 `{{ }}` 表达式语法（使用 JavaScript） - [ ] 模板字符串使用反引号：`` `${variable}` `` - [ ] 所有引号和括号平衡 ### 数据安全 - [ ] 对可选属性进行空值检查 - [ ] 访问前检查数组长度 - [ ] 使用 try-catch 处理高风险操作 - [ ] 为缺失数据提供默认值 --- ## 调试技巧 ### 1. 使用 console.log() 在浏览器控制台 (F12) 查看输出。 ### 2. 返回中间结果 通过返回当前状态来调试，查看你目前拥有什么数据。 ### 3. 使用 Try-Catch 进行故障排除 ```javascript try { // 你的代码 } catch (error) { return [{ json: { error: error.message, stack: error.stack } }]; } ``` --- ## 总结 **要避免的前 5 类错误**： 1. **代码为空 / 缺少 return** (38%) - 务必返回数据 2. **表达式语法 `{{ }}`** (8%) - 使用 JavaScript，而非表达式 3. **返回格式错误** (5%) - 始终保持 `[{json: {...}}]` 格式 4. **括号不匹配** (6%) - 正确转义字符串 5. **缺少空值检查** - 使用可选链 `?.`