Claude Code 安装：各系统官方方法与常见问题

更新于 2026-10-30 · fishxcode.cyou

简答：如果你要在终端安装 Claude Code：macOS、Linux 或 WSL 优先运行官方原生安装命令，Windows PowerShell 运行官方 PowerShell 安装命令；安装后重新打开终端，在项目目录执行 claude，再完成登录。若只想使用 Claude Desktop 的 Code 功能，则无需单独安装终端版。

定义：Claude Code 是运行在终端、IDE 或 Claude Desktop 中的智能编程工具，可以读取项目、编辑文件并执行经过授权的命令。

先选安装方式：不要把 npm 当作首选

本文根据截至 2026-10-30 可核验的官方资料整理。本站是独立的 AI API 接入指南站，不是 Claude Code 官方站；安装命令和账号规则应以官方文档为准。

环境	优先方法	命令	适用说明
macOS/Linux	原生安装	`curl -fsSL https://claude.ai/install.sh \| bash`	官方推荐，适合直接使用终端版。
Windows PowerShell	原生安装	`irm https://claude.ai/install.ps1 \| iex`	Windows 官方推荐方式。
macOS/Linux	Homebrew	`brew install --cask claude-code`	已有 Homebrew、希望由包管理器维护时使用。
Windows	WinGet	`winget install Anthropic.ClaudeCode`	习惯使用 Windows 包管理器时使用。
npm	不建议作为新安装方式	`npm install -g @anthropic-ai/claude-code`	官方 README 已标注为 deprecated；不要使用 `sudo npm install -g`。

官方 README 同时给出了原生安装、Homebrew、WinGet 和 npm 方式，但明确提示 npm 安装已弃用。优先使用与你系统匹配的原生方式，可减少 Node 版本和全局权限问题。参考：官方 GitHub README。

macOS、Linux 与 WSL：安装、验证、启动

打开终端。macOS 可使用 Terminal 或 iTerm；Linux 和 WSL 使用对应发行版的 shell。
运行原生安装命令：
```
curl -fsSL https://claude.ai/install.sh | bash
```
命令中的地址应保持为官方 claude.ai 域名，不要把搜索结果中的未知脚本替换进去。
安装结束后关闭并重新打开终端，然后检查版本：
```
claude --version
```
进入你的项目目录，再启动 Claude Code：
```
cd /path/to/your-project
claude
```
/path/to/your-project 只是占位路径，请替换成实际项目目录。首次启动通常会进入登录或授权流程。

成功判定不是只看安装命令没有报错，而是同时满足：claude --version 能返回版本信息、在项目目录执行 claude 能启动、登录流程能完成。如果终端显示找不到命令，先重开终端或执行 source ~/.zshrc、source ~/.bashrc；官方 FAQ 说明原生安装通常把命令放在 ~/.local/bin/claude。

WSL 中建议把 Claude Code 当作 Linux 环境使用，并确认 PATH 中优先的是 WSL 内的 Linux 工具，而不是 Windows Node。若运行时调用了 Windows Node，可按官方排查建议检查并调整 shell 的 PATH。参考：官方安装与认证排查。

Windows：PowerShell、CMD、Git Bash 与 WSL 怎么选

环境	建议	注意事项
PowerShell	优先使用原生安装	运行 `irm https://claude.ai/install.ps1 \| iex`，完成后重开 PowerShell。
CMD	可用于启动和验证	安装命令本身优先在 PowerShell 中执行；安装后可在 CMD 运行 `claude --version`。
Git Bash	适合已有 Unix 风格工作流的用户	若 PATH 未刷新，关闭并重新打开窗口；遇到路径混用时先改用 PowerShell 验证。
WSL	适合需要 Linux 工具链、容器或远程开发环境的用户	在 WSL 内执行 Linux 安装命令，避免混用 Windows Node 与 Linux Node。

Windows 原生安装命令：

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

也可以使用 WinGet：

winget install Anthropic.ClaudeCode

两种方式不要在没有确认的情况下反复混装。若已经安装过一种方式，发现系统调用的不是预期版本，先执行 where claude 查看命令来源，再保留一种安装渠道并重新打开终端。

首次登录：订阅账号、Console API Key 与代理要分清

Claude Code 的登录方式会影响用量归属。官方资料区分了 Claude 的订阅账号和 Console/API Key：Pro 或 Max 用户可以用对应 Claude 账号登录；使用 Console、Bedrock、Vertex 或其他支持的 API Key 时，则按对应 API 账户计费或受对应组织权限控制。不要把订阅额度和 API Key 的用量当成同一套系统，具体规则以当前账号和官方帮助中心为准。

在项目目录运行 claude，按提示完成登录。
如果浏览器在另一台机器打开，或你通过 SSH 登录远程服务器，在登录提示处按 c 复制授权地址，用本地浏览器完成认证，再把返回代码粘贴回终端。
登录后运行 /status，确认当前使用的是订阅认证还是 API Key。
如果希望使用订阅而不是 API Key，检查环境变量是否存在。macOS/Linux：
```
echo $ANTHROPIC_API_KEY
```
Windows CMD：
```
echo %ANTHROPIC_API_KEY%
```
Windows PowerShell：
```
echo $env:ANTHROPIC_API_KEY
```

