n8n-code-javascript

JavaScript Code 節點

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

快速入門

// Code 節點的基本範本
const items = $input.all();

// 處理資料
const processed = items.map(item => ({
  json: {
    ...item.json,
    processed: true,
    timestamp: new Date().toISOString()
  }
}));

return processed;

基本規則

選擇「Run Once for All Items」模式（建議用於大多數情況）
存取資料：$input.all()、$input.first() 或 $input.item
回傳 [{json: {...}}]——這是標準且跨模式可移植的形式。在 Run Once for All Items 模式下，n8n 也會自動包裝單純的 return {…} 物件，所以那樣也能執行；真正會失敗的是回傳基本型別（字串/數字）或 null。
重要：Webhook 資料位於 $json.body 下（不是直接 $json）
可用的內建功能：this.helpers.httpRequest()（無認證——單純的 $helpers 全域變數在任務執行器沙箱中為 undefined，因此 $helpers.httpRequest() 會拋出 ReferenceError: $helpers is not defined）、DateTime（Luxon）、$jmespath()。不可用：this.helpers.httpRequestWithAuthentication（被拒絕清單封鎖）、$env（當 N8N_BLOCK_ENV_ACCESS_IN_NODE=true 時）、require()（除非在白名單中）。對於任何超出簡單未認證 GET 的請求（認證、分頁、重試），建議使用 HTTP Request 節點，並將 Code 節點保留給純邏輯。
執行個體白名單函式庫：自託管執行個體可透過 N8N_RUNNERS_ALLOWED_BUILT_IN_MODULES 和 N8N_RUNNERS_ALLOWED_EXTERNAL_MODULES（舊版：NODE_FUNCTION_ALLOW_BUILTIN / NODE_FUNCTION_ALLOW_EXTERNAL）將模組加入白名單。如果使用者說他們的執行個體允許特定模組（例如 axios、lodash、crypto），請透過 require() 使用它們——不要拒絕。如果不確定，請詢問或預設僅使用內建功能。
錯誤技能？ 如果你正在為附加於 AI 代理的 Custom Code Tool（@n8n/n8n-nodes-langchain.toolCode）撰寫程式碼，請停止——該節點有不同的合約（透過 query 輸入，必須回傳字串，沒有 $input/$helpers）。請使用 n8n-code-tool 技能。

模式選擇指南

Code 節點提供兩種執行模式。根據你的使用案例選擇：

Run Once for All Items（建議，預設）

使用此模式於： 95% 的使用案例

運作方式：無論輸入數量為何，程式碼執行一次
資料存取：$input.all() 或 items 陣列
最佳用途：彙總、篩選、批次處理、轉換、使用所有資料進行 API 呼叫
效能：對於多個項目較快（單次執行）

// 範例：計算所有項目的總和
const allItems = $input.all();
const total = allItems.reduce((sum, item) => sum + (item.json.amount || 0), 0);

return [{
  json: {
    total,
    count: allItems.length,
    average: total / allItems.length
  }
}];

何時使用：

✅ 比較資料集中的項目
✅ 計算總和、平均值或統計資料
✅ 排序或排名項目
✅ 去除重複
✅ 建立彙總報告
✅ 合併多個項目的資料

Run Once for Each Item

使用此模式於： 僅限特殊情況

運作方式：程式碼為每個輸入項目分別執行
資料存取：$input.item 或 $item
最佳用途：特定項目的邏輯、獨立操作、每個項目的驗證
效能：對於大型資料集較慢（多次執行）

// 範例：為每個項目加入處理時間戳記
const item = $input.item;

return [{
  json: {
    ...item.json,
    processed: true,
    processedAt: new Date().toISOString()
  }
}];

何時使用：

✅ 每個項目需要獨立的 API 呼叫
✅ 每個項目的驗證，且錯誤處理方式不同
✅ 根據項目屬性進行特定轉換
✅ 當項目必須為商業邏輯而分別處理時

決策捷徑：

需要查看多個項目？ → 使用「All Items」模式
每個項目完全獨立？ → 使用「Each Item」模式
不確定？ → 使用「All Items」模式（你總可以在內部進行迴圈）

為什麼「All Items」較快——每項目的邊界

模式選擇是 Code 節點中最大的效能槓桿。每個 per-item 執行上下文都會產生設定成本（在 n8n 2.x 上測量，小型記錄）：

