AI Skills
n8n-code-python

n8n-code-python

熱門

在 n8n 的 Code 節點中撰寫 Python 程式碼。當需要在 n8n 中使用 Python、操作 _input/_json/_node 語法、使用標準函式庫，或需要了解 Python 在 n8n Code 節點中的限制時使用。請在使用者明確要求為 n8n Code 節點使用 Python 時採用此技能。注意 — 95% 的使用情境建議使用 JavaScript — 僅在使用者明確偏好 Python，或任務需要 Python 特有的標準函式庫功能（regex、hashlib、statistics）時才使用 Python。例外 — 若為 AI 代理可呼叫的自訂程式碼工具（@n8n/n8n-nodes-langchain.toolCode）中的 Python，請改用 n8n-code-tool 技能（輸入為 _query，回傳必須是字串）。

5858星標
983分支
更新於 2026/7/16
獲取技能源代碼

相關技能

telegram-bot-builder4.4萬sendcutsend8286dotnet-core-expert1.1萬
SKILL.md
readonlyread-only
name
n8n-code-python
description

在 n8n 的 Code 節點中撰寫 Python 程式碼。當需要在 n8n 中使用 Python、操作 _input/_json/_node 語法、使用標準函式庫，或需要了解 Python 在 n8n Code 節點中的限制時使用。請在使用者明確要求為 n8n Code 節點使用 Python 時採用此技能。注意 — 95% 的使用情境建議使用 JavaScript — 僅在使用者明確偏好 Python，或任務需要 Python 特有的標準函式庫功能（regex、hashlib、statistics）時才使用 Python。例外 — 若為 AI 代理可呼叫的自訂程式碼工具（@n8n/n8n-nodes-langchain.toolCode）中的 Python，請改用 n8n-code-tool 技能（輸入為 _query，回傳必須是字串）。

Python Code 節點（Beta）

在 n8n Code 節點中撰寫 Python 程式碼的專家指引。

⚠️ 重要：優先使用 JavaScript

建議：95% 的使用情境請使用 JavaScript。僅在以下情況使用 Python：

  • 你需要特定的 Python 標準函式庫功能
  • 你對 Python 語法明顯更熟悉
  • 你正在進行更適合 Python 的資料轉換

為什麼 JavaScript 是首選：

  • 完整的 n8n 輔助函式（this.helpers.httpRequest 等）
  • Luxon DateTime 函式庫用於進階日期/時間操作
  • 無外部函式庫限制
  • 更好的 n8n 文件與社群支援

快速入門

# Python Code 節點的基本範本
items = _input.all()

# 處理資料
processed = []
for item in items:
    processed.append({
        "json": {
            **item["json"],
            "processed": True,
            "timestamp": datetime.now().isoformat()
        }
    })

return processed

基本規則

  1. 優先考慮 JavaScript - 只在必要時使用 Python
  2. 存取資料：_input.all()、_input.first() 或 _input.item
  3. 關鍵：必須回傳 [{"json": {...}}] 格式
  4. 關鍵：Webhook 資料位於 _json["body"] 下（非直接 _json）
  5. 關鍵限制：無外部函式庫（無 requests、pandas、numpy）
  6. 僅標準函式庫：json、datetime、re、base64、hashlib、urllib.parse、math、random、statistics

模式選擇指南

與 JavaScript 相同 - 根據使用情境選擇：

對所有項目執行一次（建議 - 預設）

適用於： 95% 的使用情境

  • 運作方式：無論輸入數量為何，程式碼只執行一次
  • 資料存取：_input.all() 或 _items 陣列（原生模式）
  • 最佳用途：彙總、過濾、批次處理、轉換
  • 效能：處理多個項目時較快（單次執行）
# 範例：計算所有項目的總和
all_items = _input.all()
total = sum(item["json"].get("amount", 0) for item in all_items)

return [{
    "json": {
        "total": total,
        "count": len(all_items),
        "average": total / len(all_items) if all_items else 0
    }
}]

對每個項目執行一次

適用於： 僅特殊情況

  • 運作方式：對每個輸入項目分別執行程式碼
  • 資料存取：_input.item 或 _item（原生模式）
  • 最佳用途：項目特定邏輯、獨立操作、逐項驗證
  • 效能：處理大量資料時較慢（多次執行）
