Claude Code 安裝教學：在 VPS 或本機終端機直接用 Anthropic CLI 協助寫程式

很多人第一次碰 Claude Code，會直接找一篇很短的安裝文照著貼指令，結果遇到的第一個問題通常不是「裝不起來」，而是「裝完後到底該怎麼登入、怎麼讓它理解專案、什麼情況要改用原生安裝」。這篇就是要把這三件事一次講清楚，再帶你進入 CLAUDE.md 最佳實踐、hooks 自動化、MCP server 整合與多 agent 協作。

如果你是在台灣常見的開發情境，例如用 MacBook、本機 Linux、遠端 Ubuntu VPS，或是你想把 AI CLI 當成日常開發工具來用，這篇會比只貼一條安裝指令更有用。你不只知道怎麼裝，也會知道做完後要怎麼驗證，避免 CLI 看起來有裝好，實際一跑就卡權限、PATH 或登入流程。

這篇最值得你先記住的事

Claude Code 官方目前同時提供 npm install -g @anthropic-ai/claude-code 和原生安裝腳本，兩種都能用，但適合的情境不一樣。
第一次安裝先把 claude 跑起來完成登入，再用 claude doctor 檢查版本與安裝型態，會比只看 which claude 更準。
如果你要長期在同一個 repo 裡用 Claude Code，CLAUDE.md 幾乎是必備，不然每次都得重講專案規則。
Hooks 和 MCP server 是讓 Claude Code 從「聊天工具」變成「自動化開發助手」的關鍵功能。

哪些人會最需要這篇

想在本機或 VPS 直接用終端機叫 Claude 幫你看程式、改檔案、解釋錯誤的人
已經會用 Git 和 shell，但想把 AI agent 正式納進開發流程的人
想幫團隊整理 CLAUDE.md、降低每次開新 session 都要重講上下文成本的人
想用 hooks 和 MCP 把重複工作自動化的進階開發者

動手前先把這些條件看過

官方文件目前要求 Node.js 18+
你的機器要能正常對外連線，因為登入與模型請求都需要網路
如果你是在 headless VPS 上操作，要先想好要怎麼完成 OAuth 流程，或改用 API key / 雲端整合模式

詳細教學與操作步驟

Claude Code 是 Anthropic 官方推出的終端機 AI coding agent。依官方文件，目前最常見的安裝方式仍是 npm install -g @anthropic-ai/claude-code；如果你想嘗試新版原生安裝，也可以改用官方安裝腳本。兩種方式都能工作，但剛開始建議先選一種，裝完立刻驗證，不要混著裝。

先決定你要用哪一種安裝方式

如果你只是要先把 Claude Code 跑起來，官方最直觀的做法還是先用 npm 全域安裝：

npm install -g @anthropic-ai/claude-code

如果你想跟上官方正在推進的原生安裝流程，也可以使用原生安裝腳本。官方文件將它列為較新的安裝方式，適合想減少 npm 全域安裝摩擦的人：

curl -fsSL https://claude.ai/install.sh | bash

實務上，你不用一開始就糾結哪個「絕對比較新」。比較重要的是選一種裝完後立刻驗證，確保你的 shell、PATH 與登入流程都通。

步驟一：確認 Node.js 版本，再執行安裝

在安裝前先跑 node -v 看版本。若你還沒有 Node.js，可先看本站的 Node.js 與 NVM 教學。確認版本足夠後，再選擇 npm 或原生腳本其中一種安裝。

步驟二：第一次啟動，完成登入

安裝後，在你的專案資料夾內直接執行 claude。官方文件指出，第一次進互動模式時會引導你登入，常見方式包含 Anthropic Console OAuth，或使用 Claude App 帳號方案。

在終端機輸入 claude。
依畫面選擇登入方式。
若系統跳出瀏覽器授權流程，就照指示完成登入。
如果你在純文字 VPS 上操作，就手動把授權網址貼到本機瀏覽器處理。

如果你是企業環境，也可以依官方文件改走 Amazon Bedrock 或 Google Vertex AI 整合；但對大多數個人或中小團隊來說，先把標準登入流程跑通會比較實際。

步驟三：寫好你的 CLAUDE.md — 這是最重要的一步

Claude Code 裝好不代表它已經懂你的專案。要讓它少走冤枉路，最有效的做法就是在 repo 根目錄建立 CLAUDE.md，把長期穩定的規則寫進去。

