Claude Code 由零安裝：Mac / Linux 30 分鐘起第一個 project

情境

你一個禮拜前發現 Claude Code，睇過 Anthropic blog post + 兩個開發者 Twitter thread。

你試 install：

1. Google「install claude code」→ 第 1 個結果係一個撞名嘅 npm package
2. 揾到 official docs → install 指令但你唔清楚應該喺邊個 directory 跑
3. 跑完，error message：「ANTHROPIC_API_KEY not set」
4. 揾到 API key 頁 → create key → 唔清楚喺邊度 set 環境變數
5. 設定完，試跑第一個指令 → 權限錯誤
6. 卡住 1 個鐘，放棄

呢個安裝死結：

• 文件假設咗開發者「基本認知」：環境變數、shell 設定、npm 權限等等
• Stack Overflow 答案過時（Claude Code 係新工具，仲喺更新）
• 頭一個鐘卡住 = 永遠放棄 —— 你唔會再試

呢篇就係防呢樣嘢：30 分鐘有系統裝好，覆蓋 Mac + Linux，每步解釋「點解」同「如果出錯」。完成後你跑到第一個 Claude Code session。

⚠️ Windows 用家：建議用 WSL（Windows Subsystem for Linux），跟住跟 Linux 教學。原生 Windows 雖然有但唔穩定。

跟住做

1. 事前準備（5 分鐘）

開 Terminal（Mac：iTerm 或 Terminal.app；Linux：你嘅預設 shell）：

# Check Node.js
node --version
# 需 v18.0.0+. 如果未裝或者太舊 → 用 nvm 裝:
# curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# nvm install 18

# Check npm
npm --version
# 通常跟 Node 一齊裝咗

# Check git
git --version
# 通常預設已經裝好。如果冇:
# Mac: xcode-select --install
# Linux: sudo apt install git

如果 3 個都冇問題 → 繼續。任何一個唔通過 → 先解決嗰個。

2. 安裝 Claude Code CLI（5 分鐘）

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

⚠️ -g 即全域安裝。部分系統需要管理員權限。

常見錯誤：

❌ EACCES: permission denied ✅ 解法：用 sudo，或者（較好）重新配置 npm prefix：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # 或 ~/.bashrc
source ~/.zshrc

然後再試 npm install -g @anthropic-ai/claude-code

❌ npm ERR! 404 Not Found ✅ 解法：確認 package 名正確 @anthropic-ai/claude-code（有 @anthropic-ai/ 前綴）

❌ 安裝成功但 claude 指令「not found」 ✅ 解法：PATH 未更新。重新載入你嘅 shell 設定：

source ~/.zshrc  # 或 .bashrc

然後打 claude --version

3. 設定 API key（5 分鐘）

去 console.anthropic.com：

1. 登入
2. Settings → API Keys
3. Create key → 改個 label「claude-code-local」
4. copy 咗個 key 即刻儲好（只係見到一次）

設環境變數：

# 編輯你 shell 設定檔 (Mac 預設 zsh):
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

# 確認:
echo $ANTHROPIC_API_KEY
# 應該出你 key

⚠️ 安全：永遠唔好將 API key commit 入 git。加落 .gitignore：

.env
.env.local

4. 跑第一個 Claude Code session（10 分鐘）

開一個測試 project folder：

mkdir ~/claude-test
cd ~/claude-test
git init  # optional but recommended

跑 Claude Code：

claude

第一次跑，Claude Code 會：

• 出歡迎訊息
• 同你確認工作 directory
• 顯示預設模式（interactive）
• 等你第一個 prompt

試第一個 prompt：

整個簡單 Python script print "Hello from Claude Code" 5 次

Claude：

• 出 script
• 問你權限「create file hello.py?」（Y/N）
• 你答 Y
• File 建立
• 顯示 file 內容 + path

ls 確認 file 確實存在：

ls
# hello.py

試跑：

python hello.py
# Hello from Claude Code
# Hello from Claude Code
# ...