# 範例：為每個項目加入處理時間戳
item = _input.item

return [{
    "json": {
        **item["json"],
        "processed": True,
        "processed_at": datetime.now().isoformat()
    }
}]

Python 模式：Beta 與原生

n8n 提供兩種 Python 執行模式：

Python（Beta）- 建議使用

  • 使用：_input、_json、_node 輔助語法
  • 最佳用途：大多數 Python 使用情境
  • 可用輔助功能：_now、_today、_jmespath()
  • 匯入：from datetime import datetime
# Python（Beta）範例
items = _input.all()
now = _now  # 內建的 datetime 物件

return [{
    "json": {
        "count": len(items),
        "timestamp": now.isoformat()
    }
}]

Python（原生）（Beta）

  • 使用：僅 _items、_item 變數
  • 無輔助功能：無 _input、_now 等
  • 限制較多：僅標準 Python
  • 使用時機：需要純 Python 而不使用 n8n 輔助功能時
# Python（原生）範例
processed = []

for item in _items:
    processed.append({
        "json": {
            "id": item["json"].get("id"),
            "processed": True
        }
    })

return processed

建議：使用 Python（Beta） 以獲得更好的 n8n 整合。

資料存取模式

透過底線前綴的變數存取輸入資料。每個項目是形如 {"json": {...}} 的字典，因此實際欄位位於 ["json"] 下。

# 模式 1：_input.all() - 最常見。陣列、批次操作、彙總
all_items = _input.all()            # 回傳 {"json": {...}} 字典的清單

# 模式 2：_input.first() - 非常常見。單一物件、API 回應
data = _input.first()["json"]       # 內建安全性優於 all_items[0]

# 模式 3：_input.item - 僅限「對每個項目執行一次」模式
current = _input.item["json"]       # 在「所有項目」模式下為 None/錯誤

# 模式 4：_node - 參考特定名稱的節點
webhook_data = _node["Webhook"]["json"]
http_data = _node["HTTP Request"]["json"]

參閱：DATA_ACCESS.md 取得完整指南 — 六個 _input.all() 範例（過濾、轉換、彙總、排序、分組、去重）、_input.first() 與 _input.item 範例、多節點合併、JS 與 Python 變數對照表，以及決策樹。

關鍵：Webhook 資料結構

最常見錯誤：Webhook 資料巢狀於 ["body"] 下

# ❌ 錯誤 - 會引發 KeyError
name = _json["name"]
email = _json["email"]

# ✅ 正確 - Webhook 資料位於 ["body"] 下
name = _json["body"]["name"]
email = _json["body"]["email"]

# ✅ 更安全 - 使用 .get() 安全存取
webhook_data = _json.get("body", {})
name = webhook_data.get("name")

原因：Webhook 節點將所有請求資料包裝在 body 屬性下，包括 POST 資料、查詢參數和 JSON 負載。

參閱：DATA_ACCESS.md 取得完整的 Webhook 結構說明

回傳格式要求

關鍵規則：一律回傳包含 "json" 鍵的字典清單

正確的回傳格式

# ✅ 單一結果
return [{
    "json": {
        "field1": value1,
        "field2": value2
    }
}]

# ✅ 多個結果
return [
    {"json": {"id": 1, "data": "first"}},
    {"json": {"id": 2, "data": "second"}}
]

# ✅ 串列生成式
transformed = [
    {"json": {"id": item["json"]["id"], "processed": True}}
    for item in _input.all()
    if item["json"].get("valid")
]
return transformed

# ✅ 空結果（無資料可回傳時）
return []

# ✅ 條件式回傳
if should_process:
    return [{"json": processed_data}]
else:
    return []

錯誤的回傳格式

# ❌ 錯誤：字典未包裝在清單中
return {
    "json": {"field": value}
}

# ❌ 錯誤：清單缺少 json 包裝
return [{"field": value}]

# ❌ 錯誤：純字串
return "processed"

# ❌ 錯誤：結構不完整
return [{"data": value}]  # 應為 {"json": value}

為什麼重要：後續節點預期清單格式。格式錯誤會導致工作流程執行失敗。

參閱：ERROR_PATTERNS.md #2 取得詳細錯誤解決方案

關鍵限制：無外部函式庫

