跳轉到

自創第一個 Community Node 實作教學

這章不是只講概念，而是帶你從零開始，照官方 n8n-node 工具的方式，真的 scaffold 一個自己的 community node 專案。

這章要解決什麼

學完前一章，你已經知道 community nodes 是什麼，也知道可以自己做。這一章要往前再走一步：把「我知道可以做」變成「我真的能開始做」。

這裡不會一開始就做超複雜的 node。我們的目標是先做出一個最小可開發、可 build、可在本機 n8n 看見的 node 專案。先把骨架跑通，再談進階功能。

想一想

很多人第一次想做 community node，會直接把目標設成「我要封裝某個完整 SaaS 平台」。這通常太大。比較好的起點不是追求功能完整，而是先做出一條能成功跑完的開發鏈。也就是：你能不能 scaffold 專案、看懂產生的檔案、成功 build、成功在本機 n8n 裡看到自己的 node、然後改一點東西再看到變化。只要這條鏈打通，後面你學的是節點設計，而不是一直卡在環境。

你也要接受一件事：自創 node 跟用 node 是兩種不同能力。用 node 比較像 workflow 設計；做 node 比較像產品封裝。前者重在資料流與整合，後者重在 API 模型、欄位設計、錯誤處理、版本管理。如果你把這兩件事混在一起，很容易在一開始就覺得太難。這章的目的，就是先把「做 node」拆小，讓你知道第一步其實可以很務實。

1. 先理解這章的目標

這章要做的是：

  1. 建立一個新的 community node 專案
  2. 知道要選 declarative 還是 programmatic
  3. 把專案 build 起來
  4. 用本機 n8n 載入並測試
  5. 知道之後怎麼發佈到 npm

不做的事：

  • 不在這章硬塞完整商業 API 封裝
  • 不在這章做 verified 提交流程的所有細節
  • 不在這章把每個檔案都拆到最細

2. 你需要的前置條件

根據 n8n 官方開發環境文件，建立 community node 前，至少要準備：1

  • Node.js
  • npm
  • git
  • 本機可用的 n8n

官方目前文件提到，節點開發環境需要 Node.js 22.22.0 以上。1

如果你只是想學 workflow，不一定要升到這個版本；但如果你要正式跟官方最新 n8n-node 工具走，最好讓 node 開發專案使用符合要求的 Node 版本。

3. 兩種 node 類型先分清楚

官方 n8n-node 在建立專案時，會問你要做哪種 node：2

1. HTTP API

意思： - declarative style - 低程式量 - 比較適合標準 REST API

適合： - 你要接的是一般 CRUD API - 你想比較快做出第一版

2. Other

意思： - programmatic style - 自己寫邏輯 - 彈性高

適合： - API 很特別 - 需要大量自訂邏輯 - 不是單純 HTTP CRUD

如果你是第一次做，我建議：

  • 第一個專案先選 HTTP API
  • 第二個再碰 programmatic

4. 用官方工具建立第一個專案

官方目前最推薦的起手式是：2

npm create @n8n/node@latest

這會直接幫你建立一個 community node 專案，不需要你先全域安裝 CLI。

如果你已經想好名字，也可以直接指定：

npm create @n8n/node@latest n8n-nodes-myproject

如果要直接指定模板，寫法是：

npm create @n8n/node@latest n8n-nodes-myproject -- --template declarative/custom

注意那個 -- 很重要。因為這是 npm create 轉交參數給 scaffold 工具的寫法。

5. 建議你第一個專案怎麼命名

官方要求 package name 必須符合這兩種格式之一：23

  • n8n-nodes-<YOUR_NODE_NAME>
  • @<YOUR_ORG>/n8n-nodes-<YOUR_NODE_NAME>

例如：

n8n-nodes-my-first-tool

或：

@tungyu6/n8n-nodes-my-first-tool

如果你只是本機練習，先用不帶 scope 的簡單名字就好。

6. 我的建議實作路線

如果你現在就要開始，我建議你先做一個最小練習專案：

題目

做一個「天氣查詢」或「測試 API」節點

為什麼這類題目適合： - REST API 直覺 - 欄位容易理解 - 容易看到輸入與輸出的關係

你第一版不必真的做商業服務，可以先做： - 一個 demo API - 一個自己熟悉的公開 API

7. 實作步驟

步驟 1. 建立新專案

npm create @n8n/node@latest n8n-nodes-my-first-tool -- --template declarative/custom

如果你想用互動式方式，也可以：

npm create @n8n/node@latest

然後在提示中選： - 名稱 - HTTP API - declarative/custom

步驟 2. 進入專案

cd n8n-nodes-my-first-tool

步驟 3. 看一下會出現哪些重點檔案

你不需要一開始把每個檔案都背下來，但至少要知道這幾類：

  • package.json
  • src/ 或 node 原始碼資料夾
  • credentials 檔
  • node 定義檔
  • README.md

