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-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），僅供參考