🎉 你跑咗第一個 Claude Code session。

5. 理解權限模型（5 分鐘）

Claude Code 每次讀寫 / shell 指令都會先問權限：

• Allow once：今次 1 次 OK
• Allow always：呢類動作之後自動 allow
• Reject：拒絕，Claude 試另一個方法

新手建議：開頭全部手動批准，建立信心。1 個禮拜後你摸到規律，安全動作（讀檔案 / git status 等）用「Allow always」。

⚠️ 永遠唔好「Allow always」rm、git push --force、sudo、任何破壞性動作。

6. Exit + 返回

Ctrl+C 退出 session。

Folder 入面嘅狀態會保留（你建立嘅檔案仍然喺度）。下次 cd 入同一個 folder + claude 繼續。

Claude Code 對 1 個 folder 嘅對話歷史自動儲喺 .claude/ 子 folder（記得加入 gitignore，唔好入版本庫）。

變化

變化 1：將 Claude Code 連去你嘅編輯器

VS Code 接駁：

# 安裝 VS Code extension
code --install-extension anthropic.claude-code

開 VS Code，sidebar 會出現 Claude Code panel。可以：

• 揀起一段 code → 問 Claude
• 喺行內即時補全（類似 Copilot，但模型唔同）

JetBrains（IntelliJ / WebStorm 等）有類似插件。

變化 2：Project 專屬配置（CLAUDE.md）

每個 project 可以喺 root 放 CLAUDE.md，Claude 自動讀：

# Project Context

我哋係 Next.js 14 App Router project.

## 主要 conventions
- Server actions 喺 `actions.ts` files
- Tailwind for all styling
- TypeScript strict mode

## Critical files
- `app/layout.tsx` — global layout
- `lib/auth.ts` — auth utilities
- `prisma/schema.prisma` — database schema

呢個等於 project 專屬嘅 system prompt。Claude 每次 session 入呢個 folder 都會自動載入呢啲背景。

變化 3：明確揀模型

預設 Claude Code 用最新 Claude。部分情況你想明確指定：

# 用 specific model
claude --model claude-opus-4-7

# 或在 session 入面:
# /model claude-sonnet-4-6

取捨：

• Opus = 最強推理，較慢 + 貴
• Sonnet = 平衡，大部分任務預設
• Haiku = 快，細任務 / 大量平行

日常工作：接受預設。研究任務：明確用 Opus。

拆解：點解 work，同邊度會仆街

跟到上面就已經裝得好。下面呢段係畀**想由「裝到一次 hello world」做到「日日用都唔會無啦啦炒咗成個環境」**嘅人——初學者可以跳過，唔影響你跟住做。

裝開發工具最唔老實嘅地方係：今次喺你部機 work，唔代表下次開新 terminal、或者換咗部機都 work。安裝呢一步，實際會喺呢幾個位仆街，你要預咗：

1. 改錯 shell 設定檔，新 terminal 又打回原形 Mac 新版預設 zsh，但唔少舊教學叫你寫去 ~/.bashrc，或者你部機其實用緊 ~/.zprofile。寫錯檔，當前 terminal source 完好似 work，開過新 window 就乜都唔記得。

• 會出事：claude: command not found 或者 ANTHROPIC_API_KEY 變空，但你明明「啱啱先設定過」。
• 點救：打 echo $0 或者 echo $SHELL 確認自己用緊邊個 shell，先決定寫去邊個檔；改完一定要開一個全新 terminal window 再 claude --version 同 echo $ANTHROPIC_API_KEY 驗一次，唔好淨係信當前 session。

2. 用 sudo 裝 global package，留低權限地雷 撞到 EACCES 嗰陣，最快手就係 sudo npm install -g。一時 work，但之後啲檔案 owner 變咗 root，下次更新或者裝第二個 package 又再 permission denied，越補越亂。