每個項目執行的內容	大約成本
Code All Items（整個集合執行一次）	~0.02 ms/項目
任何節點中的運算式（IF / Set 等）	~0.2 ms/項目
Code Each Item（每個項目一個完整沙箱）	~0.6 ms/項目——約為 All Items 的 25–30 倍

因此，對 10k 個項目使用 Run Once for Each Item 會產生約 6 秒的純開銷，而 Run Once for All Items 僅約 0.2 秒。僅在項目確實需要隔離時（獨立錯誤處理，或無法批次處理的每個項目 API 呼叫）才使用 Each Item；否則在一個 All Items 節點內部進行迴圈。運算式複雜度本身基本上免費（約 90% 的成本來自每個項目的上下文，而非你的程式碼），而每個節點→節點的跳躍都會重新複製所有項目——因此請減少 per-item 邊界的數量，不要微觀最佳化每個邊界。在幾百個項目以下時，這些都不重要；在熱路徑上（大量項目、少量 I/O）才需要考慮。

參見：DATA_ACCESS.md →「Mode Performance」以了解推論、跳躍成本和規模檢查。

資料存取模式

從上游節點提取資料的四種方式。請注意 $node["Name"] 和 $('Name') 需要 .first().json 或 .all()——永遠不要直接使用 .json。

const allItems = $input.all();          // 1. 所有項目——批次操作、彙總（最常見）
const data = $input.first().json;       // 2. 第一個項目——單一物件、API 回應
const item = $input.item;               // 3. 當前項目——僅限「Each Item」模式（否則為 undefined）
const other = $node["Webhook"].json;    // 4. 具名節點——跨節點合併資料

始終透過 .json 存取欄位（例如 item.json.name，而非 item.name），並優先使用明確的 $input.first().json.field 而非單純的 $json.field。

參見：DATA_ACCESS.md 以取得完整指南——每個模式的範例、決策樹以及常見錯誤（修改原始資料、缺少長度檢查、在錯誤模式下使用 $input.item）。

重要：Webhook 資料結構

最常見的錯誤：Webhook 資料巢狀於 .body 下

// ❌ 錯誤 - 會回傳 undefined
const name = $json.name;
const email = $json.email;

// ✅ 正確 - Webhook 資料位於 .body 下
const name = $json.body.name;
const email = $json.body.email;

// 或使用 $input
const webhookData = $input.first().json.body;
const name = webhookData.name;

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

參見：DATA_ACCESS.md 以取得完整的 Webhook 結構詳細資訊

回傳格式要求

標準形式：[{json: {...}}]——一個物件陣列，每個物件都有一個 json 屬性。它明確無誤，且在兩種執行模式中行為相同，因此請將其設為預設。

在 Run Once for All Items 模式下，n8n 會自動正規化較寬鬆的形狀：單一的裸物件或裸物件陣列會自動被包裝在 json 下。因此 return {foo: 1} 可以執行。而沒有東西可包裝——因此真正會在執行時失敗並顯示「Code doesn't return items properly」——的是基本型別（字串/數字/布林值）或 null/undefined。（n8n-mcp ≥ 2.63.0 不再將裸物件回傳標記為錯誤；它反映了這種自動包裝行為。）

正確的回傳格式

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

// ✅ 多個結果
return [
  {json: {id: 1, data: 'first'}},
  {json: {id: 2, data: 'second'}}
];

// ✅ 轉換後的陣列
const transformed = $input.all()
  .filter(item => item.json.valid)
  .map(item => ({
    json: {
      id: item.json.id,
      processed: true
    }
  }));
return transformed;

// ✅ 空結果（當沒有資料要回傳時）
return [];

// ✅ 條件式回傳
if (shouldProcess) {
  return [{json: processedData}];
} else {
  return [];
}

非標準回傳（自動包裝——建議使用標準形式）

// ⚠️ 在 All Items 模式下自動包裝 → [{json: {field: value}}]。可以執行，但建議使用陣列形式。
return {
  json: {field: value}
};

// ⚠️ 自動包裝 → [{json: {field: value}}]。可以執行，但為了清楚起見請加上 json 包裝。
return [{field: value}];

// ✅ 沒問題——輸入項目已帶有 json 屬性，因此原樣回傳是有效的直通
return $input.all();