官方帮助中心说明，环境变量中的 ANTHROPIC_API_KEY 可能优先于已登录的订阅账号，并导致 API 用量计费。不要把真实 Key 写入文章、截图、Git 仓库或命令历史；排查时也不要把 Key 的完整内容发送给他人。参考：官方 API Key 环境变量说明和官方 Pro/Max 使用说明。

安装后验收：用一个最小闭环确认能工作

确认命令可见：claude --version。
确认项目目录正确：使用 pwd 或 Windows 的 cd 检查当前路径。
启动：执行 claude。
完成登录后运行 /status，核对认证方式。
先提出低风险任务，例如“列出当前项目的主要目录，并说明可能的启动命令”，不要一开始就授权批量修改或删除文件。
涉及命令执行、文件修改或网络访问时，先阅读终端中的权限提示，再决定是否允许。

如果你只是想在桌面应用中使用 Code 功能，官方帮助中心说明 Claude Desktop 已内置 Claude Code，登录后打开 Code 标签即可，不需要额外安装终端版。

常见安装失败：按症状分流

claude: command not found：先重开终端；macOS/Linux 检查 ~/.local/bin 是否在 PATH，Windows 关闭并重开 PowerShell。仍失败时运行 where claude 或 which claude 检查命令路径。
npm 出现 EACCES 或 permission denied：不要用 sudo 重试。官方建议改用原生安装；若必须处理旧 npm 环境，应修复 npm prefix 和 PATH，而不是把全局目录交给 root。
安装卡住或下载失败：官方排查资料指出，企业网络可能阻断下载主机或 TLS 证书链。先确认代理、证书和网络策略，再联系网络管理员；不要随意替换成未知下载地址。
/login 一直显示等待认证：常见于 SSH、开发容器或严格防火墙环境。复制终端中的授权地址，在可打开浏览器的设备完成登录，再把代码粘回终端。
登录后仍提示未认证：检查 API Key 是否在另一个 shell 中设置、是否需要首次信任该 Key，以及组织是否要求 SSO；使用 /status 查看当前认证状态。
403 或 model not available：这通常不是安装命令问题，而是账号、组织席位、云平台区域或模型权限未开通。确认管理员权限或在 /model 中选择当前账号可用的模型。
仍无法定位：在普通终端而不是 Claude Code 会话内运行 claude doctor，保存诊断结果后再联系管理员或官方支持。

更新、卸载与 npm 旧安装处理

原生安装、Homebrew 和 WinGet 的更新机制不同。官方 FAQ 说明原生安装会在后台更新，也可以手动运行：

claude update

Homebrew 更新：

brew upgrade claude-code

WinGet 更新：

winget upgrade Anthropic.ClaudeCode

如果你之前通过 npm 安装，先不要继续使用 sudo npm install -g 覆盖安装。可以先确认旧安装位置和 PATH，再根据官方当前安装方式迁移；具体卸载命令可能随安装渠道变化，建议以当前设置文档中的卸载章节为准。

需要把 Claude Code 接入兼容接口、配置 Base URL 或排查 401/403 时，应把“客户端安装”和“API 接入配置”分开验证：先确保原生 Claude Code 能启动，再处理 Key、网关和模型参数。

常见问题

Claude Code 安装一定要用 npm 吗？

不需要。官方 README 已将 npm 安装标为 deprecated，新安装优先使用 macOS/Linux 原生脚本、Windows PowerShell 脚本、Homebrew 或 WinGet；不要使用 sudo npm install -g。

Windows 安装 Claude Code 应该选 PowerShell 还是 WSL？

只想在 Windows 项目中直接使用，优先 PowerShell 原生安装；需要 Linux 命令、容器或 Linux 开发工具链时，再在 WSL 内单独安装并验证。不要把 Windows Node、Linux Node 和多个安装渠道混在同一个 PATH 中。

安装后为什么提示 claude 不是内部或外部命令？

通常是终端没有刷新 PATH。先关闭并重新打开终端；macOS/Linux 检查 ~/.local/bin 是否在 PATH，Windows 检查用户 PATH 和 where claude 的输出。

Claude Code 登录后会不会误用 API Key？

有可能。如果环境变量 ANTHROPIC_API_KEY 存在，官方说明它可能优先于订阅认证。运行 /status 查看当前认证方式；使用订阅时不要在环境中保留不需要的 API Key。

SSH 远程服务器无法完成登录怎么办？

在登录提示处按 c 复制授权地址，在本地浏览器完成认证，再把返回代码粘贴回远程终端。若仍失败，再检查代理、防火墙和 localhost 回调限制。

Claude Desktop 还需要单独安装 Claude Code 吗？

如果你只使用 Claude Desktop 的 Code 标签，不需要单独安装终端版；如果你希望在项目目录中执行 claude、使用脚本或远程终端，则按本文安装终端版。

参考资料

Claude Code 官方文档：Advanced setup / Getting started（code.claude.com）
Anthropic Claude Code 官方 GitHub README
Claude Help Center：安装与认证排查（support.claude.com）
Claude Help Center：Claude Code 用户常见问题（support.claude.com）
Claude Help Center：Claude Code API Key 环境变量（support.claude.com）
Claude Help Center：使用 Pro 或 Max 计划连接 Claude Code（support.claude.com）