warren/momentry_core_0_1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e66b9501bd7583136ef01a1e2678f4792358c30b
momentry_core_0_1/docs/NODEJS.md
accusys e66b9501bd docs: Add version quick reference sections 
- Add version summary table to SERVICES.md
- Add version quick reference to PYTHON.md
- Add version quick reference to NODEJS.md
- Update related documents references
2026-03-16 15:43:41 +08:00

9.7 KiB
Raw Blame History

Node.js 開發指南

概述

本文檔說明 Momentry 專案中 Node.js 環境的配置、管理與監控。

當前狀態

項目 狀態
系統預設 Node.js v25.8.1
鎖定 Node.js (n8n) v22.22.1
n8n 版本 v2.3.5
npm 路徑 (預設) /opt/homebrew/bin/npm
node 路徑 (預設) /opt/homebrew/bin/node
node@22 路徑 /opt/homebrew/opt/node@22/bin/node

版本策略

為什麼需要版本鎖定？

n8n 要求 Node.js 版本為 22.x LTS。系統預設的 Node.js 25.x 會導致：

  • n8n 啟動警告
  • Task-runner 執行錯誤
  • 相容性問題

版本對照表

用途 Node.js 版本 路徑
系統預設 25.8.1 /opt/homebrew/bin/node
n8n 專用 22.22.1 /opt/homebrew/opt/node@22/bin/node
開發測試 22.x /opt/homebrew/opt/node@22/bin/node

安裝步驟

安裝特定版本 Node.js

# 安裝 Node.js 22.x (LTS)
brew install node@22

# 驗證安裝
/opt/homebrew/opt/node@22/bin/node --version
# v22.22.1

安裝全局工具

# 使用 node@22 安裝全局工具
/opt/homebrew/opt/node@22/bin/npm install -g <package-name>

# 例如安裝 n8n
/opt/homebrew/opt/node@22/bin/npm install -g n8n

使用方式

方式 1：直接使用完整路徑

# 使用 node@22
/opt/homebrew/opt/node@22/bin/node script.js

# 使用 npm@22
/opt/homebrew/opt/node@22/bin/npm install

方式 2：修改 PATH 環境變數

在 shell 配置檔案 (~/.zshrc) 中加入：

# 優先使用 node@22
export PATH="/opt/homebrew/opt/node@22/bin:$PATH"

# 重新載入
source ~/.zshrc

# 驗證
node --version
# v22.22.1

方式 3：使用 nvm (推薦)

# 安裝 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安裝 Node.js 22.x
nvm install 22
nvm use 22

# 設定預設版本
nvm alias default 22

n8n 配置

環境變數設定

在 plist 或啟動腳本中設定：

<key>ProgramArguments</key>
<array>
    <string>/opt/homebrew/opt/node@22/bin/node</string>
    <string>/opt/homebrew/lib/node_modules/n8n/bin/n8n</string>
    <string>start</string>
</array>

<key>EnvironmentVariables</key>
<dict>
    <key>PATH</key>
    <string>/opt/homebrew/opt/node@22/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>

Task Runner 配置

n8n Task Runner 用於執行 Code node 中的 JavaScript 代碼。

確保 PATH 中 node@22 在前面，這樣 task-runner 子進程會使用正確版本。

監控配置

健康檢查

monitor/service/health_check.sh 已包含 Node.js 版本檢查：

# 檢查 n8n 進程是否使用正確的 Node.js 版本
check_node() {
    local LOCKED_NODE_VERSION="22"
    # ...
}

執行監控

# 單獨檢查 Node.js
bash /Users/accusys/momentry_core_0.1/monitor/control/monitor_control.sh check node

# 檢查 Python
bash /Users/accusys/momentry_core_0.1/monitor/control/monitor_control.sh check python

查看版本狀態

# 查詢資料庫中的版本記錄
psql -U accusys -h localhost -d momentry -c "SELECT * FROM node_version_baseline;"

應用Registry

記錄系統中所有使用 Node.js 的應用程式。

應用 Node.js 版本 執行路徑 Port 狀態 說明
n8n 22.22.1 /opt/homebrew/opt/node@22/bin/node 5678/5690 ✅ 執行中 工作流自動化平台
- - - - - 新增應用請填入此表

新增 Node.js 應用決策

決策樹

新應用需要 Node.js?
    │
    ├─ 支援 Node.js 22.x ────→ 使用現有 node@22
    │                              (路徑: /opt/homebrew/opt/node@22/bin/node)
    │
    ├─ 需要特定版本 (如 18.x, 20.x) ────→ 安裝新版本 node@XX
    │                                          │
    │                                          ├─ 建立獨立目錄: /opt/homebrew/opt/node@XX/
    │                                          ├─ 更新本文檔 Registry
    │                                          └─ 建立獨立 plist 使用完整路徑
    │
    └─ 需要最新版本 ────→ 使用系統預設 node@25
                              (路徑: /opt/homebrew/bin/node)

步驟清單

  1. 確認版本需求

    # 查看應用支援的 Node.js 版本
# 通常在 package.json 或官方文件中說明

  2. 選擇現有版本或安裝新版本

    • 若支援 22.x → 使用 node@22
    • 若需要特定版本 → 使用完整路徑隔離

  3. 安裝新版本 (如需要)

    # 安裝特定版本
