macOS Web 全栈开发环境安装文档

适用环境：

• macOS 26.4.1
• x86_64
• 默认 shell 为 zsh
• 目标环境为 Web 全栈常用完整版

目标：

• 安装并启用 Xcode Command Line Tools
• 安装 Homebrew
• 配置国内镜像
• 安装 Node.js LTS、pnpm、uv、独立 Python
• 安装 VS Code CLI、Docker Desktop
• 安装并启动 PostgreSQL、Redis

一键安装命令

把下面整段复制到终端执行：

set -e

# 1) 激活 Command Line Tools
sudo xcode-select --switch /Library/Developer/CommandLineTools
xcode-select -p

# 2) 安装 Homebrew（官方脚本，默认 /usr/local）
NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 3) 写入 shell 初始化
mkdir -p "$HOME/bin" "$HOME/.config/pip"
touch "$HOME/.zprofile" "$HOME/.zshrc"

grep -q 'brew shellenv' "$HOME/.zprofile" || cat >> "$HOME/.zprofile" <<'EOF'
export PATH="$HOME/bin:$PATH"
if [ -x /usr/local/bin/brew ]; then
  eval "$(/usr/local/bin/brew shellenv)"
fi
EOF

grep -q 'NPM_CONFIG_REGISTRY' "$HOME/.zshrc" || cat >> "$HOME/.zshrc" <<'EOF'
export PATH="$HOME/bin:$PATH"
export NPM_CONFIG_REGISTRY="https://registry.npmmirror.com"
export PIP_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"

if [ -x /usr/local/bin/brew ]; then
  eval "$(/usr/local/bin/brew shellenv)"
fi

if command -v fnm >/dev/null 2>&1; then
  eval "$(fnm env --use-on-cd)"
fi
EOF

cat > "$HOME/.npmrc" <<'EOF'
registry=https://registry.npmmirror.com
EOF

cat > "$HOME/.config/pip/pip.conf" <<'EOF'
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
EOF

source "$HOME/.zprofile"
source "$HOME/.zshrc"

# 4) 安装 CLI / 运行时 / 数据库
brew update
brew install git wget jq ripgrep fd tree fnm uv python postgresql redis

# 5) Node LTS + pnpm
eval "$(fnm env --use-on-cd)"
fnm install --lts
fnm default lts-latest
fnm use default
corepack enable
corepack prepare pnpm@latest --activate

# 6) 提供 python / pip 入口（避免依赖系统 Python）
ln -sf "$(brew --prefix)/bin/python3" "$HOME/bin/python"
ln -sf "$(brew --prefix)/bin/pip3" "$HOME/bin/pip"

# 7) VS Code CLI
if [ ! -d "/Applications/Visual Studio Code.app" ]; then
  brew install --cask visual-studio-code
fi
ln -sf "/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code" "$HOME/bin/code"

# 8) Docker Desktop
if [ ! -d "/Applications/Docker.app" ]; then
  brew install --cask docker
fi
open -a Docker

# 9) 启动本地数据库服务
brew services start postgresql
brew services start redis

# 10) 验收
brew doctor
git --version
fnm --version
node -v
pnpm -v
uv --version
python --version
pip --version
code --version
psql --version
redis-cli ping
brew services list

echo
echo "Docker Desktop 正在启动。等桌面端完全起来后，再手动跑这两条："
echo "docker version"
echo "docker compose version"

安装说明

• sudo xcode-select --switch ... 会要求输入 macOS 管理员密码，这是正常现象。
• open -a Docker 只负责打开 Docker Desktop，真正就绪通常还需要几十秒。
• 这份方案默认使用国内镜像：
  • npm/pnpm：https://registry.npmmirror.com
  • pip/uv：清华 PyPI 镜像

安装完成后建议复核

在 Docker Desktop 完全启动后，再运行：

docker version
docker compose version

如果要把结果发给我继续验收，优先提供下面几组输出：

brew doctor
node -v && pnpm -v
uv --version && python --version
docker version && docker compose version
brew services list
redis-cli ping