真正會失敗的回傳

// ❌ 失敗：基本型別——n8n 錯誤「Code doesn't return items properly」
return "processed";

// ❌ 失敗：null / undefined——沒有東西可傳遞給下一個節點
return null;

為什麼重要：標準的 [{json: {...}}] 明確無誤，且在兩種模式中行為相同。n8n 在 All Items 模式下會自動正規化裸物件和物件陣列，但基本型別或 null 回傳沒有東西可包裝，因此會停止執行。

參見：ERROR_PATTERNS.md #3 以取得詳細的錯誤解決方案

常見模式概覽

來自生產工作流程中最實用的 Code 節點形狀。一個快速範例——跨所有項目的總和/彙總：

const items = $input.all();
const total = items.reduce((sum, item) => sum + (item.json.amount || 0), 0);
return [{ json: { total, count: items.length, average: total / items.length } }];

完整函式庫涵蓋 10 種模式：多來源彙總、正規表示式篩選、Markdown/結構化文字解析、JSON 比較、CRM/表單轉換、版本處理、含計算欄位的陣列轉換、Slack Block Kit 格式化、前 N 名排名以及字串彙總報告——每種都有變體。

參見：COMMON_PATTERNS.md 以取得 10 個詳細的生產模式（以及最佳實務章節：驗證輸入、try-catch、及早篩選、使用陣列方法而非迴圈、console.log 除錯）。

錯誤預防 - 最常見的錯誤

反覆出現的 Code 節點失敗，按大致頻率排序：

空的程式碼 / 缺少回傳——始終以 return [...] 結尾，並確保每個分支都有回傳。
將運算式語法當作程式碼——不要在 JavaScript 所在之處寫 {{ }}（return {{ $json.x }} 是語法錯誤）。使用 `${$json.field}` 或 $input.first().json.field。{{ }} 在字串字面值內部 是沒問題的——它只是 n8n 不會評估的文字。
回傳形狀——建議使用 return [{json:{...}}]。單純的 return {…} 在 All Items 模式下會自動包裝，但回傳基本型別（字串/數字）或 null 才是真正會失敗的。
缺少 null 檢查——使用可選鏈：item.json?.user?.email || 'fallback'。
Webhook body 巢狀——$json.email 是 undefined；請使用 $json.body.email。
認證輔助函式被封鎖（httpRequestWithAuthentication）和 $env 被封鎖——將機密透過憑證/HTTP Request 節點傳遞，而非 Code 節點沙箱。

參見：ERROR_PATTERNS.md 以取得完整指南——每個錯誤附有錯誤/正確程式碼、跳脫規則、沙箱限制（錯誤 #6–#7）、預防檢查清單以及快速錯誤訊息查詢表。

內建函式與輔助函式

// HTTP 請求（無認證——請參閱下方的沙箱說明）
const res = await this.helpers.httpRequest({ method: 'GET', url: 'https://api.example.com/data' });

// DateTime（Luxon）：現在時間、格式化、算術
const now = DateTime.now();
const formatted = now.toFormat('yyyy-MM-dd');
const tomorrow = now.plus({ days: 1 });

// $jmespath()——查詢 JSON 結構
const adults = $jmespath($input.first().json, 'users[?age >= `18`]');

// $getWorkflowStaticData()——跨執行持續存在的資料

沙箱（自 n8n v2.0 起，JsTaskRunnerSandbox）： 存取器是 this.helpers.httpRequest()——單純的 $helpers 全域變數在此為 undefined（$helpers.httpRequest() 會拋出 ReferenceError）。在巢狀的非同步函式中，如果 this 遺失，請以 await fn.call(this, ...) 呼叫。this.helpers.httpRequestWithAuthentication 和 this.helpers.requestWithAuthenticationPaginated 被拒絕清單封鎖（→ UnsupportedFunctionError）；對於需要認證的呼叫，請使用 HTTP Request 節點（建議）搭配憑證、子工作流程，或僅在 token 已作為資料流經工作流程時，在 this.helpers.httpRequest() 上手動加入 Authorization: Bearer ${token} 標頭。當 N8N_BLOCK_ENV_ACCESS_IN_NODE=true 時，$env 被封鎖；require() 僅對白名單中的模組有效。Buffer、URL 和標準 JS 全域物件（Math、JSON、Object、Array）始終可用。

