Claude学院

Claude Code Mac 安装教程：从零配置到首次运行

在 macOS 上安装 Claude Code，核心就三步：先确保系统装有 Node.js 18 及以上版本，再用 npm install -g @anthropic-ai/claude-code 全局安装官方命令行工具，最后进入任意项目目录运行 claude 完成登录即可开始使用。下面按顺序拆解每一步，并给出命令、参数和常见报错的解决办法。

安装前的环境检查

Claude Code 是 Anthropic 官方的命令行编程工具，基于 Node.js 运行，因此安装前先确认本机环境。打开「终端」（Terminal）或 iTerm2，依次执行：

node -v
npm -v

要求 Node.js 版本不低于 18（推荐 20 LTS 或更高）。如果提示 command not found，说明还没装 Node。macOS 上推荐用 Homebrew 安装，避免直接用系统自带的旧版本：

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

# 安装 Node LTS
brew install node@20

如果你需要在多个 Node 版本间切换，更推荐用 nvm 管理：nvm install 20 && nvm use 20。Apple Silicon（M 系列芯片）和 Intel 芯片的 Mac 都原生支持，无需额外配置 Rosetta。

用 npm 全局安装 Claude Code

环境就绪后，执行官方安装命令：

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

这里的 -g 表示全局安装，安装完成后系统任意目录都能调用 claude 命令。安装结束后验证一下：

claude --version
claude doctor

claude doctor 会自检运行环境（Node 版本、安装路径、网络连通性等），是排查问题的第一步。安装过程不需要也不建议加 sudo——如果遇到权限报错（EACCES），通常是 npm 全局目录的归属问题，正确做法是把 npm 全局目录改到用户可写位置，而不是用 root 强行覆盖：

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

macOS Catalina 之后默认 Shell 是 zsh，配置文件为 ~/.zshrc；如果你仍在用 bash，把上面的文件名换成 ~/.bash_profile 即可。

登录与鉴权

首次运行 Claude Code 需要登录授权，有两种方式可选：

  • Claude 订阅账号登录：直接用 Claude Pro / Max 账号，运行 claude 后按提示在浏览器完成 OAuth 授权，无需单独配置 API Key，额度走订阅套餐。
  • API Key 登录：适合按用量计费或团队场景。在 Anthropic 控制台生成密钥后，写入环境变量：
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
# 写入 ~/.zshrc 可永久生效

两种方式的额度与计费规则不同，具体以 Anthropic 官网为准。如果你还没有密钥，可以参考 Claude API Key 怎么获取 这篇拿到密钥；登录环节卡住时，Claude Code 登录失败完整解决 里有针对性的排查步骤。Claude Code 默认调用的是 Messages API（POST /v1/messages，鉴权头为 x-api-key 加 anthropic-version），底层模型目前以 Claude Opus 4.8、Claude Sonnet 4.6、Claude Haiku 4.5 为主。

首次运行与基本用法

进入你的代码项目根目录，启动交互式会话：

cd ~/projects/my-app
claude

启动后会进入对话界面，你可以直接用自然语言下指令，例如「读一下 src 目录，告诉我项目结构」「帮我给 utils.ts 写单元测试」。Claude Code 会读取当前目录上下文、调用工具（Tool Use）查看和修改文件、运行命令，整个过程支持流式输出（SSE），响应是逐字返回的。

几个上手就常用的能力：

  1. 在项目根目录放一个 CLAUDE.md 文件，写明项目约定、技术栈、代码风格，Claude Code 会自动读取作为长期上下文。写法可参考 CLAUDE.md 配置文件完整模板。
  2. 会话内可用斜杠命令控制行为，常用的有 /clear（清空上下文）、/model（切换模型）、/login（重新登录）。更全的清单见 Claude Code 常用命令大全。
  3. 需要连接外部工具（数据库、GitHub、本地文件服务等）时，通过 MCP（模型上下文协议）扩展能力，配置流程见 Claude Code 配置 MCP 服务器完整步骤。

如果你用的是 Windows 系统，安装方式略有不同，可以看 Claude Code Windows 完整安装教程。

升级与卸载

Claude Code 更新较频繁，建议定期升级到最新版：

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

不再使用时卸载也很简单：

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

常见问题

安装后输入 claude 提示 command not found 怎么办？

说明 npm 全局 bin 目录不在 PATH 里。先用 npm config get prefix 查看全局安装路径，再确认它的 bin 子目录已加入 PATH。把对应的 export PATH=... 写进 ~/.zshrc 后执行 source ~/.zshrc，重开终端即可。用 nvm 的用户要注意，切换 Node 版本后全局包路径也会变，需要在新版本下重新安装。

安装时报 EACCES 权限错误怎么解决？

不要用 sudo npm install，那只会让问题更复杂。正确做法是把 npm 全局目录改到用户主目录下（参见上文「用 npm 全局安装」一节的 prefix 配置），让当前用户对安装目录有写权限，然后重新执行安装命令即可。

运行后报错或无法连接 Anthropic 服务怎么排查？

先跑 claude doctor 看自检结果，它会提示是 Node 版本、网络还是鉴权问题。若是认证相关报错（如 401），检查 API Key 是否正确、是否过期；网络层面注意国内访问可能需要稳定的代理环境。更系统的排查清单见 Claude Code 报错不工作排查清单。

← Claude Code