• 會出事：之後每次 npm install -g 都要 sudo，甚至 npm cache 同 global folder 權限花到要成個重裝。
• 點救：唔好行 sudo 條路。跟返文中重設 npm prefix 去 ~/.npm-global 嗰個做法，等 global package 裝喺你自己 home 目錄，根本唔使 root。如果之前已經 sudo 裝爛咗，揾返被 root 佔咗嘅 folder 改返 owner，或者用 nvm 重裝一套乾淨 Node。

3. API key 表面入咗 git，背後已經外洩 文中提你加 .env 落 .gitignore，但 key 其實係寫咗喺 ~/.zshrc，唔係 .env；又或者你喺某個 script、某個 .env.example 度為咗方便貼咗真 key 落去。.gitignore 只擋未 track 嘅檔，擋唔到你已經 commit 咗、或者 paste 落聊天記錄、issue、screenshot 嘅 key。

• 會出事：key 一旦推上 public repo 或者貼出街，會被自動爬蟲幾分鐘內掃到，有機會被人盜用燒爆你 API 額度。
• 點救：key 只放環境變數，唔好硬寫入任何會入 repo 嘅檔；commit 前 git status 同 git diff 望真有冇 key。萬一漏咗出去，唔好淨係刪 commit——歷史仲喺度，要即刻去 console 撤銷舊 key、重新 create 一條。

4. 開頭就「Allow always」，之後一個唔覺意執行咗危險指令 為咗順手，新手好易見到 permission 提示就狂㩒「Allow always」。問題係呢個係粗略歸類，你一旦對「shell 指令」開咗永久放行，之後連 rm -rf、git push --force 都唔再問你。

• 會出事：Claude 自把自為改檔或者刪嘢，你連㩒 N 嘅機會都冇，事後先發現。
• 點救：跟返文中講嘅——開頭全部手動批准，只對明確安全嘅動作（讀檔、git status、ls）先用 always；破壞性指令永遠保持逐次確認。重要嘢入咗 git 之後再放手，炒咗都 git restore 救得返。

5. 唔睇住用量，月底先發現燒爆 budget Claude Code 比起 web 版，係一個 prompt 可以連環讀幾十個檔、改幾輪嘅 agent，token 用量遠多過你直覺。第一個禮拜你「摸索緊」，試錯特別多，成本好易畀你估嘅高。

• 會出事：自己以為冇用幾多，Anthropic console 月中先見到數字遠超預期。
• 點救：跟文中講嘅先劃個月度預算，頭一個禮拜每日去 console 望真實用量；勿一裝好就放隻大 model 通頂跑，日常接受預設、需要深度推理先明確用 Opus。

呢幾個位，就係「裝到一次 hello world」同「日日用都信得過、唔會無啦啦炒環境」之間嘅距離。

一個心態

Claude Code 安裝嘅隱藏啟示：CLI 工具都有學習曲線，但每日嘅回報會利疊利。

第 1 日安裝 + 設定：花你 1 個鐘。第 2 至 7 日：每日 30 分鐘「我仲摸索緊」嘅唔順。第 8 日之後：每日流程順暢。

第 30 日：你諗唔明點解之前用 web 版 Claude.ai 咁慢。

呢個心態嘅轉變：安裝嘅阻力唔係「Claude Code 嘅問題」—— 係解鎖一個新生產力層嘅必經代價。撐過 1 個禮拜，生產力嘅回報對比「喺 web UI 貼嘢做 prompt 工程」係倍數增長。

最後提醒：

• ✅ 第 1 個禮拜唔好放棄。安裝頭幾日唔熟手，第 8 日就流暢。
• ⚠️ 睇住 API 開支。Claude Code 用量可以喺 Anthropic console 追蹤。先劃個 $50 月度預算。1 個禮拜後你會摸清真實成本。
• 🎯 claude --help 係你最好嘅朋友。唔記得 syntax → 直接問。

下個鐘試裝好 + 跑第一個 hello world。1 個禮拜後變成你每日工作流程。