why01 API 文档

主题

macOS 安装 Node.js

Claude Code / Codex CLI / Gemini CLI 都依赖 Node.js 18+。已装过的跑 node -v 看版本，≥ v18 直接跳过本页。

方法一：官方安装包 ​

  1. 浏览器打开 https://nodejs.org/zh-cn/download
  2. 选 LTS，操作系统选 macOS
  3. 下载 node-vXX.X.X.pkg
  4. 双击 .pkg → 一路继续 → 输密码 → 装完

适合：第一次装 Node、不想折腾包管理器、不需要多版本切换。

方法二：Homebrew（推荐 Mac 老司机） ​

bash
# 装 LTS
brew install node@22

# 把 node@22 加到 PATH
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 或者直接装最新的（不锁版本）
brew install node

TIP

M 系列 Mac 的 Homebrew 路径是 /opt/homebrew/，Intel Mac 是 /usr/local/。brew --prefix 能查你机器实际路径。

方法三：nvm（多 Node 版本切换） ​

如果你同时维护老项目和新项目要切版本，装 nvm：

bash
# 1. 装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 2. 重开 terminal 或 source 配置
source ~/.zshrc        # 或 ~/.bashrc

# 3. 装 LTS
nvm install --lts
nvm use --lts
nvm alias default lts/*

验证安装 ​

新开一个 terminal 窗口：

bash
node -v
npm -v

期望输出：

v22.11.0
10.9.0

常见问题 ​

command not found: node ​

PATH 没生效。三种处理：

  1. 关 terminal 重开——老窗口的 PATH 是装之前的
  2. 手动 source ~/.zshrc
  3. 检查 PATH：echo $PATH 看有没有 node 所在目录

npm install 慢 ​

国内访问 npm 官方源慢。换淘宝镜像：

bash
npm config set registry https://registry.npmmirror.com

恢复官方：

bash
npm config set registry https://registry.npmjs.org

npm install -g 提示权限错误（EACCES） ​

Mac 系统目录的 npm 全局安装会撞权限。不要用 sudo npm install——会留下 root 权限文件污染。正确做法：

  • 方法 A（推荐）：用 nvm（方法三），nvm 装的 Node 全局包在用户目录，无权限问题
  • 方法 B：改 npm 全局目录到用户家目录：
    bash
    mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Apple Silicon (M1/M2/M3/M4) 兼容性 ​

Node.js v18+ 原生支持 ARM64，无需 Rosetta。如果你确认要装 x86 版本（罕见），用 Rosetta 启动 terminal 后再 brew install。

下一步 ​