實作一個範例 Community Node 專案¶

這章不是只講理論，而是對照一個真的 scaffold 出來的範例專案，帶你看 community node 專案長什麼樣、怎麼 build、第一次會遇到哪些問題。

這章在看哪個專案¶

我已經在本機幫你建立一個官方 scaffold 出來的示範專案：

/Users/tungyu6/Documents/project/n8n-community-node-lab/n8n-nodes-demo-example

這個專案是用官方 n8n-node 工具建立的 programmatic/example 模板，不是我手工亂拼的假專案。

想一想¶

很多人學自創 node，會在腦中把它想成一個很抽象的「外掛」。但一旦你真的看到專案目錄，你就會發現它沒有那麼神祕。它其實就是一個 TypeScript 專案，只是多了一些 n8n 規則，例如 package.json 內要有 n8n metadata、節點檔案要放在對的位置、圖示與說明文件要跟著一起打包。當你看見這個結構，你就會比較知道「我要改哪裡」，而不是一直在想「我要怎麼開始」。

另一個很重要的觀念是：官方 scaffold 產出的專案，不代表一跑就完全綠燈。像這次範例專案雖然能成功 build，但 lint 還是因為預設 description 和 repository.url 沒改而報錯。這其實是好事，因為它在一開始就提醒你，community node 不是只要能執行就夠，還要把封裝品質、專案資訊、文件完整性一起做好。

1. 我幫你實際做了什麼¶

這個範例專案的建立方式是：

另外安裝 node@22
用 Node 22 執行官方 scaffold
建立 programmatic/example 專案骨架
補做依賴安裝
跑 build
修掉 scaffold 預設值造成的 lint 錯誤

這裡有一個實務重點：

你目前系統原本主要在用 Node 20 跑 n8n，但官方 n8n-node 工具鏈偏向 Node 22 開發環境。所以我沒有去破壞你現有的 Node 20，而是另外裝一份 node@22 供 node 開發使用。

2. 這個專案放在哪裡¶

專案路徑：

/Users/tungyu6/Documents/project/n8n-community-node-lab/n8n-nodes-demo-example

你之後如果想自己再做第二個，可以在同一層開新的專案，例如：

n8n-nodes-my-weather
n8n-nodes-my-clinic-api

3. 專案結構怎麼看¶

這份範例專案至少有這些重要檔案：

`package.json`¶

用途： - 專案基本資訊 - npm scripts - n8n metadata

`nodes/Example/Example.node.ts`¶

用途： - 節點真正的 TypeScript 邏輯

`nodes/Example/Example.node.json`¶

用途： - node 文件資源與分類資訊

`nodes/Example/example.svg`¶

用途： - node 圖示

`README.md`¶

用途： - 套件說明 - 安裝與使用說明

4. `package.json` 裡最值得先看哪裡¶

這個範例專案裡，最重要的幾塊是：

1. 套件名稱¶

"name": "n8n-nodes-demo-example"

2. keyword¶

"keywords": [
  "n8n-community-node-package"
]

3. scripts¶

"build": "n8n-node build",
"dev": "n8n-node dev",
"lint": "n8n-node lint"

4. n8n metadata¶

"n8n": {
  "n8nNodesApiVersion": 1,
  "strict": true,
  "credentials": [],
  "nodes": [
    "dist/nodes/Example/Example.node.js"
  ]
}

你可以把這段想成：「n8n 要去哪裡找我打包後的 node」。

5. 這個範例 node 本身在做什麼¶

Example.node.ts 是一個最小示範：

節點名稱叫 Example
有一個欄位 My String
執行時會把這個字串寫回每個 item 的 json.myString

也就是說，它不是一個真正對外 API 的 node，而是官方給你的最小 programmatic 範例。這很適合當第一個學習專案，因為你可以專心看：

node 描述怎麼寫
properties 怎麼定義
execute() 怎麼運作
錯誤怎麼處理

6. 實際執行結果¶

Build¶

這個範例專案已經成功 build。

使用指令：

cd /Users/tungyu6/Documents/project/n8n-community-node-lab/n8n-nodes-demo-example
PATH="/usr/local/opt/node@22/bin:$PATH" npm run build

結果： - n8n-node build 成功 - TypeScript build 成功 - static files 已複製

Lint¶

第一次 lint 失敗，但原因不是程式壞掉，而是官方 scaffold 留下的預設欄位沒有改：

description
repository.url

我已經先幫你把這兩個欄位改成 demo 值，讓這個範例更接近真專案。

7. 這個範例讓你學到什麼¶

最重要的不是這個 Example node 本身有多強，而是你現在已經有一份真的官方骨架，可以對照學：

node 專案不是只有一個 .ts 檔
package.json 的 n8n metadata 很重要
build 和 lint 是兩件不同的事
scaffold 完還是要補專案資訊
用 Node 22 跑 node 開發，比較貼近官方工具鏈

8. 你接下來最值得改哪裡¶

如果你要把這份 Example 專案往前推一步，我建議按這個順序改：

第一步¶

把 Example 改成你自己的服務名

例如： - Weather - ClinicApi - MyWebhookTool

第二步¶

把 My String 改成真實欄位

例如： - API Key - Record ID - Query

第三步¶

把 execute() 從單純寫回字串，改成： - 呼叫 API - 或整理輸入資料

第四步¶

補 credentials

現在這個範例是：

"credentials": []

之後你做真服務時，這裡通常不會是空的。

9. 你現在可以怎麼自己跑它¶

如果你要自己再重跑一次，建議用這組指令：

cd /Users/tungyu6/Documents/project/n8n-community-node-lab/n8n-nodes-demo-example
PATH="/usr/local/opt/node@22/bin:$PATH" npm run build
PATH="/usr/local/opt/node@22/bin:$PATH" npm run lint

如果你想嘗試 dev：

cd /Users/tungyu6/Documents/project/n8n-community-node-lab/n8n-nodes-demo-example
PATH="/usr/local/opt/node@22/bin:$PATH" npm run dev

但要記得，dev 階段常常比 build 更挑本機環境，所以第一步先求 build 穩定，是合理順序。

10. 這個範例目前的限制¶

這份專案是：

官方骨架
已成功 scaffold
已成功 build

但還不是一個正式可發佈的成熟 node，因為它還沒有：

真實 credentials 設計
真實 API operation
完整 README
真實 repository
發佈流程

換句話說，它現在是一份很好的學習樣本，不是一個成品。

11. 下一步最合理的練習¶

如果你要把這份範例繼續往前做，我建議下一題是：

題目 A. 改成一個 Echo Tool Node¶

輸入： - 一個字串

輸出： - 同字串 - 加上時間戳

目的： - 練 properties - 練 output 結構

題目 B. 改成一個 HTTP API Node¶

例如打： - jsonplaceholder - open-meteo

目的： - 練 API 呼叫 - 練欄位映射

題目 C. 補一組 credentials¶

目的： - 練 community node 真實封裝

對應章節¶

這一章的角色，就是把前一章的抽象知識，落到一個真的專案上。