夕桜白雪

前置檢查#

先確認目前環境是否已經有 Node.js 與 npm：

1
node -v
2
npm -v

如果系統找不到指令，代表還沒有安裝 Node.js，或是 shell 尚未載入正確的環境變數。

安裝 nvm#

nvm 用來管理不同版本的 Node.js。安裝完成後，通常會把初始化片段加入 ~/.bashrc。

1
export NVM_DIR="$HOME/.nvm"
2
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
3
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

如果剛安裝完 nvm 但終端機還不能使用 nvm，可以重新開啟終端機，或手動載入：

1
\. "$HOME/.nvm/nvm.sh"

安裝 Node.js#

使用 nvm 安裝指定主版本：

1
nvm install 24

安裝完成後檢查版本：

1
node -v
2
npm -v

範例輸出：

1
v24.11.1
2
11.6.2

nvm 也會建立預設別名，之後開新終端機時會自動使用這個版本。

安裝 pnpm#

如果伺服器尚未安裝 pnpm，可以透過 npm 安裝：

1
npm install -g pnpm

確認 pnpm 是否可用：

1
pnpm -v

如果終端機顯示版本號，就可以進入專案安裝依賴。

安裝 Git#

Ubuntu / Debian 可以使用 apt：

1
apt update
2
apt install -y git

確認版本：

1
git --version

如果要讓伺服器可以拉取私有倉庫，還需要另外設定 SSH key 或 HTTPS token。

Mizuki 專案常用命令#

進入專案後先安裝依賴：

1
pnpm install

檢查內容、型別與基本建置條件：

1
pnpm check

產生靜態站：

1
pnpm build

本機或伺服器預覽：

1
pnpm preview

Windows 補充#

Windows 不一定要照 Linux 的 nvm 流程。可以使用 Node.js 官方安裝器、fnm、nvm-windows，或透過 winget / Scoop 安裝，再用同樣的方式檢查：

1
node -v
2
npm -v
3
pnpm -v

只要版本符合專案需求，後續 pnpm install、pnpm check、pnpm build 的流程就一樣。

排查筆記#

• nvm: command not found：重新開啟終端機，或手動載入 ~/.nvm/nvm.sh。
• pnpm: command not found：確認 npm install -g pnpm 是否成功，並重新開啟終端機。
• 建置失敗：先跑 pnpm check 看是編碼、型別、文章 Frontmatter，還是資產路徑問題。
• 伺服器和本機結果不同：優先比對 node -v、pnpm -v、環境變數與專案鎖定檔。