Claude Code 會按照以下優先順序讀取指令檔：

全域層 ~/.claude/CLAUDE.md — 你個人的跨專案偏好（語言、commit 風格、常用工具）
專案層 {repo-root}/CLAUDE.md — 專案技術棧、建置指令、架構規範（會 commit 進 repo）
子目錄層 {repo-root}/src/CLAUDE.md — 某個子模組的特殊規則

CLAUDE.md 該寫什麼？一份好的範例結構

# CLAUDE.md

## Commands
npm run dev      # 開發伺服器
npm run build    # 建置
npm run lint     # ESLint 檢查
npm test         # 跑測試

## Architecture
- Next.js App Router，output: "export" 靜態匯出
- Tailwind CSS v4，主題在 globals.css
- 路徑 alias：@/* 對應專案根目錄

## Code Style
- 所有 UI 文案用繁體中文
- Commit message 格式：feat/fix/docs + 中文描述
- 用 import（ES modules），不用 require

## Common Pitfalls
- 靜態匯出不能用 getServerSideProps
- 動態路由必須有 generateStaticParams

CLAUDE.md 最佳實踐

寫具體指令，不要只寫概念。 「用 npm run build 驗證」比「記得建置」有效得多。
寫禁止事項。 Claude Code 會真的遵守「不要動 migrations/ 資料夾」這類規則。
寫常見錯誤。 像是「Tailwind v4 沒有 tailwind.config.js，主題定義在 globals.css」，能讓 Claude 避開很多繞路。
定期更新。 隨著專案演進，舊規則可能過時，記得清理。
分層管理。 全域偏好放 ~/.claude/CLAUDE.md，專案規則放 repo root，子模組規則放子目錄。

步驟四：設定 Hooks — 讓重複工作自動化

Hooks 是 Claude Code 的自動化機制，讓你在特定事件發生時自動執行腳本。這是從「手動確認每一步」進化到「信任但驗證」的關鍵功能。

Hooks 設定放在 .claude/settings.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hook": "npm run lint --silent"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hook": "npm run build --silent 2>&1 | tail -5"
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hook": "terminal-notifier -message \"$CLAUDE_NOTIFICATION\""
      }
    ]
  }
}

常見的 hooks 使用場景：

PreToolUse — 在 Claude 要改檔案前先跑 lint，確保不會破壞現有程式碼風格
PostToolUse — 改完檔案後自動跑 build，馬上知道有沒有壞掉
Notification — Claude 做完一個長任務後，用系統通知提醒你回來看
Stop — Claude 決定停下來時，自動執行最後的驗證腳本

步驟五：整合 MCP Server — 擴充 Claude 的能力

MCP（Model Context Protocol）讓 Claude Code 可以連接外部工具和資料來源。你可以把它想成「給 Claude 裝外掛」。

在 .claude/settings.json 中加入 MCP server 設定：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token"
      }
    }
  }
}

常見的 MCP server 用途：

filesystem — 讓 Claude 存取特定目錄（例如文件資料夾、設定檔目錄）
github — 讓 Claude 直接操作 GitHub issue、PR、搜尋 repo
postgres / sqlite — 讓 Claude 查詢資料庫 schema 或執行讀取查詢
puppeteer — 讓 Claude 控制瀏覽器做截圖、測試

設定好 MCP 後，Claude Code 會自動偵測可用工具，你不需要手動呼叫。

步驟六：多 Agent 協作 — 讓 Claude Code 和其他 AI 工具搭配

在實務開發中，不同 AI 工具各有強項。一個高效的做法是讓它們互相搭配：

工具	強項	適合的任務
Claude Code	深度理解程式碼上下文、大範圍重構	架構設計、複雜 debug、code review
Codex CLI	sandbox 執行、安全修改	自動修 bug、跑測試、批次修改
Gemini CLI	Google 搜尋整合、多模態	查文件、分析截圖、搜尋解法

在 CLAUDE.md 中可以記錄你的多 agent 策略：

## AI Tools
- Gemini CLI 可用來查最新文件或做第二意見
- Codex CLI 可用來做獨立的 sandbox 修復
- 複雜架構決策先用 Claude Code 分析

步驟七：實戰場景 — Claude Code 在日常開發中怎麼用

Debug 工作流

claude "這個 API route 回傳 500 錯誤，幫我看 error log 找出原因"

Claude 會讀取相關檔案、分析 stack trace、提出修復建議。搭配 hooks，修完後自動跑測試驗證。

Code Review 工作流

claude "review 目前 staged 的 changes，注意安全性和效能問題"

Claude 會用 git diff --staged 看變更，逐一檢查潛在問題，給出具體改善建議。

重構工作流

claude "把這個 utils.js 拆成獨立模組，保持所有 import 正確"

Claude 會分析依賴關係、建立新檔案、更新所有 import path，然後跑 build 確認沒有壞掉。

非互動模式 — 適合 CI/CD 或腳本

# 產生 commit message
claude -p "根據 git diff 產生一個 conventional commit message" --output-format text

# 分析 PR
claude -p "分析這個 PR 的變更，列出潛在風險" --output-format json

步驟八：做完後立刻驗證，不要只看有沒有安裝成功

先跑 claude doctor，確認版本與安裝型態。
再進專案資料夾執行 claude，實際問一個小問題，例如請它解釋目前專案架構。
確認它能正常讀 repo、沒有權限錯誤，也沒有反覆要求你重登。
測試 hooks 是否正常觸發（如果你有設定的話）。

常見問題

Q：認證時瀏覽器打不開怎麼辦？ 在 VPS 上這很常見。把終端機提供的網址複製到你的本機瀏覽器完成授權即可。

Q：為什麼我用 sudo npm install -g 之後反而更亂？ Anthropic 官方文件明確提醒不要用 sudo npm install -g。這很容易把全域權限和日後更新搞得很難處理。

Q：原生安裝跟 npm 安裝能不能混著用？ 技術上可能會留下舊別名、舊 symlink 或 PATH 混淆。比較穩的做法是一次只留一種，然後用 claude doctor 檢查當前狀態。

Q：CLAUDE.md 太長會不會影響效能？ Claude Code 對 CLAUDE.md 的處理很高效，一般專案的規則檔不太會造成問題。但建議保持精簡，只寫真正需要 Claude 知道的規則，不要把整份文件當 README 用。

Q：MCP server 連不上怎麼排查？ 先確認 MCP server 的 command 在你的 PATH 中可用，再檢查 .claude/settings.json 的 JSON 格式有沒有語法錯誤。你也可以單獨執行 MCP server 的指令來測試它是否能正常啟動。

Q：hooks 跑太慢怎麼辦？ hooks 會在每次工具呼叫前後執行，如果你的 lint 或 build 很慢，可以考慮只在特定 matcher 上觸發，或改用 --silent 減少輸出。

做完後怎麼確認自己真的有設對

在 repo 內執行一次 claude，確認不是只在空資料夾能跑
跑 claude doctor，確認版本、安裝方式與環境檢查沒有明顯異常
新增一份簡短的 CLAUDE.md，再請 Claude 解釋它讀到哪些規則，確認上下文真的有被吃進去
測試一次 hooks 觸發流程，例如故意讓 lint 失敗，看 hook 有沒有正確攔截
如果有設 MCP server，請 Claude 列出可用的工具，確認連線正常

這一題最常踩的坑

只看舊文章照做，結果把 sudo npm install -g 當成標準做法
已經有舊版 claude 路徑或 alias，導致你以為更新了，其實 shell 吃到的還是舊安裝
把工具裝好卻沒補 CLAUDE.md，之後每次開 session 都像重新認識一次專案
CLAUDE.md 寫太模糊（「注意程式碼品質」），Claude 無法執行具體動作
hooks 設定的 JSON 格式錯誤，導致 Claude Code 靜默忽略整個設定
MCP server 設定了但忘記給必要的環境變數（例如 GitHub token）

如果你要往下一步走

裝完 Claude Code 之後，下一個最值得補的通常不是更多花俏指令，而是把你的開發環境整理好。像是先把 Node.js 與 NVM 安裝教學補齊，再把 Git 與 SSH Key 設定做好，這樣 Claude 幫你改檔、看專案、跑指令時才不會每一步都卡在基礎環境。

如果你想同時使用多個 AI 工具，可以接著看 Codex CLI 安裝教學和 Gemini CLI 安裝教學，把多 agent 協作流程一起建起來。