brew install node@20
# 或
brew install node@18

# 驗證安裝
/opt/homebrew/opt/node@20/bin/node --version

  4. 建立隔離的服務配置

    • 使用完整路徑，不要依賴 PATH
    • plist 中明确指定 node 路徑
    • 設定獨立的環境變數

  5. 更新文件

    • 更新本文檔 Registry 表格
    • 新增應用的安裝文檔
    • 更新監控配置

隔離原則

原則 說明
完整路徑 使用 /opt/homebrew/opt/node@XX/bin/node 而非 node
獨立 PATH plist 中設定隔離的 PATH 環境變數
獨立目錄 不同版本的 node 安裝在各自目錄
獨立全局套件 每個版本有自己的 node_modules

版本衝突處理

常見衝突場景

場景 原因 解決方案
n8n 顯示版本警告 使用 Node.js 25.x 啟動 確認 plist 使用 node@22 路徑
task-runner 執行錯誤 子進程繼承錯誤版本 在 plist 中設定正確的 PATH
全域套件找不到 跨版本安裝 使用正確版本的 npm
Port 被佔用 多個應用使用相同 Port 分配獨立 Port

診斷命令

# 1. 查看程序使用的 node 版本
ps aux | grep node

# 2. 查看程序 PID 使用的執行檔
lsof -p <PID> | grep bin/node

# 3. 確認路徑優先順序
echo $PATH

# 4. 查看 launchctl 服務的環境變數
sudo launchctl list | grep <service-name>

# 5. 檢查 Port 佔用
lsof -i :<port-number>

預防措施

  1. 每次新增服務都更新 Registry
  2. 使用完整路徑而非 PATH
  3. 建立服務時指定版本
  4. 定期檢查執行中的程序

故障排除

問題：n8n 顯示 Node.js 版本警告

原因：n8n 檢測到 Node.js 版本不是 22.x

解決方案：

  1. 確認 plist 中 ProgramArguments 使用正確路徑
  2. 確認 PATH 環境變數中 node@22 在前面
  3. 重載服務：
sudo launchctl unload /Library/LaunchDaemons/com.momentry.n8n.main.plist
sudo launchctl unload /Library/LaunchDaemons/com.momentry.n8n.worker.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.n8n.main.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.n8n.worker.plist

問題：Task Runner 使用錯誤版本

原因：PATH 環境變數設定不正確

診斷：

# 查看 task-runner 進程使用的 node
ps aux | grep "task-runner"
lsof -p <PID> | grep "txt" | grep node

解決方案： 更新 plist 中的 PATH，確保 /opt/homebrew/opt/node@22/bin 在最前面。

問題：npm 全域套件找不到

原因：使用錯誤的 node 版本安裝

解決方案：

# 確認使用的是哪個 node
which node
node --version

# 使用正確版本重新安裝
/opt/homebrew/opt/node@22/bin/npm install -g <package>

版本切換腳本

建立快速切換腳本 ~/bin/switch-node.sh：

#!/bin/bash

VERSION=$1

case $VERSION in
    22)
        export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
        echo "切換到 Node.js 22.x"
        ;;
    system|25)
        export PATH="/opt/homebrew/bin:$PATH"
        echo "切換到系統 Node.js 25.x"
        ;;
    *)
        echo "用法: $0 {22|system}"
        echo "  22    - Node.js 22.x (n8n)"
        echo "  system - Node.js 25.x (系統預設)"
        exit 1
        ;;
esac

node --version

賦予執行權限：

chmod +x ~/bin/switch-node.sh

使用方式：

~/bin/switch-node.sh 22      # 切換到 22.x
~/bin/switch-node.sh system  # 切換到系統預設

常用指令

# 查看 node 版本
node --version

# 查看 npm 版本
npm --version

# 查看 node 安裝位置
which node

# 查看 node@22 版本
/opt/homebrew/opt/node@22/bin/node --version

# 安裝全域套件 (使用 node@22)
/opt/homebrew/opt/node@22/bin/npm install -g n8n

# 檢查 n8n 進程
ps aux | grep n8n | grep -v grep

# 檢查 task-runner
ps aux | grep task-runner | grep -v grep

# 查看 task-runner 使用的 node 版本
lsof -p <PID> | grep "txt" | grep node

檔案位置

類型 路徑 說明
node (系統) /opt/homebrew/bin/node 預設 node
node@22 /opt/homebrew/opt/node@22/bin/node n8n 專用
npm (系統) /opt/homebrew/bin/npm 預設 npm
npm@22 /opt/homebrew/opt/node@22/bin/npm n8n 專用
n8n 安裝 /opt/homebrew/lib/node_modules/n8n/ n8n 目錄
n8n main plist /Library/LaunchDaemons/com.momentry.n8n.main.plist 開機啟動
n8n worker plist /Library/LaunchDaemons/com.momentry.n8n.worker.plist 開機啟動

版本速查

版本 用途 路徑
22.22.1 n8n 專用 /opt/homebrew/opt/node@22/bin/node
25.x 系統預設 /opt/homebrew/bin/node

相關文件

Reference in New Issue View Git Blame Copy Permalink