Claude Code 安装教程：Windows、macOS 和 Linux 从零开始

先讲结论：安装只有三步

装 Claude Code 不需要开发经验，实际就三步：

1. 跑一条官方安装命令
2. 用 claude --version 确认装上了
3. 进一个目录运行 claude，看到登录界面

这篇只负责把它装起来。登录方式和怎么接自己的 API，放在下一篇，两件事分开做不容易乱。

如果你还不确定为什么要装它，先看《为什么 Claude Code 能直接干活，而聊天工具只能给建议》。

安装前要准备什么

需要的东西不多：

• 一个终端。macOS 用「终端」或 iTerm，Windows 用 PowerShell 或 CMD，Linux 用你惯用的
• 一台 Windows、macOS、Linux，或者装了 WSL 的 Windows
• 能正常访问安装地址的网络

Windows 用户多一条建议：先装 Git for Windows。Claude Code 在原生 Windows 上需要它才能使用 Bash 工具，没装的话会退回用 PowerShell 当 shell。用 WSL 的不需要。

安装命令

官方推荐的是 Native Install，一条命令搞定，而且之后会在后台自动更新。

三个环境的命令不一样，别拿错。

macOS、Linux 和 WSL

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

Windows PowerShell

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

Windows CMD

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

怎么分清自己在 PowerShell 还是 CMD：看提示符。PowerShell 的提示符以 PS C:\ 开头，CMD 只有 C:\，没有前面的 PS。

这一步是 Windows 用户最常出错的地方，具体报错在后面的问题表里。

验证：先看版本号

安装完，先别急着做别的，跑一下：

claude --version

能打印出版本号，说明装成功了。

如果提示找不到命令，先关掉终端重新开一个再试——安装脚本会把程序目录写进 PATH，但已经开着的终端不会自动读到新的 PATH。

想看更详细的体检结果，跑：

claude doctor

它不会开始会话，只打印安装状态、配置文件有没有写错、以及最近一次更新的结果。后面排查问题时这条命令很有用。

首次启动

Claude Code 是在项目目录里用的，所以先建一个目录再启动：

mkdir claude-code-test
cd claude-code-test
claude

能看到首次登录或配置界面，就说明主体安装完成了。

这里会让你登录。多数入口需要 Claude 订阅或 Anthropic Console 账号。如果你的环境里已经设了 ANTHROPIC_API_KEY，它会跳过登录提示，转而让你确认是否使用这个 Key。

登录和 API 接入的完整说明放在下一篇，这一步先看到界面就算过。

安装方式怎么选

除了 Native Install，还有几种装法。建议先按主流程装，装不上再考虑备选。

几个需要知道的差别：

• Native Install 会在后台自动更新，装完基本不用管
• Homebrew：brew install --cask claude-code。有两个 cask，claude-code 走稳定通道，通常比最新版落后一周左右；claude-code@latest 跟最新版。Homebrew 装的不会自动更新，要自己跑 brew upgrade
• WinGet：winget install Anthropic.ClaudeCode。同样不会自动更新，要定期 winget upgrade Anthropic.ClaudeCode
• Debian、Fedora、RHEL、Alpine 可以用系统自带的 apt、dnf、apk 装，官方有签名仓库
• npm 单独讲，见下一节

如果没有特别理由，用 Native Install 就行，省掉后面手动升级这件事。

npm 装法：网络不通时的第一备选

Claude Code 也发布在 npm 上：

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

几个要点：

• 需要 Node.js 22 或更高。低版本会打印 EBADENGINE 警告但仍能装上，因为它装的是原生二进制，运行时并不用你的 Node
• 装完的和官方安装脚本装的是同一个二进制。npm 只是通过按平台区分的可选依赖把它拉下来，再链接到位
• 升级用 npm install -g @anthropic-ai/claude-code@latest。不要用 npm update -g，它会受初次安装时的版本范围限制，未必升到最新
• 不要用 sudo npm install -g，会带来权限和安全问题。遇到权限报错，改配置 npm 的全局目录

npm 这条路值得单独说，是因为它走的是 registry.npmjs.org，和官方安装脚本走的域名不同。直连官方安装地址不通的时候，npm 往往还能用，而且 npm 可以换成国内镜像源。

其他客户端怎么装

前面装的是终端 CLI。Claude Code 还有几个入口，用同一个引擎，配置也通用。

几个实际的选择建议：

• 完全没碰过终端的，直接用桌面 App。它自带 Claude Code，能可视化看改动前后的差异，也能同时开多个会话。需要付费订阅
• 平时就在 VS Code 里干活的，装扩展最顺手，能在编辑器里直接看 diff、用 @ 引用文件
• 网页版适合临时用一下，或者在没有本地环境的机器上跑长任务