如果是官方 scaffold，通常 package.json 會已經幫你放好基礎結構與 npm scripts。

步驟 4. 先 build 一次

npm run build

官方等價指令是：2

n8n-node build

先 build 的目的不是發佈，而是確認環境與依賴至少是通的。

步驟 5. lint 一次

npm run lint

官方等價指令是：2

n8n-node lint

如果要自動修一些小問題：

npm run lint:fix

步驟 6. 用 dev 跑起來

npm run dev

官方等價指令：2

n8n-node dev

這個指令會： - build 你的 node - 啟動本機 n8n - 把你的 node 載進去

然後你打開：

http://localhost:5678

就應該能在節點面板搜尋到你的 node。

8. 第一次看到自己的 node 時，先驗證什麼

你第一次跑成功，不要急著加很多功能。先驗證這四件事：

  1. 節點有出現在面板中
  2. 可以被拖進 workflow
  3. 參數欄位可以正常顯示
  4. execute 後不會立刻報結構錯誤

只要這四件成立，你就已經跨過最困難的第一步。

9. 你真正要改的是哪裡

第一次 scaffold 完後，最值得改的通常不是 build 設定，而是：

1. 節點名稱與描述

要讓使用者看得懂

2. credentials

先決定這個服務怎麼驗證

3. operations

先只做一兩個最有價值的操作

4. 欄位命名

盡量跟 API 語意對齊，但又不要讓使用者太難懂

初學者常見錯誤是： - 一開始就做太多 operation - 一開始就想把整個 API 全封完

這樣幾乎一定會讓專案失控。

10. 什麼時候用 Declarative，什麼時候用 Programmatic

先用 Declarative 的情況

  • 主要是 HTTP API
  • 欄位與操作結構規則明確
  • 想快速做出可維護版本

改用 Programmatic 的情況

  • API 不規則
  • 要做特殊資料轉換
  • 要有很多自訂執行邏輯
  • 一個 operation 牽涉多段流程

實務上很常見的路線是：

先做 declarative MVP，後面真的不夠再改成 programmatic。

11. 本機測試時最常見的錯

1. Node 版本不符

如果你的 Node.js 太舊，官方 scaffold 或 build 可能直接出問題。

2. 名稱格式不對

不是 n8n-nodes-... 或 @scope/n8n-nodes-...

3. 沒有用官方 scaffold

結果 package.json 缺 n8n metadata

4. 只 build 沒 dev

build 成功不代表已載入到 n8n

5. 想直接發佈，但本機都還沒跑通

這是最浪費時間的順序

12. 發佈前至少要知道的事

如果你只是自己本機用，暫時不用急著發佈。

但如果你要變成真正的 community node，至少要做到：

  1. package name 合規
  2. package.json 有 community node 需要的 metadata
  3. 有 README
  4. 可以 npm run lint
  5. 可以 npm run dev
  6. 發佈到 npm

官方提交文件也提到，若要送 verified，從 2026-05-01 起必須透過 GitHub Actions 加 provenance 發佈。3

13. 最小開發檢查表

在你說「我要開始做 node」之前，先確認：

環境

  • Node.js 版本符合要求
  • npm 可用
  • git 可用

專案

  • 名稱格式正確
  • 有用官方 n8n-node scaffold
  • 知道要選 declarative 還是 programmatic

本機驗證

  • npm run build 成功
  • npm run lint 成功
  • npm run dev 成功
  • 在 localhost:5678 看得到節點

14. 這章結束後你應該具備什麼能力

學完這章，你不一定已經做出一個很完整的 node，但你應該要能做到：

  • 知道官方推薦工具是什麼
  • 知道第一個專案怎麼 scaffold
  • 知道該選哪種模板
  • 知道怎麼本機測試
  • 知道之後若要發佈或送 verified，要補哪些東西

這樣你就不是停在「我聽過 community node」，而是真的進入「我可以開始做」。

與其他章節的關係

這章建議搭配：

如果你真的要自己做 node，最底層能力仍然是：

  • 看懂 API
  • 設計欄位
  • 想清楚使用者怎麼在 workflow 裡使用它

參考來源

  • n8n Docs: Using the n8n-node tool
  • n8n Docs: Set up your development environment
  • n8n Docs: Submit community nodes

  1. n8n Docs, Set up your development environment: https://docs.n8n.io/integrations/creating-nodes/build/node-development-environment/ ↩↩

  2. n8n Docs, Using the n8n-node tool: https://docs.n8n.io/integrations/creating-nodes/build/n8n-node/ ↩↩↩↩↩↩

  3. n8n Docs, Submit community nodes: https://docs.n8n.io/integrations/creating-nodes/deploy/submit-community-nodes/ ↩↩