參見：BUILTIN_FUNCTIONS.md 以取得完整參考——完整的 httpRequest 選項、所有 DateTime/Luxon 操作、JMESPath 模式、靜態資料使用案例以及沙箱限制詳細資訊。

最佳實務

先驗證輸入——在處理前檢查空陣列 / 缺少 .json。
對高風險工作使用 try-catch（HTTP 呼叫）並回傳錯誤物件而非讓程式崩潰。
偏好陣列方法（filter/map/reduce）而非手動迴圈。
及早篩選，延後轉換——在進行昂貴工作前縮小資料集。
使用描述性名稱和 console.log() 進行除錯（輸出會顯示在瀏覽器主控台中）。

參見：COMMON_PATTERNS.md →「Best Practices」以取得每個項目的程式碼範例。

生產環境注意事項

來自實際部署的寶貴經驗——摘要如下，程式碼請見 DATA_ACCESS.md →「Production Gotchas」：

SplitInBatches 的輸出違反直覺：main[0] = 完成（觸發一次，在所有批次之後），main[1] = 每個批次（迴圈本體）。在完成輸出後加入一個 Limit 1 節點作為安全措施。
疊代次數就是成本：每次迴圈疊代都會重新執行整個本體（約 0.8 ms 開銷）。batchSize: 1 相當於 Each Item 的迴圈版本——請使用你的實際限制（速率限制、頁面大小、記憶體）允許的最大批次大小，或者根本不使用迴圈。
跨疊代累積（重要）：迴圈結束後，$('Node Inside Loop').all() 只回傳 最後一次 疊代的項目。請透過 $getWorkflowStaticData('global') 累積（在迴圈前重設，在迴圈內推入，在迴圈後讀取）。
pairedItem：當發出的項目與輸入並非 1:1 對應時，請設定 pairedItem: { item: i }，否則下游的 Set 節點會因 paired_item_no_info 而失敗。
節點參考語法：$('Node').first().json 或 $('Node').all()——永遠不要在參考上直接使用 .json。
浮點數精度：在分位數層級比較金額——Math.round(a*100) !== Math.round(b*100)——以避免因浮點數雜訊而產生誤判。

何時使用 Code 節點

在動用 Code 節點之前，請先走過轉換關卡：在 n8n Expression Syntax 技能中，依序嘗試：運算式 → Edit Fields 欄位中的箭頭函式 IIFE → Code 節點。前兩種路徑涵蓋大多數「轉換此資料」的任務，每個約需 1–10ms，而 Code 節點的沙箱化約需 500–1000ms——在純單一項目塑形上差距約 100 倍，且功能上沒有差異。Code 節點只有在需要整個資料集彙總（$input.all()）、白名單函式庫或非同步工作時才值得使用。在為加密（HMAC、雜湊、簽章）或 XML/SOAP/RSS 解析撰寫程式碼之前，請先檢查是否有 原生節點——n8n 有 Crypto 節點（nodes-base.crypto）和 XML 節點（nodes-base.xml）可以處理這些需求，無需任何 JavaScript。為了原生節點已能處理的事情而跳入 Code 節點，是最常見的誤判之一。

在以下情況使用 Code 節點：

✅ 需要多個步驟的複雜轉換
✅ 自訂計算或商業邏輯
✅ 遞迴操作
✅ 具有複雜結構的 API 回應解析
✅ 多步驟條件判斷
✅ 跨項目資料彙總

在以下情況考慮其他節點：

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

Code 節點擅長：需要串聯許多簡單節點的複雜邏輯

與其他技能的整合

搭配使用：

n8n Expression Syntax：

運算式在其他節點中使用 {{ }} 語法
Code 節點直接使用 JavaScript（無 {{ }}）
何時使用運算式 vs 程式碼

n8n MCP Tools Expert：

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

n8n Node Configuration：

模式選擇（All Items vs Each Item）
語言選擇（JavaScript vs Python）
了解屬性相依性

n8n Workflow Patterns：

轉換步驟中的 Code 節點
Webhook → Code → API 模式
工作流程中的錯誤處理

n8n Validation Expert：

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

快速參考檢查清單

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

