LeeScot's Web
開發環境macOS新手

為什麼你的 Mac 跑 Python 會爆掉？新手最該學的不是語法，是環境管理

|
- 次瀏覽

先講結論：你的 Mac 沒有你想的那麼堅強

剛拿到 Mac，裝了 VS Code，Google 搜了一下「Python 教學」，照著打了 pip install pandas。

然後事情開始不對勁。

終端機跳出一堆紅字，什麼 permission denied、什麼 externally-managed-environment。你心想：「我不是才剛開始嗎，怎麼就壞了？」

別慌，你沒有搞壞電腦。但你踩到了一個幾乎所有新手都會踩的坑：沒有先建立獨立的 Python 環境。

macOS 本身其實沒有預裝完整的 Python。當你在終端機輸入 python3，系統會提示你安裝 Xcode Command Line Tools，裝完後才會多一個 Python 3.9.x。但這個版本是綁定系統工具用的，直接拿來 pip install 裝套件，就會觸發 externally-managed-environment 錯誤。這是 Python 社群刻意設下的保護機制（PEP 668），目的是防止你把系統搞亂。

所以不管你是要學 Python、JavaScript、還是讓 AI 幫你寫 code，第一件該做的事不是學語法。

是「把環境管好」。

這篇文章會帶你從零開始，在 macOS 上建立一個乾淨的開發環境。所有步驟都是「打開終端機，複製貼上」就能完成，不需要任何程式基礎。

第一步：裝地基 — Xcode CLI + Homebrew

Xcode Command Line Tools

這東西不是 Xcode 那個肥大的 App，它是一包輕量的編譯工具。你之後裝的所有東西，底層幾乎都需要它。

打開終端機（Terminal），貼上這行：

xcode-select --install

跳出視窗後點「安裝」，等它跑完就好。

Homebrew：macOS 的套件總管

Linux 有 apt，macOS 有 Homebrew。它讓你用一行指令就能裝好各種開發工具。

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

裝完之後，畫面下方會出現「Next steps」，裡面有兩行指令。這兩行一定要複製並執行，不然 brew 指令不會生效。通常長這樣（請以你螢幕顯示的為準）：

