Claude Code 安装教程（2026 最新）：Mac、Windows、Linux 三种装法与国内常见问题

下面按「先选装法 → 装 → 检查 → 解决报错 → 第一次使用」的顺序讲，所有命令都在 2026 年 10 月 15 日用最新的 Claude Code 2.1.300 实测过。

先看这张表：你该用哪种装法

三种方法装出来的是同一个程序，区别只在下载渠道和怎么更新。

Claude Code 是什么

Claude Code 是 Anthropic 官方出的 AI 编程助手。和网页版 Claude 聊天不同，它直接在你的电脑上干活：读整个项目的代码、改文件、运行命令、提交 Git，你用中文说需求，它自己规划步骤去完成。

它最常用的形式是终端版（本文讲的），另外也有 VS Code / JetBrains 插件、官方桌面应用和网页版。终端版功能最全，接入第三方 API 也以终端版为准。

安装前准备

• 系统：macOS 13 及以上；Windows 10 1809 及以上（或 Windows Server 2019 及以上）；Ubuntu 20.04+、Debian 10+、Alpine 3.19+。
• 硬件：4 GB 以上内存，x64 或 ARM64 处理器（Apple 芯片的 Mac 可以）。
• 不需要先装 Node.js：官方一键安装装的是独立程序，和 Node.js 无关。网上很多老教程第一步还是「先装 Node.js」，那是旧做法。只有选 npm 方法才需要 Node.js，而且要 22 或以上。
• 想清楚怎么付费：Claude Code 要调用模型才能干活。走官方需要 Claude Pro / Max / Team / Enterprise 订阅或 Claude Console 账号（免费版不行）；另一种是接兼容 Claude 接口的 API 服务，按用量付费，见下文「第一次使用」。

方法一：官方一键安装（推荐）

Mac / Linux / WSL，打开「终端」，粘贴运行：

curl -fsSL https://claude.ai/install.sh | bash

Windows，先看清你打开的是哪个窗口：提示符前面有 PS 的是 PowerShell，没有的是 CMD，两者命令不一样。

PowerShell：

irm https://claude.ai/install.ps1 | iex

CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

安装过程中没有进度条，下载完才会有输出，耐心等一会儿。我们在 Mac 上实测，下载加安装共 25 秒，最后输出：

✔ Claude Code successfully installed!

  Version: 2.1.300

  Location: ~/.local/bin/claude

这种装法会在后台自动更新，以后基本不用管。

方法二：Homebrew 或 WinGet

已经在用这两个软件包管理器的，可以直接：

# Mac
brew install --cask claude-code

# Windows
winget install Anthropic.ClaudeCode

要注意两点：

1. 不会自动更新，要自己定期运行 brew upgrade claude-code 或 winget upgrade Anthropic.ClaudeCode。
2. Homebrew 的 claude-code 跟的是「稳定版」，比最新版晚一周左右。我们查的时候最新版是 2.1.300，Homebrew 上是 2.1.287。想要最新版，装 claude-code@latest。

方法三：npm 安装（国内网络推荐）

如果你在国内连不上 claude.ai，官方一键安装脚本下载不下来，就用 npm，配合国内镜像下载飞快。

先确认装了 Node.js 22 或以上：

node -v

然后用国内镜像安装：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

实测 7 秒装完，版本和官方同步（同样是 2.1.300）：

added 2 packages in 7s

npm 版的更新命令是 npm install -g @anthropic-ai/claude-code@latest（国内同样可以加 --registry=https://registry.npmmirror.com）。别用 npm update -g，它可能不会升到最新版。

装完检查：两条命令

1. 看版本号。关掉终端、重新打开一个新窗口，运行：

claude --version

能看到类似 2.1.300 (Claude Code) 就说明装好了。

2. 体检。运行 claude doctor，它会检查安装方式、搜索功能、自动更新等，不会启动对话：

$ claude doctor
Claude Code doctor

Running: native (2.1.300)
Platform: darwin-arm64
Config install method: native
Search: OK (bundled)
…

有问题的话，结尾会列出 warning 和对应的修复方法（Fix: …），照着做就行。

国内装不上、报错怎么办

把报错原文和下面对一下：

1. 提示 command not found 或「不是内部或外部命令」

zsh: command not found: claude

这是最常见的问题：程序装好了，但安装目录不在 PATH 里，终端找不到它。官方一键安装时其实会提醒你：

⚠ Setup notes:
  ● Native installation exists but ~/.local/bin is not in your PATH.

Mac（默认终端 zsh）：

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

Linux（bash）：

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

Windows：把 %USERPROFILE%\.local\bin 加进「系统属性 → 环境变量 → Path」，然后重新打开终端窗口。

用 npm 装的，检查 npm config get prefix 显示的目录下的 bin（Windows 是这个目录本身）是否在 PATH 里。

2. 安装脚本报 syntax error near unexpected token '<'

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

意思是下载回来的不是安装脚本，而是一个网页，通常是网络拦截或代理返回了错误页。在国内网络下比较常见，最省事的办法是直接换方法三（npm 国内镜像）。