最重要的 Python 限制：預設安裝無法匯入外部套件。

自託管例外：外部套件的可用性完全取決於該實例的 Python 執行器設定。如果使用者表示其自託管實例的 Python 執行器環境中有特定套件，請使用它們 — 不要拒絕。若不確定，請詢問或僅撰寫標準函式庫程式碼。

❌ 不可用（會引發 ModuleNotFoundError）：requests、pandas、numpy、scipy、bs4/BeautifulSoup、lxml。

✅ 可用（僅標準函式庫）：json、datetime、re、base64、hashlib、urllib.parse、math、random、statistics。

替代方案

需要 HTTP 請求？

  • ✅ 在 Code 節點前使用 HTTP Request 節點
  • ✅ 或改用 JavaScript 並使用 this.helpers.httpRequest()（裸 $helpers 全域變數在任務執行器沙箱中未定義）

需要資料分析（pandas/numpy）？

  • ✅ 使用 Python statistics 模組進行基本統計
  • ✅ 或改用 JavaScript 處理大多數操作
  • ✅ 使用清單和字典手動計算

需要網頁爬取（BeautifulSoup）？

  • ✅ 使用 HTTP Request 節點 + HTML Extract 節點
  • ✅ 或改用 JavaScript 搭配正則表達式/字串方法

參閱：STANDARD_LIBRARY.md 取得完整參考

常見模式概覽

根據實際工作流程，最有用的 Python 模式包括：

  1. 資料轉換 - 使用串列生成式轉換所有項目
  2. 過濾與彙總 - 使用內建函式進行加總、過濾、計數
  3. 字串處理與正則表達式 - 使用 re 從文字中提取模式
  4. 資料驗證 - 驗證並清理資料，附加錯誤清單
  5. 統計分析 - 使用 statistics 模組計算平均數/中位數/標準差

可直接複製的程式碼片段位於 COMMON_PATTERNS.md，以及 10 個完整詳細的實際模式（多來源彙總、Markdown 解析、JSON 比較、CRM 標準化、字典查詢、Top-N 過濾等）。

錯誤預防 - 前 5 大錯誤

  1. 匯入外部函式庫（Python 特有）→ import requests 會引發 ModuleNotFoundError。請改用 HTTP Request 節點或 JavaScript。
  2. 程式碼為空或缺少回傳 → 每個路徑必須以 return [{"json": ...}] 結尾。
  3. 回傳格式錯誤 → 包裝在清單中：{"json": {...}} 改為 [{"json": {...}}]。
  4. 字典存取 KeyError → 使用 .get()：_json.get("user", {}).get("name", "Unknown")。
  5. Webhook body 巢狀 → 透過 ["body"] 讀取：_json.get("body", {}).get("email", "no-email")。

參閱：ERROR_PATTERNS.md 取得完整指南 — 每個錯誤附有錯誤與正確程式碼、錯誤訊息、巢狀存取修正、AttributeError 額外案例、預防檢查清單，以及快速修正表。

標準函式庫參考

最實用的模組：json（解析/產生）、datetime（日期 + timedelta）、re（正則表達式）、base64（編碼/解碼）、hashlib（雜湊）、urllib.parse（URL 操作）、statistics（平均數/中位數/標準差）。此外還有：math、random、collections、itertools、functools。

如需濃縮速查表及每個模組的完整範例，請參閱 STANDARD_LIBRARY.md。

最佳實務

1. 一律使用 .get() 存取字典

# ✅ 安全：欄位缺失時不會崩潰
value = item["json"].get("field", "default")

# ❌ 危險：欄位不存在時會崩潰
value = item["json"]["field"]

2. 明確處理 None/Null 值

# ✅ 良好：若為 None 則預設為 0
amount = item["json"].get("amount") or 0

# ✅ 良好：明確檢查 None
text = item["json"].get("text")
if text is None:
    text = ""

3. 使用串列生成式進行過濾

# ✅ Python 風格：串列生成式
valid = [item for item in items if item["json"].get("active")]

# ❌ 冗長：手動迴圈
valid = []
for item in items:
    if item["json"].get("active"):
        valid.append(item)

4. 回傳一致的結構

# ✅ 一致：一律使用含 "json" 鍵的清單
return [{"json": result}]  # 單一結果
return results  # 多個結果（已格式化）
return []  # 無結果

