n8n Code 节点明确要求 Python 时：用原生…

当用户在 n8n 2.x Code 节点中明确要求 Python，或迁移旧 Pyodide Python 代码并遇到 _input/_json NameError、导入被禁、构建类失败、返回值错误或 Python runner 不可用时，按本经验操作。

适用场景

解决思路

1. 仅当用户明确要求 Python 时才用 Python Code node；否则优先 JavaScript Code node、表达式、Edit Fields 或原生节点（Crypto、Date & Time、HTML、XML）。
2. 使用 n8n 2.x 原生 Python：Code node 配置 language: pythonNative、mode: runOnceForAllItems 或 runOnceForEachItem、pythonCode: ...，节点为 n8n-nodes-base.code typeVersion 2。
3. Run Once for All Items 模式下：用 _items，它是由 plain dict {'json': {...}, 'pairedItem': {...}} 组成的 list；返回例如 [{'json': {'name': it['json']['name'], 'revenue': it['json']['revenue']}} for it in _items if it['json'].get('active')]。
4. Run Once for Each Item 模式下：用 _item，它是一个 plain dict {'json': {...}, 'pairedItem': {...}}；返回例如 {'json': {**row, 'name_upper': (row.get('name') or '').upper()}}，其中 row = _item['json']。
5. 每个变量只在自己的模式存在：all-items 模式不要用 _item，each-item 模式不要用 _items，否则 NameError。
6. 只允许字典访问：it['json']['name'] 或 it['json'].get('name')；不要 it.json.name，否则 AttributeError: 'dict' object has no attribute 'json'。
7. 没有其他节点访问方式：没有 _node / $('Node') 等价物；需要其他分支数据先用 Merge 引入，或改用 JavaScript。
8. Webhook payload 在 ['body'] 下：用 _items[0]['json'].get('body', {}).get('email')。
9. 二进制数据不在本技能覆盖：在 JavaScript 中读写二进制，见 n8n-binary-and-data。
10. pairedItem：返回 _items 或 _item 会保留；构造新 dict 且下游使用 $('Node').item 时，给每个返回项加 'pairedItem': {'item': i}；native Python 尚未验证，依赖前先测试。
11. 缺失键优先用 .get(key, default)；row['missing'] 会 KeyError。
12. 迁移 legacy Pyodide 代码：_input.all() → _items。
13. 迁移：_input.first()['json'] → _items[0]['json']（并用 if _items 保护）。
14. 迁移：_input.item / _json → _item / _item['json']。
15. 迁移：_node['X'] → 不可用；用 Merge 上游，或改 JS。
16. 迁移：_now、_today → 不可用；通过 Edit Fields 传入 {{ $now.toISO() }}，或改 JS。
17. 迁移：_jmespath(data, q) → 不可用；用表达式中的 $jmespath，或列表推导。
18. 迁移：item.json.field → item['json']['field']。
19. Imports 默认全被阻止：每个 import（标准库和第三方）在代码运行前按 allowlist 检查；默认 allowlist 为空，所以 import json 也会以 Security violations detected 拒绝整个节点。
20. n8n Cloud 完全不允许 imports。
21. 自托管时 admin 可在 task-runner config 中 allowlist 模块（见 n8n-self-hosting → TASK_RUNNERS.md）；有些实例允许 json、datetime、re，大多数不允许，不要假设。
22. 默认写无 import 代码。若 import 确实有帮助，先确认：用一行测试节点 import json + return [{'json': {'ok': True}}]，或询问用户；绝不假设。
23. 无 import 替代：JSON 字符串在上游解析（Edit Fields 中用 {{ JSON.parse($json.payload) }}）。
24. 无 import 替代：日期运算用表达式（Luxon）或 JS；ISO-8601 字符串仍可按普通字符串比较和排序。
25. 无 import 替代：哈希用 Crypto node。
26. requests、pandas、numpy 除非 admin 构建 custom runner image，否则永不可用；HTTP 用 HTTP Request node。
27. 沙箱拒绝的 builtins：eval、exec、compile、open、input、type、getattr、setattr、hasattr、vars、dir、globals、locals、object、memoryview、breakpoint，运行时报 NameError: name 'type' is not defined 等；改用 isinstance(x, dict)、key in d、d.get(key)。
28. 不要定义 class Foo；会报 __build_class__ not found；改用 dict 加函数。
29. 不要访问 dunder 或动态导入：x.__class__、'{0.__class__}'.format(x)、__import__('json') 会 Security violations detected，并在运行前拒绝整个节点。
30. 函数内不要用 global counter；因为代码运行在 wrapper function 中会 NameError；改用 nonlocal counter。
31. 可安全使用 plain Python：comprehensions、generators、lambdas、closures、recursion、try/except、f-strings / .format() / %、sorted/min/max/sum/any/all/enumerate/zip/round、sets、isinstance、print()（输出到浏览器 console）。
32. Run Once for All Items 返回形状：返回 [{'json': {...}}, ...] 得到 canonical N items；返回 [{...}, ...] 纯 dict 会自动包到 json 下，N items；返回 {'json': {...}} 或单个纯 dict 得到 1 item；返回原地修改的 _items 会 passthrough 你的修改；返回 None / 无 return 报 Cannot read properties of null (reading 'json')。
33. Run Once for Each Item 返回形状：返回 {'json': {...}}、纯 dict 或 _item 得到 1 item；返回 None 会丢弃该 item（内置 filter）；返回 list 报 A 'json' property isn't a dictionary [item 0]。
34. 输出值转换：tuple 变 list；set 变字符串 '{1, 2}'；datetime 变 str(dt)（如 '2026-09-16 10:18:00.025792'，不是 ISO）；显式转换（sorted(s)、dt.isoformat()）。
35. 明确优先显式返回形状：all-items 模式用 [{'json': ...}]，each-item 模式用 {'json': ...}；自动包装可用但显式更清楚。
36. 错误处理：普通 raise ValueError('bad row') 会让节点失败并显示该消息。onError continue 模式下三类失败不同：运行时异常（raise、KeyError、NameError、禁用 builtin）在 continueErrorOutput 时把 {'error': '<message>'} 放到 error output（main[1]）✅，在 continueRegularOutput 时放到 main output。
37. 静态拒绝（Security violations detected：import、dunder）：节点标记 failed，但输入 items 原样从 success output 出去；main[1] 保持空。continueRegularOutput 时输入 item 原样在 main output。
38. 错误返回形状（each-item 模式返回 list、all-items 模式返回 None）：同样把未修改的输入放到 success output。最后两类是 silent-data trap：下游收到未处理输入且执行显示 success，没有 error branch 能捕获。
39. 预防 silent-data trap：除非已确认 allowlist，否则不加 import；保证返回形状匹配模式；用真实测试运行检查 Code node 状态和输出（见 n8n-error-handling）。
40. 其他消息：Python runner unavailable: Python 3 is missing from this system 表示自托管实例没有 Python task runner（stock image 不带）；这是基础设施问题，不是代码问题；见 n8n-self-hosting → TASK_RUNNERS.md。
41. validate_node / validate_workflow 能抓一些 Python 错误（import requests、缺少 return、return None），但不能抓 _input/_json、点访问、被阻止的 stdlib import、dunder 访问或 class；只有测试执行可靠。
42. 性能：每个 Python Code node 约 0.4 s（runner 冷启动约 1 s），明显比 JS Code node 或表达式慢；用 Run Once for All Items 处理列表，不要逐项处理，不要串联多个小 Python 节点。
43. Checklist：确认用户确实要 Python；模式与变量匹配（_items all-items / _item each-item）；只用 dict 访问，无 _input/_json/_node/_now/_jmespath；除非确认此实例 allowlist，否则无 import；无 class、type()、getattr/hasattr 或 dunder；用 nonlocal 不用 global；返回形状匹配模式；显式转换 set 和 datetime；运行真实测试并检查输出 items。
44. 参考 COMMON_PATTERNS.md 中的 12 个无 import 模式（filter、aggregate、group、dedupe、top N、flatten、validate、drop items、text report、safe nested access、running totals、ISO timestamps），每个都在 live n8n 验证。
45. 相关技能：默认 Code node 用 n8n-code-javascript；$jmespath、Luxon 和 transform gatekeeper 见 n8n-expression-syntax；AI-agent Custom Code Tool 的 Python 用 n8n-code-tool；错误输出见 n8n-error-handling；启用 Python task runner 和 allowlist 见 n8n-self-hosting。

适用边界 · 注意事项

• 用户没有明确要求 Python 时，不要用；优先 JavaScript、表达式或原生节点。
• AI-agent-callable Custom Code Tool（@n8n/n8n-nodes-langchain.toolCode）不要用本技能；改用 n8n-code-tool，因为输入是 _query，返回值必须是字符串。
• 需要 n8n helpers、imports、二进制处理、跨节点读取或大量小节点时，不适用；改用 JavaScript 或相应节点。