安装前先确认三件事
Claude Code 是 Anthropic 官方的编程 Agent，主要在终端里使用。动手之前先核对官方 安装文档 列出的要求：
| 项目 | 要求 |
|---|---|
| 操作系统 | macOS 13+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+、Alpine 3.19+ |
| 硬件 | 4 GB 以上内存，x64 或 ARM64 处理器 |
| 账号 | Pro、Max、Team、Enterprise 或 Console（API）账号；免费版不行 |
| 网络 | 需要联网 |
| 所在地 | 需在 Anthropic 支持的国家和地区 之内 |
最后一条要说实话：中国大陆目前不在官方支持地区列表中。 这意味着官方不保证在大陆的可用性，安装脚本和登录都可能直接返回地区不可用的提示。本文只讲官方流程和报错含义，不提供规避地区限制的办法。
账号方面，如果你还没有付费订阅，先看本文后面”需要哪个订阅档位”一节。
安装方式：四选一
官方目前推荐原生安装脚本，不依赖 Node.js，并且会在后台自动更新。
| 方式 | 命令 | 自动更新 | 备注 |
|---|---|---|---|
| 原生安装（推荐） | 见下方 | 是 | macOS / Linux / WSL / Windows 通用 |
| Homebrew | brew install --cask claude-code | 默认否 | 用 brew upgrade claude-code 手动升级 |
| WinGet | winget install Anthropic.ClaudeCode | 默认否 | 用 winget upgrade Anthropic.ClaudeCode 升级 |
| npm | npm install -g @anthropic-ai/claude-code | 视权限而定 | 需要 Node.js 22+；不要加 sudo |
原生安装命令按系统区分：
# 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.cmdDebian、Fedora、Alpine 等发行版还可以用 apt、dnf、apk 仓库安装，命令见官方文档。不想碰终端的话，官方也提供桌面应用。
安装完成后：
- 新开一个终端窗口（旧窗口的 PATH 还没更新）；
- 运行
claude --version，能看到版本号即安装成功； - 进入你的项目目录，运行
claude启动。
Windows 用户补充两点：不需要管理员权限；PowerShell 的提示符以 PS C:\ 开头，CMD 没有 PS，两者的安装命令不能混用。Git for Windows 是可选项，装了之后 Claude Code 可以使用 Bash 工具，不装则用 PowerShell 执行命令。
登录：订阅账号还是 API Key
第一次运行 claude 会自动打开浏览器让你登录。登录方式有两种，计费完全不同：
| 订阅账号登录 | API Key / Console | |
|---|---|---|
| 用什么登录 | claude.ai 账号（Pro / Max） | Console 账号或 ANTHROPIC_API_KEY |
| 怎么计费 | 包含在订阅里，受 5 小时窗口和周限额约束 | 按 token 扣预充值余额 |
| 和网页版的关系 | 共用同一份额度 | 无关 |
| 适合 | 每天都用、用量稳定 | 偶尔用、接进 CI 或脚本、需要独立核算 |
订阅登录的步骤：
- 终端运行
claude，浏览器自动打开登录页； - 用你的 claude.ai 账号登录并授权；
- 终端显示
Login successful，按回车继续。
几种特殊情况，官方 登录文档 给了对应做法：
- 浏览器没有自动打开：在终端按
c复制登录链接，粘贴到浏览器里打开。 - 浏览器登录后显示一串代码而不是跳回终端：把代码粘贴到终端的
Paste code here if prompted提示处。WSL2、SSH、容器里常见。 - 想换账号：运行
/logout后重新登录，或直接/login。
最常见的坑：环境变量里的 API Key
如果系统里设置了 ANTHROPIC_API_KEY，Claude Code 会询问是否使用这把 Key；一旦同意，之后的请求都走 API 计费，而不是你的订阅。按官方的凭证优先级，环境变量里的 Key 排在订阅登录之前。
想用订阅额度，就取消这个变量：
unset ANTHROPIC_API_KEY
claude再到 ~/.zshrc、~/.bashrc 等配置文件里删掉对应的 export 行，然后在 Claude Code 里运行 /status，确认当前生效的是哪种登录方式。
安装报错对照表
下面的报错原文和处理办法来自官方 安装与登录排错文档：
| 你看到的 | 原因 | 怎么办 |
|---|---|---|
command not found: claude 或 'claude' is not recognized | 安装目录不在 PATH 里 | 先新开终端重试；仍不行按官方文档把安装目录加入 PATH |
syntax error near unexpected token '<' | 安装地址返回的是网页而不是脚本 | 若网页内容是 App unavailable in region，说明所在地区不受支持；否则多为临时网络问题，稍后重试或改用 Homebrew / WinGet |
curl: (22) The requested URL returned error: 403 | 同上，或被公司代理、防火墙拦截 | 同上；在公司网络下联系网络管理员 |
curl: (56) Failure writing output to destination | 下载中断 | 检查能否访问 downloads.claude.ai，重试 |
Failed to fetch version | 连不上下载服务器 | 检查网络和代理设置 |
TLS connect error、unable to get local issuer certificate | TLS 握手失败，常见于公司网络的证书 | 更新系统 CA 证书，或配置公司 CA |
EACCES: permission denied | 安装目录没有写权限 | 修正目录权限；npm 安装遇到的话改用原生安装，不要用 sudo |
irm is not recognized / '&&' is not a valid statement separator | PowerShell 和 CMD 的命令用反了 | 换成当前终端对应的那条命令 |
Error: claude native binary not installed | npm 安装时跳过了可选依赖或安装后脚本 | 重新安装，不要加 --omit=optional 或 --ignore-scripts |
Linux 上安装时出现 Killed | 内存不足 | 释放内存或增加 swap |
拿不准是哪里的问题时，运行 claude doctor。它只做只读检查，会列出安装状态、配置文件错误和建议的修复办法。
登录失败怎么排查
| 你看到的 | 原因 | 怎么办 |
|---|---|---|
OAuth error: Invalid code | 登录代码过期或复制不完整 | 回车重试，浏览器打开后尽快完成；用 c 复制完整链接 |
API Error: 403 Request not allowed | 订阅未生效，或 Console 账号没有对应角色 | 到 claude.ai 设置页确认订阅有效；Console 用户确认有 Claude Code 或 Developer 角色 |
This organization has been disabled，但订阅正常 | 环境变量里有一把旧的、已失效的 API Key | 按上一节取消 ANTHROPIC_API_KEY |
Unable to connect to Anthropic services | 首次启动的连通性检查失败 | 检查网络和代理配置 |
Login expired · Please run /login | 登录凭证过期 | 运行 /login 重新登录；频繁出现时检查系统时间是否准确 |
App unavailable in region | 所在地区不在支持范围 | 见官方支持地区列表 |
Credit balance is too low | 走了 API 计费且余额不足 | /status 确认凭证，切回订阅登录或给 Console 充值 |
原因不明时，官方建议先做一次干净的重新登录：/logout → 关闭 Claude Code → 重新运行 claude 登录。
还有一种情况容易混淆：网页版本身就提示账号被停用。那不是安装或登录的问题，见 Claude 账号被封怎么办。
需要哪个订阅档位
Claude Code 不单独收费，跟着订阅或 API 走：
- 免费版：不包含 Claude Code；
- Pro（$20/月）：包含，适合修 bug、写小功能、偶尔使用；
- Max 5x / 20x（$100 / $200/月）：每个会话的用量是 Pro 的 5 倍或 20 倍，适合每天写代码。本站的 Max 代充已停售，需海外卡在官网订阅；
- API：按量计费，和订阅无关。
第一次用建议从 Pro 开始，观察一两周自己撞上限的频率再决定是否升档。额度怎么算、撞上限怎么办，见 Claude Code 额度与限流；三种付费方式的成本对比见 Claude Code 充值。
订阅本身卡在付款上的话：官方只接受海外发行的卡，国内可以用人民币代付开到你自己的账号上，通常 1 分钟左右到账，不需要提供长期密码，步骤见 国内开通 Claude Pro 教程。
更新和卸载
Claude Code 更新很频繁，新模型上线时往往需要较新的版本才能使用，所以值得弄清楚自己的安装方式怎么升级：
| 安装方式 | 升级 | 卸载 |
|---|---|---|
| 原生安装 | 后台自动更新；也可以手动运行 claude update | 删除 ~/.local/bin/claude 和 ~/.local/share/claude |
| Homebrew | brew upgrade claude-code | brew uninstall --cask claude-code |
| WinGet | winget upgrade Anthropic.ClaudeCode | winget uninstall Anthropic.ClaudeCode |
| npm | npm install -g @anthropic-ai/claude-code@latest | npm uninstall -g @anthropic-ai/claude-code |
两个细节：npm 方式升级时不要用 npm update -g，它可能停在旧版本上；卸载后如果 claude 命令还能运行，说明机器上有第二份安装，常见于先用 npm 装过、后来又用原生脚本装了一次。运行 claude doctor 可以看到当前生效的是哪一份。
设置、会话记录和登录信息保存在用户目录下的 .claude 文件夹里。只是重装的话不用动它；想彻底清理再删除，删除后设置和历史会话都会丢失。
装好之后怎么用
进入项目目录运行 claude，直接用自然语言说需求即可。几条上手建议：
- 先让它读项目。 运行
/init生成 CLAUDE.md，把项目结构、常用命令、编码约定写进去，之后每次会话都会自动加载。 - 需求说具体。 “给 auth.ts 的登录函数加输入校验”比”优化一下代码”省额度也更准。
- 复杂任务先出计划。 按 Shift+Tab 切到计划模式，确认方案再让它动手。
- 换任务就
/clear。 旧上下文会持续消耗额度。 - 跑偏了立刻按 Esc。 可以随时打断并纠正方向。
- 常用命令：
/model换模型，/usage看额度，/status看登录状态，/doctor做体检。
Claude Code 和其他编程工具怎么搭配，见 开发者选购指南。