n8n-mcp 实战Python Code 节点五大高频错误模式与系统化排查指南【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp导读本文是 n8n-mcp 项目中 Python Code 节点n8n Code node Python 模式的权威错误排查指南源自 ERROR_PATTERNS.md并融合了同目录 SKILL.md、DATA_ACCESS.md、STANDARD_LIBRARY.md 及仓库源码实现。读完本文你将掌握 n8n Python Code 节点最常见的五大错误外加一个 Bonus 错误的成因、报错形态、正确修复写法以及一套可落地的错误预防检查清单与测试模式能够直接排查并修复真实工作流中的 Python 节点故障。一、错误全景Top 5 高频错误总览在 n8n 的 Code 节点中Python 模式与 JavaScript 模式共享同一套数据与返回契约但 Python 因其标准库限制和语法特性产生了特有的高频错误。根据 ERROR_PATTERNS.md 的统计以下 5 类错误覆盖了 Python Code 节点失败的大多数场景#错误根因1ModuleNotFoundError导入外部库Python 特有2空代码 / 缺少 return没有代码或没有返回语句3KeyError未使用.get()直接访问字典键4IndexError未做边界检查直接按下标访问列表5返回格式错误返回了错误的数据结构这五类错误是 n8n Python Code 节点失败的主要来源下文逐一拆解。在动手排查前请先建立一条核心认知n8n 官方与本文所在技能体系都建议 95% 的场景优先使用 JavaScriptPython 仅在你明确需要标准库能力正则、哈希、统计等时使用详见 README.md。二、Error #1ModuleNotFoundError —— 最致命的 Python 特有错误频率Python Code 节点中非常常见。成因尝试导入 n8n Python 运行环境中不可用的外部库。n8n 默认只提供 Python 标准库没有 pip 包管理能力。2.1 错误现场# ❌ 错误外部库不可用 import requests # ModuleNotFoundError: No module named requests import pandas # ModuleNotFoundError: No module named pandas import numpy # ModuleNotFoundError: No module named numpy import bs4 # ModuleNotFoundError: No module named bs4 import pymongo # ModuleNotFoundError: No module named pymongo import psycopg2 # ModuleNotFoundError: No module named psycopg2 # 以下代码必然失败——这些库并未安装 response requests.get(https://api.example.com/data)2.2 解决方案方案一改用 JavaScript推荐覆盖约 95% 的场景// ✅ JavaScript Code 节点中使用 this.helpers.httpRequest() const response await this.helpers.httpRequest({ method: GET, url: https://api.example.com/data }); return [{json: response}];方案二用 n8n HTTP Request 节点替代在 Python Code 节点之前串联一个 HTTP Request 节点然后在前置节点的输出上继续处理# ✅ 在 Python Code 节点中读取上游 HTTP Request 节点的响应 response _input.first()[json] return [{ json: { status: response.get(status), data: response.get(body), processed: True } }]方案三仅使用标准库# ✅ 使用标准库 urllib功能有限无自定义 headers、无鉴权 from urllib.request import urlopen from urllib.parse import urlencode import json url https://api.example.com/data with urlopen(url) as response: data json.loads(response.read()) return [{json: data}]2.3 常见库替换对照表需求❌ 外部库✅ 替代方案HTTP 请求requestsHTTP Request 节点或 JavaScript数据分析pandasPython 列表推导式数据库psycopg2、pymongon8n 数据库节点Postgres/MySQL/MongoDB网页抓取beautifulsoup4HTML Extract 节点ExcelopenpyxlSpreadsheet File 节点图片处理pillow外部 API 或专用节点2.4 可用的标准库模块清单# ✅ 以下均可使用——标准库 import json # JSON 解析 import datetime # 日期/时间操作 import re # 正则表达式 import base64 # Base64 编码 import hashlib # 哈希MD5、SHA256 import urllib.parse # URL 解析与编码 import math # 数学函数 import random # 随机数 import statistics # 统计函数 import collections # defaultdict、Counter 等完整的可用模块与不可用模块清单含itertools、functools、os.path等分级说明见 STANDARD_LIBRARY.md。自托管例外外部包是否可用完全取决于实例的 Python runner 配置。若你的自托管实例明确声明了可用的额外包可以按实例实际情况使用详见 SKILL.md 中的说明。2.5 源码佐证官方 Python 示例同样遵守标准库约束仓库中的示例生成器 example-generator.ts 内置了nodes-base.code.pythonExample示例其实现完全遵循“仅标准库 _input.all()数据访问”的约束# Python data processing - use underscore prefix for built-in variables import json from datetime import datetime import re results [] # Use _input.all() to get items in Python for item in _input.all(): # Convert JsProxy to Python dict to avoid issues with null values item_data item.json.to_py() # Clean email addresses email item_data.get(email, ) if email and re.match(r^[\w\.-][\w\.-]\.\w$, email): cleaned_data { email: email.lower(), name: item_data.get(name, ).title(), validated: True, timestamp: datetime.now().isoformat() } else: cleaned_data dict(item_data) cleaned_data[validated] False cleaned_data[error] Invalid email format results.append({json: cleaned_data}) return results这段代码印证了三条关键实现事实只用json/datetime/re标准库用item.json.to_py()将 JsProxy 转为 Python dict避免空值问题统一以{json: ...}结构返回。同时仓库的表达式格式校验器 expression-format-validator.ts 明确将jsCode、pythonCode、functionCode视为“原始代码字段”跳过表达式检查——说明这些字段在项目中被当作不可外部校验的代码主体写好它们只能靠开发者遵守标准库与返回格式约束。三、Error #2空代码 / 缺少 Return频率所有 Code 节点均常见。成因代码节点内容为空或代码执行路径上没有return语句。3.1 错误现场# ❌ 错误空代码 # 什么都没有 # ❌ 错误有代码但没有 return items _input.all() processed [item for item in items if item[json].get(active)] # 忘了 return # ❌ 错误return 作用域错误 if _input.all(): return [{json: {result: success}}] # return 在 if 块内部——可能不会执行3.2 正确写法# ✅ 正确始终 return all_items _input.all() if not all_items: # 返回空数组或错误信息 return [{json: {error: No items}}] # 处理数据 processed [item for item in all_items if item[json].get(active)] # 末尾必须 return return processed if processed else [{json: {message: No active items}}]3.3 最佳实践无条件返回# ✅ 良好函数末尾无条件 return def process_items(): items _input.all() if not items: return [{json: {error: Empty input}}] # 处理 result [] for item in items: result.append({json: item[json]}) return result # 调用函数并返回结果 return process_items()将业务逻辑封装进函数、由主流程return process_items()兜底可以保证无论内部分支如何节点出口始终有返回值。四、Error #3KeyError —— 字典访问未用 .get()频率Python Code 节点中非常常见。成因直接以dict[key]形式访问不存在的字典键。4.1 错误现场# ❌ 错误直接按键访问 item _input.first()[json] name item[name] # 若 name 不存在则 KeyError email item[email] # 若 email 不存在则 KeyError age item[age] # 若 age 不存在则 KeyError return [{ json: { name: name, email: email, age: age } }]4.2 报错形态KeyError: name4.3 解决方案.get() 默认值# ✅ 正确使用带默认值的 .get() item _input.first()[json] name item.get(name, Unknown) email item.get(email, no-emailexample.com) age item.get(age, 0) return [{ json: { name: name, email: email, age: age } }]4.4 嵌套字典访问# ❌ 错误多层键直接访问 webhook _input.first()[json] name webhook[body][user][name] # 可能产生多个 KeyError # ✅ 正确逐层安全访问 webhook _input.first()[json] body webhook.get(body, {}) user body.get(user, {}) name user.get(name, Unknown) # ✅ 同样正确链式 .get() name ( webhook .get(body, {}) .get(user, {}) .get(name, Unknown) ) return [{json: {name: name}}]4.5 Webhook Body 访问关键n8n Python Code 节点最常见的单一错误是忘记 webhook 数据被嵌套在[body]之下。Webhook 节点会把 POST 数据、查询参数、JSON 载荷统一包装在body属性内# ❌ 错误忘记 webhook 数据位于 body 下 webhook _input.first()[json] name webhook[name] # KeyError email webhook[email] # KeyError # ✅ 正确通过 [body] 访问 webhook _input.first()[json] body webhook.get(body, {}) name body.get(name, Unknown) email body.get(email, no-email) return [{ json: { name: name, email: email } }]关于 webhook 完整结构headers、params、query、body、method、url以及_input.all()/_input.first()/_input.item/_node[Name]的选型决策树详见 DATA_ACCESS.md。五、Error #4IndexError —— 列表访问未做边界检查频率处理数组/列表时常见。成因直接按下标访问不存在的列表位置。5.1 错误现场# ❌ 错误假设元素必然存在 all_items _input.all() first_item all_items[0] # 列表为空则 IndexError second_item all_items[1] # 只有 1 个元素则 IndexError return [{ json: { first: first_item[json], second: second_item[json] } }]5.2 报错形态IndexError: list index out of range5.3 解决方案先检查长度# ✅ 正确先检查长度 all_items _input.all() if len(all_items) 2: first_item all_items[0][json] second_item all_items[1][json] return [{ json: { first: first_item, second: second_item } }] else: return [{ json: { error: fExpected 2 items, got {len(all_items)} } }]5.4 安全获取首元素# ✅ 正确用 _input.first() 代替 [0]内置安全保护 first_item _input.first()[json] return [{json: first_item}] # ✅ 同样正确访问前先判断 all_items _input.all() if all_items: first_item all_items[0][json] else: first_item {} return [{json: first_item}]5.5 用切片代替下标# ✅ 正确切片永远不会抛出 IndexError all_items _input.all() # 取前 5 个不足 5 个也不会失败 first_five all_items[:5] # 取第一个之后的全部为空也不会失败 rest all_items[1:] return [{json: item[json]} for item in first_five]六、Error #5返回格式错误频率新手用户常见。成因n8n 要求 Code 节点返回带json键的对象数组返回其他结构会导致下游节点无法解析。6.1 错误现场# ❌ 错误返回普通字典 return {name: Alice, age: 30} # ❌ 错误返回没有 json 包装的数组 return [{name: Alice}, {name: Bob}] # ❌ 错误返回 None return None # ❌ 错误返回字符串 return success # ❌ 错误返回单个对象而非数组 return {json: {name: Alice}}6.2 正确格式# ✅ 正确带 json 键的对象数组 return [{json: {name: Alice, age: 30}}] # ✅ 正确多条数据 return [ {json: {name: Alice}}, {json: {name: Bob}} ] # ✅ 正确批量转换 all_items _input.all() return [ {json: item[json]} for item in all_items ] # ✅ 正确空数组合法 return [] # ✅ 正确单条结果也要数组包装 return [{json: {result: success}}]为什么必须这样下游节点期望的是列表格式。格式错误会导致整个工作流执行失败详见 SKILL.md 的 Return Format Requirements 章节。6.3 常见场景场景一聚合返回单一结果# 计算总和 all_items _input.all() total sum(item[json].get(amount, 0) for item in all_items) # ✅ 正确用数组 json 包装 return [{ json: { total: total, count: len(all_items) } }]场景二过滤返回多条结果# 过滤活跃条目 all_items _input.all() active [item for item in all_items if item[json].get(active)] # ✅ 正确原样返回已是正确格式 return active # ✅ 同样正确若需转换 return [ {json: {**item[json], filtered: True}} for item in active ]场景三无结果# ✅ 正确返回空数组 return [] # ✅ 同样正确返回错误信息 return [{json: {error: No results found}}]七、Bonus 错误AttributeError —— 模式使用不当成因在错误的运行模式下使用了_input.item。7.1 错误现场# ❌ 错误在 All Items 模式使用 _input.item current _input.item # 在 All Items 模式下为 None data current[json] # AttributeError: NoneType object has no attribute __getitem__7.2 解决方案# ✅ 正确根据模式选择合适的方法 # All Items 模式使用 all_items _input.all() # Each Item 模式使用 current_item _input.item # ✅ 安全先判断 item 是否存在 current _input.item if current: data current[json] return [{json: data}] else: # 当前运行在 All Items 模式 return _input.all()_input.item仅在Run Once for Each Item模式下可用在默认的Run Once for All Items模式下为None。两种模式的选择依据、性能差异与示例代码见 SKILL.md。八、错误预防检查清单运行 Python Code 节点前逐项核验无外部导入仅使用标准库json、datetime、re 等代码返回数据每条执行路径都以return结尾格式正确返回[{json: {...}}]带 json 键的数组字典安全访问字典用.get()而非[]列表安全访问下标访问前检查长度或改用切片Webhook body 访问通过_json[body]访问 webhook 数据不返回 None用空数组[]代替None模式意识按运行模式正确使用_input.all()、_input.first()、_input.item九、快速修复参考表错误快速修复ModuleNotFoundError改用 JavaScript 或 HTTP Request 节点KeyError: field将data[field]改为data.get(field, default)IndexError: list index out of range访问items[0]前先if len(items) 0:输出为空在末尾添加return [{json: {...}}]AttributeError: NoneType检查模式设置或确认_input.item是否存在格式错误包装结果return [{json: result}]Webhook KeyError通过_json.get(body, {})访问十、测试你的代码三种验证模式测试模式一处理空输入# ✅ 始终用空输入测试 all_items _input.all() if not all_items: return [{json: {message: No items to process}}] # 继续处理 # ...测试模式二测试缺失字段# ✅ 用 .get() 默认值字段缺失也不报错 item _input.first()[json] name item.get(name, Unknown) email item.get(email, no-email) age item.get(age, 0) return [{json: {name: name, email: email, age: age}}]测试模式三兼容两种运行模式# ✅ 两种模式下都能运行的代码 try: # 先尝试 Each Item 模式 current _input.item if current: return [{json: current[json]}] except: pass # 回退到 All Items 模式 all_items _input.all() return all_items if all_items else [{json: {message: No data}}]十一、总结与黄金法则需避开的 Top 5 错误ModuleNotFoundError—— 改用 JavaScript 或 n8n 节点缺少 return—— 始终以return [{json: {...}}]结尾KeyError—— 字典访问一律使用.get()IndexError—— 下标访问前先检查长度格式错误—— 返回[{json: {...}}]而非普通对象黄金法则不导入外部库需要时改用 JavaScript字典访问始终使用.get()始终返回[{json: {...}}]格式列表访问前检查长度通过[body]访问 webhook 数据最后提醒JavaScript 适用于约 95% 的场景Python 有明确限制无 requests、pandas、numpy复杂操作优先选用 n8n 专用节点。延伸阅读同一技能包内的配套文档SKILL.md —— Python Code 节点总览与快速上手DATA_ACCESS.md —— 数据访问模式与决策树STANDARD_LIBRARY.md —— 可用标准库模块全参考COMMON_PATTERNS.md —— 10 个生产级 Python 模式README.md —— 技能总览、何时用 Python 而非 JavaScript【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
n8n-mcp 实战Python Code 节点五大高频错误模式与系统化排查指南【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp导读本文是 n8n-mcp 项目中 Python Code 节点n8n Code node Python 模式的权威错误排查指南源自 ERROR_PATTERNS.md并融合了同目录 SKILL.md、DATA_ACCESS.md、STANDARD_LIBRARY.md 及仓库源码实现。读完本文你将掌握 n8n Python Code 节点最常见的五大错误外加一个 Bonus 错误的成因、报错形态、正确修复写法以及一套可落地的错误预防检查清单与测试模式能够直接排查并修复真实工作流中的 Python 节点故障。一、错误全景Top 5 高频错误总览在 n8n 的 Code 节点中Python 模式与 JavaScript 模式共享同一套数据与返回契约但 Python 因其标准库限制和语法特性产生了特有的高频错误。根据 ERROR_PATTERNS.md 的统计以下 5 类错误覆盖了 Python Code 节点失败的大多数场景#错误根因1ModuleNotFoundError导入外部库Python 特有2空代码 / 缺少 return没有代码或没有返回语句3KeyError未使用.get()直接访问字典键4IndexError未做边界检查直接按下标访问列表5返回格式错误返回了错误的数据结构这五类错误是 n8n Python Code 节点失败的主要来源下文逐一拆解。在动手排查前请先建立一条核心认知n8n 官方与本文所在技能体系都建议 95% 的场景优先使用 JavaScriptPython 仅在你明确需要标准库能力正则、哈希、统计等时使用详见 README.md。二、Error #1ModuleNotFoundError —— 最致命的 Python 特有错误频率Python Code 节点中非常常见。成因尝试导入 n8n Python 运行环境中不可用的外部库。n8n 默认只提供 Python 标准库没有 pip 包管理能力。2.1 错误现场# ❌ 错误外部库不可用 import requests # ModuleNotFoundError: No module named requests import pandas # ModuleNotFoundError: No module named pandas import numpy # ModuleNotFoundError: No module named numpy import bs4 # ModuleNotFoundError: No module named bs4 import pymongo # ModuleNotFoundError: No module named pymongo import psycopg2 # ModuleNotFoundError: No module named psycopg2 # 以下代码必然失败——这些库并未安装 response requests.get(https://api.example.com/data)2.2 解决方案方案一改用 JavaScript推荐覆盖约 95% 的场景// ✅ JavaScript Code 节点中使用 this.helpers.httpRequest() const response await this.helpers.httpRequest({ method: GET, url: https://api.example.com/data }); return [{json: response}];方案二用 n8n HTTP Request 节点替代在 Python Code 节点之前串联一个 HTTP Request 节点然后在前置节点的输出上继续处理# ✅ 在 Python Code 节点中读取上游 HTTP Request 节点的响应 response _input.first()[json] return [{ json: { status: response.get(status), data: response.get(body), processed: True } }]方案三仅使用标准库# ✅ 使用标准库 urllib功能有限无自定义 headers、无鉴权 from urllib.request import urlopen from urllib.parse import urlencode import json url https://api.example.com/data with urlopen(url) as response: data json.loads(response.read()) return [{json: data}]2.3 常见库替换对照表需求❌ 外部库✅ 替代方案HTTP 请求requestsHTTP Request 节点或 JavaScript数据分析pandasPython 列表推导式数据库psycopg2、pymongon8n 数据库节点Postgres/MySQL/MongoDB网页抓取beautifulsoup4HTML Extract 节点ExcelopenpyxlSpreadsheet File 节点图片处理pillow外部 API 或专用节点2.4 可用的标准库模块清单# ✅ 以下均可使用——标准库 import json # JSON 解析 import datetime # 日期/时间操作 import re # 正则表达式 import base64 # Base64 编码 import hashlib # 哈希MD5、SHA256 import urllib.parse # URL 解析与编码 import math # 数学函数 import random # 随机数 import statistics # 统计函数 import collections # defaultdict、Counter 等完整的可用模块与不可用模块清单含itertools、functools、os.path等分级说明见 STANDARD_LIBRARY.md。自托管例外外部包是否可用完全取决于实例的 Python runner 配置。若你的自托管实例明确声明了可用的额外包可以按实例实际情况使用详见 SKILL.md 中的说明。2.5 源码佐证官方 Python 示例同样遵守标准库约束仓库中的示例生成器 example-generator.ts 内置了nodes-base.code.pythonExample示例其实现完全遵循“仅标准库 _input.all()数据访问”的约束# Python data processing - use underscore prefix for built-in variables import json from datetime import datetime import re results [] # Use _input.all() to get items in Python for item in _input.all(): # Convert JsProxy to Python dict to avoid issues with null values item_data item.json.to_py() # Clean email addresses email item_data.get(email, ) if email and re.match(r^[\w\.-][\w\.-]\.\w$, email): cleaned_data { email: email.lower(), name: item_data.get(name, ).title(), validated: True, timestamp: datetime.now().isoformat() } else: cleaned_data dict(item_data) cleaned_data[validated] False cleaned_data[error] Invalid email format results.append({json: cleaned_data}) return results这段代码印证了三条关键实现事实只用json/datetime/re标准库用item.json.to_py()将 JsProxy 转为 Python dict避免空值问题统一以{json: ...}结构返回。同时仓库的表达式格式校验器 expression-format-validator.ts 明确将jsCode、pythonCode、functionCode视为“原始代码字段”跳过表达式检查——说明这些字段在项目中被当作不可外部校验的代码主体写好它们只能靠开发者遵守标准库与返回格式约束。三、Error #2空代码 / 缺少 Return频率所有 Code 节点均常见。成因代码节点内容为空或代码执行路径上没有return语句。3.1 错误现场# ❌ 错误空代码 # 什么都没有 # ❌ 错误有代码但没有 return items _input.all() processed [item for item in items if item[json].get(active)] # 忘了 return # ❌ 错误return 作用域错误 if _input.all(): return [{json: {result: success}}] # return 在 if 块内部——可能不会执行3.2 正确写法# ✅ 正确始终 return all_items _input.all() if not all_items: # 返回空数组或错误信息 return [{json: {error: No items}}] # 处理数据 processed [item for item in all_items if item[json].get(active)] # 末尾必须 return return processed if processed else [{json: {message: No active items}}]3.3 最佳实践无条件返回# ✅ 良好函数末尾无条件 return def process_items(): items _input.all() if not items: return [{json: {error: Empty input}}] # 处理 result [] for item in items: result.append({json: item[json]}) return result # 调用函数并返回结果 return process_items()将业务逻辑封装进函数、由主流程return process_items()兜底可以保证无论内部分支如何节点出口始终有返回值。四、Error #3KeyError —— 字典访问未用 .get()频率Python Code 节点中非常常见。成因直接以dict[key]形式访问不存在的字典键。4.1 错误现场# ❌ 错误直接按键访问 item _input.first()[json] name item[name] # 若 name 不存在则 KeyError email item[email] # 若 email 不存在则 KeyError age item[age] # 若 age 不存在则 KeyError return [{ json: { name: name, email: email, age: age } }]4.2 报错形态KeyError: name4.3 解决方案.get() 默认值# ✅ 正确使用带默认值的 .get() item _input.first()[json] name item.get(name, Unknown) email item.get(email, no-emailexample.com) age item.get(age, 0) return [{ json: { name: name, email: email, age: age } }]4.4 嵌套字典访问# ❌ 错误多层键直接访问 webhook _input.first()[json] name webhook[body][user][name] # 可能产生多个 KeyError # ✅ 正确逐层安全访问 webhook _input.first()[json] body webhook.get(body, {}) user body.get(user, {}) name user.get(name, Unknown) # ✅ 同样正确链式 .get() name ( webhook .get(body, {}) .get(user, {}) .get(name, Unknown) ) return [{json: {name: name}}]4.5 Webhook Body 访问关键n8n Python Code 节点最常见的单一错误是忘记 webhook 数据被嵌套在[body]之下。Webhook 节点会把 POST 数据、查询参数、JSON 载荷统一包装在body属性内# ❌ 错误忘记 webhook 数据位于 body 下 webhook _input.first()[json] name webhook[name] # KeyError email webhook[email] # KeyError # ✅ 正确通过 [body] 访问 webhook _input.first()[json] body webhook.get(body, {}) name body.get(name, Unknown) email body.get(email, no-email) return [{ json: { name: name, email: email } }]关于 webhook 完整结构headers、params、query、body、method、url以及_input.all()/_input.first()/_input.item/_node[Name]的选型决策树详见 DATA_ACCESS.md。五、Error #4IndexError —— 列表访问未做边界检查频率处理数组/列表时常见。成因直接按下标访问不存在的列表位置。5.1 错误现场# ❌ 错误假设元素必然存在 all_items _input.all() first_item all_items[0] # 列表为空则 IndexError second_item all_items[1] # 只有 1 个元素则 IndexError return [{ json: { first: first_item[json], second: second_item[json] } }]5.2 报错形态IndexError: list index out of range5.3 解决方案先检查长度# ✅ 正确先检查长度 all_items _input.all() if len(all_items) 2: first_item all_items[0][json] second_item all_items[1][json] return [{ json: { first: first_item, second: second_item } }] else: return [{ json: { error: fExpected 2 items, got {len(all_items)} } }]5.4 安全获取首元素# ✅ 正确用 _input.first() 代替 [0]内置安全保护 first_item _input.first()[json] return [{json: first_item}] # ✅ 同样正确访问前先判断 all_items _input.all() if all_items: first_item all_items[0][json] else: first_item {} return [{json: first_item}]5.5 用切片代替下标# ✅ 正确切片永远不会抛出 IndexError all_items _input.all() # 取前 5 个不足 5 个也不会失败 first_five all_items[:5] # 取第一个之后的全部为空也不会失败 rest all_items[1:] return [{json: item[json]} for item in first_five]六、Error #5返回格式错误频率新手用户常见。成因n8n 要求 Code 节点返回带json键的对象数组返回其他结构会导致下游节点无法解析。6.1 错误现场# ❌ 错误返回普通字典 return {name: Alice, age: 30} # ❌ 错误返回没有 json 包装的数组 return [{name: Alice}, {name: Bob}] # ❌ 错误返回 None return None # ❌ 错误返回字符串 return success # ❌ 错误返回单个对象而非数组 return {json: {name: Alice}}6.2 正确格式# ✅ 正确带 json 键的对象数组 return [{json: {name: Alice, age: 30}}] # ✅ 正确多条数据 return [ {json: {name: Alice}}, {json: {name: Bob}} ] # ✅ 正确批量转换 all_items _input.all() return [ {json: item[json]} for item in all_items ] # ✅ 正确空数组合法 return [] # ✅ 正确单条结果也要数组包装 return [{json: {result: success}}]为什么必须这样下游节点期望的是列表格式。格式错误会导致整个工作流执行失败详见 SKILL.md 的 Return Format Requirements 章节。6.3 常见场景场景一聚合返回单一结果# 计算总和 all_items _input.all() total sum(item[json].get(amount, 0) for item in all_items) # ✅ 正确用数组 json 包装 return [{ json: { total: total, count: len(all_items) } }]场景二过滤返回多条结果# 过滤活跃条目 all_items _input.all() active [item for item in all_items if item[json].get(active)] # ✅ 正确原样返回已是正确格式 return active # ✅ 同样正确若需转换 return [ {json: {**item[json], filtered: True}} for item in active ]场景三无结果# ✅ 正确返回空数组 return [] # ✅ 同样正确返回错误信息 return [{json: {error: No results found}}]七、Bonus 错误AttributeError —— 模式使用不当成因在错误的运行模式下使用了_input.item。7.1 错误现场# ❌ 错误在 All Items 模式使用 _input.item current _input.item # 在 All Items 模式下为 None data current[json] # AttributeError: NoneType object has no attribute __getitem__7.2 解决方案# ✅ 正确根据模式选择合适的方法 # All Items 模式使用 all_items _input.all() # Each Item 模式使用 current_item _input.item # ✅ 安全先判断 item 是否存在 current _input.item if current: data current[json] return [{json: data}] else: # 当前运行在 All Items 模式 return _input.all()_input.item仅在Run Once for Each Item模式下可用在默认的Run Once for All Items模式下为None。两种模式的选择依据、性能差异与示例代码见 SKILL.md。八、错误预防检查清单运行 Python Code 节点前逐项核验无外部导入仅使用标准库json、datetime、re 等代码返回数据每条执行路径都以return结尾格式正确返回[{json: {...}}]带 json 键的数组字典安全访问字典用.get()而非[]列表安全访问下标访问前检查长度或改用切片Webhook body 访问通过_json[body]访问 webhook 数据不返回 None用空数组[]代替None模式意识按运行模式正确使用_input.all()、_input.first()、_input.item九、快速修复参考表错误快速修复ModuleNotFoundError改用 JavaScript 或 HTTP Request 节点KeyError: field将data[field]改为data.get(field, default)IndexError: list index out of range访问items[0]前先if len(items) 0:输出为空在末尾添加return [{json: {...}}]AttributeError: NoneType检查模式设置或确认_input.item是否存在格式错误包装结果return [{json: result}]Webhook KeyError通过_json.get(body, {})访问十、测试你的代码三种验证模式测试模式一处理空输入# ✅ 始终用空输入测试 all_items _input.all() if not all_items: return [{json: {message: No items to process}}] # 继续处理 # ...测试模式二测试缺失字段# ✅ 用 .get() 默认值字段缺失也不报错 item _input.first()[json] name item.get(name, Unknown) email item.get(email, no-email) age item.get(age, 0) return [{json: {name: name, email: email, age: age}}]测试模式三兼容两种运行模式# ✅ 两种模式下都能运行的代码 try: # 先尝试 Each Item 模式 current _input.item if current: return [{json: current[json]}] except: pass # 回退到 All Items 模式 all_items _input.all() return all_items if all_items else [{json: {message: No data}}]十一、总结与黄金法则需避开的 Top 5 错误ModuleNotFoundError—— 改用 JavaScript 或 n8n 节点缺少 return—— 始终以return [{json: {...}}]结尾KeyError—— 字典访问一律使用.get()IndexError—— 下标访问前先检查长度格式错误—— 返回[{json: {...}}]而非普通对象黄金法则不导入外部库需要时改用 JavaScript字典访问始终使用.get()始终返回[{json: {...}}]格式列表访问前检查长度通过[body]访问 webhook 数据最后提醒JavaScript 适用于约 95% 的场景Python 有明确限制无 requests、pandas、numpy复杂操作优先选用 n8n 专用节点。延伸阅读同一技能包内的配套文档SKILL.md —— Python Code 节点总览与快速上手DATA_ACCESS.md —— 数据访问模式与决策树STANDARD_LIBRARY.md —— 可用标准库模块全参考COMMON_PATTERNS.md —— 10 个生产级 Python 模式README.md —— 技能总览、何时用 Python 而非 JavaScript【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