(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> /Users/你的使用者名稱/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

很多新手卡在這裡，裝完 Homebrew 卻用不了，十之八九就是漏了這步。

Git + GitHub CLI

開發離不開 Git。一起裝好 GitHub 的命令列工具，以後 push code 不用再到網頁上操作。

brew install git gh

登入 GitHub：

gh auth login

選 GitHub.com → HTTPS → Yes → Login with a web browser，照著畫面走就好。

第二步：Docker 不是只有 Docker Desktop

如果你之後會碰到資料庫、後端服務、或是任何需要跑 container 的東西，你會需要 Docker。

但請不要裝 Docker Desktop。

Docker Desktop 在 Mac 上很肥、很慢、很吃記憶體。它背後跑的是一個完整的 Linux 虛擬機，光是開著什麼都不做，RAM 就先被吃掉好幾 GB。

替代方案是 OrbStack。它是專門為 Apple Silicon 設計的 Docker 替代品，啟動大概 2 秒，記憶體佔用比 Docker Desktop 低約 60%，而且所有 docker 指令都完全相容。個人非商業用途免費，在 Mac 開發圈的討論度很高。

brew install --cask orbstack

裝好後到「應用程式」打開 OrbStack，點幾下完成初始化。它會自動幫你把 docker 指令設定好，之後用起來跟 Docker Desktop 沒有差別（除了快很多）。

補充：Apple 在 WWDC 2025 也發表了原生的 container 工具，用 Swift 寫的，但目前還在非常早期的階段（v0.1.0），缺少 docker-compose 等功能。如果你想要一個現在就能用的方案，OrbStack 是比較成熟的選擇。

第三步：Python 環境的正確打開方式 — uv

回到那個問題：為什麼你的 Mac 跑 Python 會爆掉？

因為你直接用了系統的 Python，而且用 pip 把套件裝到了系統層級。這就像是把你的私人物品全部堆在公共走廊，遲早會出事。

正確做法是用版本管理工具，幫你在系統之外建立一個獨立、乾淨的 Python 環境。

目前社群推薦的工具是 uv。

uv 是 Astral 公司用 Rust 寫的 Python 套件管理工具，根據官方 benchmark，安裝速度是 pip 的 10 到 100 倍（例如安裝 JupyterLab，uv 只要 2.6 秒，pip 需要 21 秒）。它能同時管理 Python 版本和虛擬環境，一套搞定，不用再搞什麼 pyenv + virtualenv + pip 的三件套。

安裝 uv（用官方腳本，不要用 brew 裝）：

curl -LsSf https://astral.sh/uv/install.sh | sh

設定環境變數，讓終端機找得到它：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

下載一個乾淨的 Python（不會動到系統的）：

uv python install 3.12

以後要開新專案，流程是這樣：

mkdir my-project && cd my-project
uv init          # 初始化專案
uv add pandas    # 裝套件（取代 pip install）
uv run main.py   # 跑程式

從現在開始，你的腦內要建立一個自動轉換機制：

看到 pip install X → 自動翻譯成 uv add X。

這就是保持系統乾淨的秘訣。

第四步：Node.js 也不能直接裝 — nvm

如果你之後會碰前端、或是用任何 JavaScript/TypeScript 的工具（例如 Astro、Next.js），你會需要 Node.js。

Node.js 的版本更新非常快，而且不同專案可能需要不同版本。直接裝在系統上，之後版本一衝突，又是一場災難。

解法是 nvm（Node Version Manager），讓你用指令切換 Node 版本。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

版本號可能會更新，最新版本請查閱 nvm GitHub。

裝完後，把設定寫進 shell config：

echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

安裝目前的 LTS（Long Term Support，長期支援版）：

nvm install --lts
nvm use --lts

裝完輸入 node -v，有看到版本號就對了。

進階選項：如果你在意終端機啟動速度，可以考慮 fnm（Fast Node Manager）。它用 Rust 寫的，啟動速度比 nvm 快很多，指令也很類似。不過 nvm 的生態系比較成熟，新手用 nvm 完全沒問題。

第五步：給 AI CLI 工具立規矩

這一步是整篇文章最容易被忽略，但可能是最重要的。

現在的開發流程，很多時候是你下指令，AI Agent 幫你寫 code、跑指令、甚至幫你建專案。不管你用的是 Claude Code、Codex CLI、還是 Cursor，這些工具本質上都是「一個會打終端機指令的 AI」。

問題來了：如果你沒告訴它你的環境長什麼樣，它就會用它「以為」的方式來操作。

比如它可能會跑 pip install（錯），可能會試圖修改 /usr/bin（更錯），可能會用 apt-get（你又不是 Linux）。

所以你需要一份「家規」，在 AI 開始工作之前先讓它讀過。

如果你用 Claude Code，把以下內容放在專案根目錄的 CLAUDE.md：

# Development Environment

## Package Management
- Python: Use `uv` for everything.
  - Create project: `uv init`
  - Install packages: `uv add <package>` (NEVER use pip)
  - Run scripts: `uv run script.py`
- Node.js: Managed via `nvm`. Use `npm` for packages.
  - Do not use `sudo npm`.
  - Check `.nvmrc` before running commands.
- System tools: Use `brew` only when explicitly asked.
  - DO NOT use `apt-get`, `yum`, or `choco`.

## Containerization
- Using OrbStack (Docker compatible).
- Use standard `docker` and `docker compose` commands.

## File System
- macOS root is read-only. Do not modify `/usr/bin` or system paths.
- Projects are in `~/Projects/`.

## Git
- Use `gh` CLI for GitHub operations.

如果你用 Cursor，同樣的內容放在 .cursorrules 檔案裡。

如果你用 Codex CLI 或其他工具，找到它的 system prompt 或 instructions 設定，把上面那段貼進去。

格式不重要，重點是讓 AI 在動手之前知道三件事：

  1. Python 用 uv，不是 pip
  2. 不要碰系統目錄
  3. Docker 用 OrbStack，不用特別設定 VM

這份家規能幫你省下大量的 debug 時間。

最後：驗證一切是否就緒

打開終端機，跑這三行：

uv --version
nvm --version
docker --version

三個都有跑出版本號，就代表你的環境搞定了。

整理一下你現在裝了什麼：

工具用途安裝方式
Xcode CLI編譯工具基礎xcode-select --install
HomebrewmacOS 套件管理官方腳本
Git + gh版本控制 + GitHubbrew install
OrbStackDocker 替代品brew install --cask
uvPython 版本 + 套件管理官方腳本
nvmNode.js 版本管理官方腳本

沒有多餘的東西，每個工具都有明確的職責，彼此不打架。

這套設定不花俏，但它能讓你的 Mac 在跑了一整年的專案之後，依然保持乾淨。

開始寫 code 吧。

返回文章列表