同一套 CLAUDE.md、设置和 MCP 配置在各个入口通用，所以规则写一次就够，不用每个客户端配一遍。

但有一个例外要提前知道：**如果你要接自己的 API 地址，各入口的读取方式不一样。**终端读环境变量和 settings.json，VS Code 扩展要在它自己的设置里配，桌面 App 走另一套界面。下一篇有完整对照表。

网络不通时怎么办

这一节写给直连不畅的环境，包括中国大陆。

先分清两件事

装不上和用不了，是两个不同的问题，解决办法也不同。

**第一件是账号。**Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账号，免费的 Claude.ai 计划不包含 Claude Code。同时 Anthropic 有支持国家和地区名单，中国大陆不在名单内。这一层是账号资格问题，不是配个代理就能绕过去的。

**第二件才是网络。**如果账号本身没问题（比如你用的是境外主体的 Console 账号，或者公司走的是云厂商的模型服务），剩下的就是让机器能连上该连的地址。

如果第一件解决不了，往下看最后一小节的替代路径。

装的时候要连哪些地址

不同装法走的域名不一样，这决定了哪条路能通：

所以官方安装脚本下不动的时候，先试 npm——它走的是完全不同的域名，而且可以换镜像源。

跑起来之后要连哪些地址

装好只是第一步，运行时还要能连：

• api.anthropic.com：所有模型请求
• claude.ai 和 platform.claude.com：登录和令牌交换
• downloads.claude.ai：自动更新检查

如果你用的是第三方模型服务或自建网关，模型请求和认证会走你自己的地址，就不再依赖前两个。

配代理

Claude Code 支持标准的代理环境变量：

export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,127.0.0.1,.example.com"

Windows PowerShell：

$env:HTTPS_PROXY = "http://proxy.example.com:8080"

几个实际会踩到的点：

• 不支持 SOCKS 代理，只认 HTTP 和 HTTPS 代理
• 代理需要用户名密码的，写成 http://用户名:密码@proxy.example.com:8080
• shell 里 export 的变量只对当前终端有效。要让所有入口和后台任务都读到，写进 ~/.claude/settings.json 的 env 块更稳：

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:8080"
  }
}

• 代理地址写错时，Claude Code 启动就会报错并指出是哪个变量，不用猜
• 公司做了 TLS 拦截、报证书错误的，把根证书路径给它：export NODE_EXTRA_CA_CERTS=/path/to/ca.pem

配完想确认有没有生效，进会话跑 /status，看 Proxy 那一行；或者用 claude --debug 启动，日志在 ~/.claude/debug/ 下。

如果账号或直连这条路走不通

这里有一个很多人没意识到的点：Claude Code 是一个框架，模型是可以换的。

读文件、跑命令、写 Skill、接 MCP、按权限审批——这些能力都在框架层，不在模型层。把模型请求指到别的地址，这些照样能用。

所以除了 Anthropic 直连，还有几条路：

• 云厂商的托管服务：Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry
• 提供 Anthropic 兼容接口的模型服务：国内几家服务商已经适配了 Anthropic 的调用协议，可以直接用国内地址接进来
• 你自己或公司搭的 API 网关

三条路的配置方式是同一套：设 ANTHROPIC_BASE_URL 指向服务地址，再配上对应的凭据。走这条路时，模型请求和认证都发到你指定的地址，不再需要 claude.ai 登录，订阅额度也不参与，费用按 token 算在对应账号上。

需要如实说的是：换了模型，框架能力不变，但模型本身的表现会变。复杂的多步任务、长上下文的处理、工具调用的准确度，不同模型差别不小。建议先拿一个你熟悉的活试一遍，再决定用哪个。

配置和验证的完整步骤在下一篇。

常见问题

装完之后的检查表

• 安装命令跑完没有报错
• claude --version 能显示版本号
• claude 能启动
• 已经看到首次登录或配置界面

四条都过了，就可以进下一步。

下一步

装好之后有两条路（跑通之后就可以写第一个 Skill了）：

• 直接用订阅登录，最省事，适合先试用
• 接自己的 API 或网关，适合团队统一管账、控成本，或者你本来就有可用的 API

第二条路的坑集中在一个地方：只设 Base URL 不算切换，凭据必须一起设。下一篇专门讲这个。

参考资料

• Claude Code Overview
• Claude Code: Quickstart
• Claude Code: Advanced setup
• Claude Code: Troubleshoot installation