3. 提示 Failed to fetch version from downloads.claude.ai，或连接超时

安装程序连不上官方下载服务器。同样换 npm 国内镜像安装即可。如果你所在的网络本来就需要通过代理上网，可以先设置代理再装：

export HTTPS_PROXY=http://你的代理地址:端口
export HTTP_PROXY=http://你的代理地址:端口
curl -fsSL https://claude.ai/install.sh | bash

4. Windows 报 'irm' is not recognized 或 The token '&&' is not a valid statement separator

命令和窗口没对上：

• 'irm' is not recognized：你在 CMD 里运行了 PowerShell 的命令，换 CMD 那条。
• '&&' is not a valid statement separator：你在 PowerShell 里运行了 CMD 的命令，换 PowerShell 那条。

5. npm 装完运行报 claude native binary not installed

npm 版的程序本体是作为「可选依赖」下载的，如果被跳过就会出现这个错。检查安装命令里有没有 --omit=optional、--ignore-scripts，以及 .npmrc 里有没有 optional=false，去掉后重新安装：

npm install -g @anthropic-ai/claude-code@latest --registry=https://registry.npmmirror.com

6. npm 报权限错误（EACCES）

不要加 sudo。Claude Code 官方的建议是改用方法一（官方一键安装），它装在你自己的用户目录下，不涉及 npm 权限。

如果一键安装在你的网络下下载不了、只能用 npm，就按 npm 官方的办法，把 npm 的全局目录换到自己的用户目录下：

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

然后重新运行安装命令。更省事的办法是用 nvm 安装 Node.js，它装的 Node 本来就在你自己的目录下，不会有这个问题。

第一次使用

进入你的项目文件夹，启动 Claude Code：

cd 你的项目文件夹
claude

第一次启动会让你选界面主题，然后登录。你有两种选择：

方式一：用 Claude 官方账号登录

有 Claude Pro / Max / Team / Enterprise 订阅或 Claude Console 账号的，按提示在浏览器里登录即可，之后不用再登。

方式二：接兼容 Claude 接口的 API 服务

Claude Code 官方支持通过 ANTHROPIC_BASE_URL 把请求发到其他兼容 Claude 接口的服务（官方叫「网关」）。没有官方账号、或者想按用量付费的，可以用这种方式，不需要登录 Claude 账号。

以 api.foo 为例：

1. 登录 api.foo，进入 控制台 → API 密钥，点「创建 API 密钥」，复制以 sk- 开头的密钥。
2. 打开（没有就新建）Claude Code 的用户设置文件：Mac / Linux 是 ~/.claude/settings.json，Windows 是 C:\Users\你的用户名\.claude\settings.json。写入：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.foo",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

3. 保存后重新运行 claude。

几点说明：

• ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 的区别：前者把密钥放在 Authorization 请求头里，后者放在 X-Api-Key 里，api.foo 两种都认。推荐用 ANTHROPIC_AUTH_TOKEN：ANTHROPIC_API_KEY 会顶替你已登录的官方订阅，启动时还要确认一次。
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC：关掉自动更新、使用统计、错误上报这类非必要的网络请求。在连不上 Anthropic 服务器的网络里，能少很多无谓的连接尝试。关了自动更新后，记得偶尔手动更新（见下文）。
• 地址填 https://api.foo 就行，不用加 /v1。Claude Code 会自己拼路径。长时间任务可以换成直连线路 https://dc.api.foo，没有 100 秒超时限制。

模型名对不上、VS Code 插件还让登录、各种报错怎么处理，见 Claude Code 接中转站 / 第三方 API 配置教程。

上手：5 个最常用的操作

1. 先让它认识你的项目。在会话里输入：

/init

它会读一遍项目，生成一个 CLAUDE.md 文件，记下项目结构、怎么运行、代码规范。以后每次启动它都会先看这个文件，回答更准。

2. 直接用中文提需求。越具体越好：

登录页输错密码后页面一片空白，帮我找到原因并修好

比「修个 bug」好得多。复杂的需求可以分步骤列出来。

3. 看清楚再同意。Claude Code 要改文件或运行命令时会先问你。按 Shift+Tab 可以切换权限模式（每次都问 / 自动接受修改 / 先出计划再动手），新手建议保持每次都问。

4. 切换模型和查看用量。/model 换模型，/usage 看本次用了多少，/clear 清空当前对话重新开始。

5. 常用启动方式：

想在 VS Code 里用，在会话里输入 /ide 按提示连接编辑器即可。

更新与卸载

更新：

卸载：

# 官方一键安装（Mac / Linux）
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

# Homebrew
brew uninstall --cask claude-code

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

Windows（PowerShell）：

# 官方一键安装
Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

# WinGet
winget uninstall Anthropic.ClaudeCode

卸载程序不会删除你的设置和对话记录。想彻底清干净，再删掉 ~/.claude 文件夹和 ~/.claude.json 文件（删之前确认里面没有你要保留的东西）。

相关阅读

• API 中转站是什么？怎么选不踩坑