5. 使用 print() 進行除錯

# 除錯陳述會顯示在瀏覽器主控台（F12）
items = _input.all()
print(f"處理 {len(items)} 個項目")
print(f"第一個項目：{items[0] if items else 'None'}")

實際生產注意事項

SplitInBatches 迴圈語意

SplitInBatches 節點有兩個輸出：

  • main[0] = 完成 — 在所有批次完成後觸發一次
  • main[1] = 每個批次 — 每個批次都會觸發（迴圈本體）

請務必在完成輸出後加上 Limit 1 節點。

正確的節點參考語法

# ❌ 錯誤
data = _node['HTTP Request']['json']

# ✅ 正確 - 先呼叫 .first() 再存取 json
data = _node['HTTP Request'].first()['json']

Python 中無法使用跨迭代資料

$getWorkflowStaticData('global') 在 Python Beta 模式中可能無法使用。若需要在 SplitInBatches 迭代間累積資料，請改用 JavaScript Code 節點來處理累積邏輯。

何時使用 Python 與 JavaScript

使用 Python 時機：

  • ✅ 你需要 statistics 模組進行統計運算
  • ✅ 你對 Python 語法明顯更熟悉
  • ✅ 你的邏輯適合用串列生成式表達
  • ✅ 你需要特定的標準函式庫功能

使用 JavaScript 時機：

  • ✅ 你需要 HTTP 請求（this.helpers.httpRequest()）
  • ✅ 你需要進階日期/時間（DateTime/Luxon）
  • ✅ 你想要更好的 n8n 整合
  • ✅ 95% 的使用情境（建議）

考慮使用其他節點時機：

  • ❌ 簡單欄位對應 → 使用 Set 節點
  • ❌ 基本過濾 → 使用 Filter 節點
  • ❌ 簡單條件判斷 → 使用 IF 或 Switch 節點
  • ❌ 僅 HTTP 請求 → 使用 HTTP Request 節點

與其他技能的整合

可搭配使用：

n8n 表達式語法：

  • 表達式在其他節點中使用 {{ }} 語法
  • Code 節點直接使用 Python（無需 {{ }}）
  • 何時使用表達式 vs 程式碼

n8n MCP 工具專家：

  • 如何找到 Code 節點：search_nodes({query: "code"})
  • 取得設定協助：get_node({nodeType: "nodes-base.code"})
  • 驗證程式碼：validate_node({nodeType: "nodes-base.code", config: {...}})

n8n 節點設定：

  • 模式選擇（所有項目 vs 每個項目）
  • 語言選擇（Python vs JavaScript）
  • 了解屬性相依性

n8n 工作流程模式：

  • 轉換步驟中的 Code 節點
  • 何時在模式中使用 Python vs JavaScript

n8n 驗證專家：

  • 驗證 Code 節點設定
  • 處理驗證錯誤
  • 自動修正常見問題

n8n Code JavaScript：

  • 何時改用 JavaScript
  • JavaScript 與 Python 功能比較
  • 從 Python 遷移至 JavaScript

快速參考檢查清單

在部署 Python Code 節點前，請確認：

  • [ ] 已優先考慮 JavaScript - 僅在必要時使用 Python
  • [ ] 程式碼非空 - 必須包含有意義的邏輯
  • [ ] 存在回傳陳述 - 必須回傳字典清單
  • [ ] 正確的回傳格式 - 每個項目：{"json": {...}}
  • [ ] 資料存取正確 - 使用 _input.all()、_input.first() 或 _input.item
  • [ ] 無外部匯入 - 僅標準函式庫（json、datetime、re 等）
  • [ ] 安全的字典存取 - 使用 .get() 避免 KeyError
  • [ ] Webhook 資料 - 若來自 webhook，透過 ["body"] 存取
  • [ ] 模式選擇 - 大多數情況使用「所有項目」
  • [ ] 輸出一致 - 所有程式碼路徑回傳相同結構

其他資源

相關檔案

n8n 文件

準備好在 n8n Code 節點中撰寫 Python - 但請優先考慮 JavaScript！ 針對特定需求使用 Python，參考錯誤模式指南以避免常見錯誤，並有效利用標準函式庫。