[ ] 程式碼不為空 - 必須有有意義的邏輯
[ ] 存在回傳陳述式 - 回傳項目，而非基本型別/null
[ ] 標準回傳格式 - 每個項目：{json: {...}}（裸物件會自動包裝，但請明確寫出）
[ ] 資料存取正確 - 使用 $input.all()、$input.first() 或 $input.item
[ ] 沒有將 {{ }} 寫成程式碼 - 使用 JavaScript 樣板字面值：`${value}`
[ ] 錯誤處理 - 對 null/undefined 輸入使用防護子句
[ ] Webhook 資料 - 如果來自 webhook，請透過 .body 存取
[ ] 模式選擇 - 大多數情況使用「All Items」
[ ] 效能 - 偏好 map/filter 而非手動迴圈
[ ] 輸出一致 - 所有程式碼路徑回傳相同結構

其他資源

n8n 文件

Code 節點指南：https://docs.n8n.io/code/code-node/
內建方法：https://docs.n8n.io/code-examples/methods-variables-reference/
Luxon 文件：https://moment.github.io/luxon/

準備好在 n8n Code 節點中撰寫 JavaScript！ 從簡單的轉換開始，使用錯誤模式指南避免常見錯誤，並參考模式函式庫以取得生產就緒的範例。

您可能也喜歡

kubernetes-patterns

240Kbackend-api

Kubernetes workload patterns, resource management, RBAC, probes, autoscaling, ConfigMap/Secret handling, and kubectl debugging for production-grade deployments. Use when writing or reviewing Kubernetes manifests, or debugging probes, RBAC, autoscaling, or resource limits.

affaan-m

獲取

flox-environments

237Kbackend-api

使用宣告式 Nix 架構的環境管理工具 Flox，打造可重現且跨平台（macOS/Linux）的開發環境。適用於以下情境：建置任何語言的專案工具鏈、安裝系統級相依套件（編譯器、資料庫、openssl/BLAS 等原生函式庫）、為團隊固定精確的套件版本、執行本機服務（PostgreSQL、Redis、Kafka）、一行指令讓新開發者快速上手，或解決「在我的電腦上明明可以執行」的問題——包含需要專案專用工具且免 sudo 權限的 agent/vibe-coding 設定。當使用者提及 .flox/、manifest.toml、flox activate 或 FloxHub 時亦可使用。

affaan-m

獲取

cloud

107Kbackend-api

Browser Use Cloud 技術參考文件 — 這是用於瀏覽器自動化的雲端託管 API 與 SDK。當使用者需要關於 Cloud REST API (v2 或 v3)、browser-use-sdk (Python 或 TypeScript)、X-Browser-Use-API-Key 身份驗證、雲端 Session、瀏覽器設定檔 (profiles)、設定檔同步、CDP WebSocket 連線、隱形瀏覽器 (stealth browsers)、住宅代理 (residential proxies)、驗證碼處理 (CAPTCHA)、webhooks、工作區 (workspaces)、Skill 市集、liveUrl 即時串流、價格計費，或整合模式（聊天 UI、子 Agent、為現有 Agent 新增瀏覽器工具）等協助時，請使用此 Skill。當詢問有關 n8n/Make/Zapier 整合、於雲端基礎架構執行 Playwright/Puppeteer/Selenium，或 1Password 保險箱整合等問題時亦可觸發。請注意：切勿將此 Skill 用於開源版 Python 函式庫（Agent、Browser、Tools 設定）— 請改用開源版 Skill。

browser-use

獲取

繼續探索

瀏覽 backend-api 熱門 Skills 最近更新

n8n-code-javascript

相關技能

JavaScript Code 節點

快速入門

基本規則

模式選擇指南

Run Once for All Items（建議，預設）

Run Once for Each Item

為什麼「All Items」較快——每項目的邊界

資料存取模式

重要：Webhook 資料結構

回傳格式要求

正確的回傳格式

非標準回傳（自動包裝——建議使用標準形式）

真正會失敗的回傳

常見模式概覽

錯誤預防 - 最常見的錯誤

內建函式與輔助函式

最佳實務

生產環境注意事項

何時使用 Code 節點

與其他技能的整合

搭配使用：

快速參考檢查清單

其他資源

相關檔案

n8n 文件

您可能也喜歡

kubernetes-patterns

flox-environments

cloud

繼續探索