Claude Code 是 Anthropic 出品的终端 AI 编程助手(agent 形态,能读文件、改代码、跑测试、执行 Git 操作)。安装本身只有一行命令,真正会卡住人的是三件事:官方推荐的安装方式已经换过(不再是 npm)、它没有免费档、以及装完之后常见的十几个报错。2026 年 9 月的最优路径是官方原生安装脚本——自带运行时、不需要 Node.js、后台自动更新。本文给出 5 种安装方式的可复制命令、装完后必须做的三步验证、12 个报错的逐一解法,以及付费与地区可用性这两件装之前就该知道的事。 安装Claude Code先确认3个前置条件
Claude Code 的安装脚本会自己处理依赖,所以"前置条件"比多数教程写的要少。真正必须满足的只有三条:
| | |
|---|
| macOS 13.0+;Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+;Windows 10 1809+ 或 Windows Server 2019+(原生或 WSL 2)。内存 4GB 以上,磁盘留 500MB,x64 或 ARM64 处理器 | uname -a(macOS/Linux)或 winver(Windows) |
| Claude 付费订阅(Pro / Max / Team / Enterprise)、Claude Console 的 API 额度,或受支持的云厂商(Amazon Bedrock、Google Vertex AI、Microsoft Foundry)。免费计划不含 Claude Code | |
| 安装脚本要从官方下载地址取二进制,运行时要连 Anthropic API | |
常被误写成"必需"的两项其实都不是:Node.js 只在选择 npm 安装路线时才需要(要求 18+),走原生安装脚本完全不需要;Git 也不是硬性前置,但官方建议在 Windows 原生环境下装一个,因为 Claude Code 的 Bash 工具依赖它。
5种安装方式:命令可直接复制
方式一:原生安装脚本(官方推荐,macOS / Linux / WSL)
方式二:原生安装脚本(Windows),注意 PowerShell 与 CMD 的命令不同:
方式三:Homebrew(macOS / Linux)
方式四:WinGet(Windows)或 Linux 发行版包管理器
方式五:npm 或 npx(唯一需要 Node.js 的一条路)
| | | |
|---|
| | | |
| | | 用 brew upgrade claude-code 升级 |
| | | |
| | | 用 npm install -g @anthropic-ai/claude-code@latest 升级 |
| | | |
为什么不再首选 npm?npm 全局安装需要写系统目录,权限问题(EACCES)是社区最高频的安装故障之一,而官方文档明确要求不要用 sudo 去绕过——那会留下 root 所有的文件,破坏后续更新。另外 npm 包实际是通过平台相关的可选依赖去拉原生二进制的,如果你用 --omit=optional(或在 .npmrc 里设了 optional=false),二进制根本不会被安装,运行时只会报 Could not find native binary package——这个包没有 JavaScript 兜底实现。
装完必做的3步:验证、登录、更新
- 验证安装成功:运行 claude --version,能显示版本号即成功。若提示命令不存在,多半是 PATH 没刷新——开一个新终端,或执行 source ~/.zshrc(Bash 用户为 ~/.bashrc);Windows 上关闭并重开 PowerShell。
- 完成登录:在项目目录下直接运行 claude,首次会触发浏览器 OAuth 授权流程。授权成功后凭据保存在本地 ~/.claude/,之后一般不需要重复登录。换账号用会话内命令 /login,或终端里 claude auth login。CI/CD 场景改用环境变量 ANTHROPIC_API_KEY 走非交互认证。
- 知道怎么更新与自检:claude update 手动更新(原生安装通常会自动更新);遇到疑难问题运行 claude doctor,它会打印一份诊断报告,是提工单时最有用的材料。注意要在普通 shell 里跑,不要在 Claude 会话内部跑。
顺带说清一个常见混淆:Claude Code 的登录账号和 VS Code / JetBrains 插件是共用的——插件复用 CLI 的凭据,所以在终端登录一次即可;而 JetBrains 插件需要先单独装好 CLI,它是在 IDE 终端里调用 CLI 来工作。
12个常见报错与解法
下表按"报错原文 → 原因 → 修复"整理,前 10 条来自 Anthropic 官方支持文档所列的高频问题(官方称这十条覆盖了绝大部分安装与认证工单):
| | |
|---|
claude: command not found | 安装脚本已把 claude 加进 PATH,但当前 shell 还没重新加载 | 开新终端,或 source ~/.zshrc/~/.bashrc;Windows 关闭并重开 PowerShell。原生安装的目录通常是 ~/.local/bin,npm 路线要先 npm bin -g 看路径 |
npm 报 EACCES / permission denied | 安装时用过 sudo,或全局 npm 目录属 root | 不要用 sudo。改用原生安装脚本;若必须用 npm,先 npm config set prefix ~/.npm-global,再把该 bin 目录加入 PATH |
"Node version not supported" 或启动即静默崩溃 | | node -v 自查,用 nvm install --lts 升级;或直接换原生安装,它自带运行时 |
WSL 里 claude 跑的是 Windows 的 Node | Windows 的 PATH 泄漏进 WSL,覆盖了 nvm | 在 ~/.bashrc 里把 Linux 的 node 前置:export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH" |
| | 先设代理再重跑:export HTTPS_PROXY=http://代理地址:端口;或向 IT 索取离线安装包 |
SELF_SIGNED_CERT_IN_CHAIN 等 TLS 错误 | | 让 Node 指向企业 CA:export NODE_EXTRA_CA_CERTS=/路径/company-ca.pem,并写进 shell 配置文件使其长期生效 |
/login 能打开浏览器,但终端一直卡在"等待验证" | 本地回调地址被拦截,常见于远程 SSH、容器开发环境、严格防火墙 | 改用手动流程:复制终端打印的 URL,在任意浏览器完成登录,再把返回的验证码粘回终端 |
明明设了 ANTHROPIC_API_KEY,仍提示未认证 | 三种常见原因:密钥是在另一个 shell 里导出的;Claude Code 首次使用需要你确认信任该密钥;或你的组织要求走 SSO 而非 Console 密钥 | 先 echo $ANTHROPIC_API_KEY 确认当前 shell 能看到;首次使用时按提示确认信任;组织账号按其要求走 SSO |
Bedrock / Vertex 报 "Could not load credentials" | | Bedrock:确认 aws sts get-caller-identity 可用、AWS_REGION 指向已启用该模型的区域。Vertex:确认已运行 gcloud auth application-default login,并设置 ANTHROPIC_VERTEX_PROJECT_ID 与 CLOUD_ML_REGION |
装好也认证了,但每个请求都 403 / "model not available" | | 企业席位先确认席位已在管理后台激活;Bedrock/Vertex 确认该模型在对应区域或项目已启用。临时办法:/model 换一个你有权限的模型 |
安装脚本返回 403,页面写着 "App unavailable in region" | | 这是服务地域限制,不是安装问题——见下方"地区可用性"一节 |
WSL 上运行报 Exec format error | | |
另有一个 Windows 特有的坑:如果你之前装过旧版 Claude 桌面应用,它会在 WindowsApps 里注册一个 Claude.exe 并抢占 PATH 优先级,导致你敲 claude 打开的是桌面应用而不是 CLI。升级桌面应用即可解决。
装之前要算的一笔账:付费与模型
Claude Code 没有免费档。官方定价常见问答的表述是"Claude Code 包含在所有付费计划中",免费计划只覆盖聊天。三条付费路径:
| | |
|---|
| | 入门额度,默认 Sonnet 5,可手动切到 Opus 5 |
| | 约 5 倍 Pro 额度,高峰优先,默认 Opus 5 |
| | |
| Standard 25 美元/席位/月起;Premium 125 美元/席位/月起 | Premium 档与 Max 5x 的 Claude Code 权益对齐,另加管理后台与 SSO |
| | |
API 参考单价(每百万 token):Haiku 4.5 输入 1 美元 / 输出 5 美元;Sonnet 5 约 3 / 15 美元;Opus 5 为 5 / 25 美元;Fable 5.1 为 10 / 50 美元。提示缓存读取约为标准输入价的 10%,Batch 接口再打 5 折。具体价格与活动会变,以下单时官方定价页为准。
两个容易踩的认知坑。
第一,不同付费方式默认跑的模型不一样。按 Anthropic 的模型配置文档:Max、Team Premium、企业按量席位与直连 API 默认 Opus 5;Pro、Team Standard 与企业订阅席位默认 Sonnet 5。所以一个 20 美元的 Pro 用户照搬 100 美元 Max 用户的教程,跑的可能不是同一个模型,结果和消耗都会不同。想换模型用 /model;另外有一个 opusplan 模式——用 Opus 做方案规划、用 Sonnet 执行改动,是"想要 Opus 级架构决策又不想按 Opus 价付每一次编辑"的最省做法。Fable 5.1 不是任何档位的默认模型,且需要在 Claude Code 2.1.250 或更高版本才会出现在选择器里。
第二,额度限制的算法和直觉不同。Pro 用的是5 小时滚动窗口——下午 2 点用满,下一次要等到 7 点,而不是等到第二天零点。官方不公布 Pro 窗口的确切 token 数,社区测算约为每 5 小时 4.4 万 token(属于社区推算,非官方数据)。Max 档有两个独立的周限额:一个跨全部模型,另一个只针对 Sonnet 系列,各自从会话开始时起算 7 天——"感觉额度比预期用完得早"多半是因为撞到了其中一个小限额,而另一个其实还有余量。
地区可用性:中国大陆用户的现实情况
这是安装前最该先确认的一件事,因为它不属于"报错可以修"的范畴。Anthropic 官方目前未在中国大陆提供服务支持,中国大陆不在其公布的服务地区列表内。具体表现是:IP 归属地被识别为中国大陆时,访问安装地址可能直接返回 403 与 "App unavailable in region" 页面,注册流程中也没有中国大陆这个可选地区;此外官方域名与 API 接口在国内网络环境下还存在连接超时、TLS 握手失败等连通性问题;账号层面则表现为注册不支持中国大陆手机号、订阅仅支持海外信用卡。
据媒体报道,Anthropic 自 2026 年 7 月起对消费者账户(Free / Pro / Max)推行 KYC 身份核验,要求提交政府签发的身份证件并做人脸比对,Team、Enterprise 与 API 开发者账户暂不受影响;同时风控对 IP 频繁切换、非支持地区访问等行为的识别力度在加强。这些属于媒体报道与社区观察,不是官方公告口径,请自行核实。
如果你的环境不在官方服务范围内,有几条合规路径可考虑。
其一,接入兼容 Anthropic 协议的模型服务:Claude Code 支持通过 ANTHROPIC_BASE_URL 与 ANTHROPIC_API_KEY 两个环境变量把请求指向第三方端点(这本来是给 Bedrock、Vertex、企业自建网关用的官方配置项)。国内已有模型服务商提供兼容 Anthropic 协议的接口,配置后可以保留 Claude Code 的 CLI 交互习惯。
其二,采用国内可直连的同类终端 agent 工具,形态和用法接近,网络与支付门槛更低。
其三,仅把它当作技术参考——Claude Code 的 Sub-agents、Skills、Hooks、Agent Teams 等工程化设计,对理解 AI 编程工具的演进方向有参考价值。
无论选择哪条路径,都请遵守服务商的条款与所在地的法律法规,不要通过非正规渠道获取账号或支付。
常见问题
Q:安装 Claude Code 要钱吗?
A:安装本身免费,但使用需要付费。它没有免费档,至少要 Pro 订阅(20 美元/月)或 API 额度。免费计划只能用网页版聊天。
Q:必须装 Node.js 吗?
A:不必。只有选 npm / npx 路线时才需要 Node.js 18+。官方推荐的原生安装脚本自带运行时。
Q:Windows 上要装 WSL 吗?
A:不一定,Windows 10 1809+ 与 Windows Server 2019+ 已支持原生运行。但官方建议在原生 Windows 下装一个 Git,否则 Bash 工具无法正常工作。若走 WSL,请确保是 WSL 2。
Q:装完在哪用?
A:同一个 agent 有多个入口——终端 CLI(功能最全、新特性最先落地)、VS Code 扩展、JetBrains 插件、Claude 桌面应用的 Code 标签页、以及网页端 claude.ai/code。它们共用同一套配置与登录状态。建议新手先学终端版。
Q:怎么确认装的是最新版?
A:claude --version 看版本号,claude update 升级。若用 Homebrew 或 WinGet 安装,则通过包管理器升级。
Q:报错一时找不到头绪怎么办?
A:在普通 shell 里运行 claude doctor,它会输出一份诊断报告,比逐条猜错误快得多。
Q:企业账号装完提示没有模型权限?
A:先确认席位已在管理后台激活,云厂商路线还要确认目标模型在对应区域或项目已启用;临时可以先 /model 切到有权限的模型继续用。
Q:一定要用 sudo 才能装上吗?
A:不需要,而且不要用。sudo 会留下 root 所有的文件,破坏后续自动更新。遇到权限报错的正确做法是改用原生安装脚本,或修正 npm 的全局目录属主。
如何安装Claude Code,核心思路是:官方现在更推荐用原生安装程序,图省心选这个;习惯用包管理器的,Homebrew、WinGet等对应的包管理器都支持,但记得这几种方式默认不自动更新,需要手动升级或者开启对应的自动更新环境变量;装完用claude--version验证,再跑一下/init把CLAUDE.md建起来,基本就能顺利开始用了。