第 2 章 安装、登录与更新

对应官方页面：Advanced setup ｜ Authentication ｜ Troubleshoot installation
抓取日期：2026-10-23 ｜ 适用版本：Claude Code 2.1.x

2.1 先确认你能装

⚠️ 踩坑提醒：网络受限时先看官方 Network configuration 文档。安装脚本、自动更新、模型请求走的是不同域名，只放行一部分会出现「装上了但连不上」。

2.2 三种安装方式怎么选

给小白：直接用原生安装。 它自带后台自动更新，不用你操心版本。Homebrew 用户注意：claude-code 是 stable 通道（约晚一周、跳过有严重回归的版本），claude-code@latest 是 latest 通道。

2.3 安装步骤

macOS / Linux / WSL

打开「终端」（macOS：Cmd+空格 输入 Terminal），运行官方安装脚本：

curl -fsSL 官方安装脚本地址 | bash

📘 官方：安装过程中没有任何进度显示，看起来像卡住了，其实在下载。等它结束就好。

Windows

先看你终端里提示符的样子：

• 显示 PS C:\Users\你的名字> → 你在 PowerShell
• 显示 C:\Users\你的名字>（没有 PS）→ 你在 CMD

PowerShell：

irm 官方安装脚本地址 | iex

CMD：

curl -fsSL 官方安装脚本地址 -o install.cmd && install.cmd && del install.cmd

⚠️ 常见报错对照

• The token '&&' is not a valid statement separator → 你在 PowerShell，用了 CMD 的命令
• 'irm' is not recognized as an internal or external command → 你在 CMD，用了 PowerShell 的命令

装不装 Git for Windows？ 建议装。装了之后 Claude Code 用 Git Bash 执行 Bash 工具，行为和 macOS/Linux 一致，网上搜到的命令也能直接抄。不装则用 PowerShell 工具，很多 Unix 命令（grep、sed、tail -f）会失效。

如果 Git Bash 已装但 Claude Code 找不到，在 settings.json 里指定路径：

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

WSL 用户

在 WSL 的终端里运行 Linux 安装命令，不要在 PowerShell 里跑。

🔍 补充细节：WSL 2 支持沙箱（第 7 章），原生 Windows 不支持。如果你的工作流依赖沙箱，用 WSL 2。反之，如果项目就是 Windows 原生工具链（.NET、Visual Studio），用原生 Windows。

Alpine / musl 发行版

apk add bash curl libgcc libstdc++ ripgrep

然后在 settings.json 里加：

{ "env": { "USE_BUILTIN_RIPGREP": "0" } }

2.4 验证安装

关掉当前终端窗口，重新开一个，然后：

claude --version

正常输出类似：

2.1.296 (Claude Code)

再做一次完整体检：

claude doctor

它会读取安装健康度、settings 校验错误、以及带修复建议的警告，不会启动会话。这是排查环境问题的第一条命令。

报 command not found

安装目录还没进 PATH。官方排错页（Troubleshoot installation）给了各 shell 的修复方法，找到 command-not-found 章节即可。

🔍 补充细节：macOS/Linux 上原生安装的可执行文件是 ~/.local/bin/claude（指向 ~/.local/share/claude/versions/ 的符号链接）。快速自查：

ls -l ~/.local/bin/claude
echo $PATH | tr ':' '\n' | grep -n '\.local/bin'

第二条没输出，就是 ~/.local/bin 不在 PATH 里。

2.5 登录

在任意项目目录运行：

claude

首次启动会打开浏览器。流程如下：

1. 浏览器里登录你的 Claude 官网 / Console 账号
2. 授权后浏览器跳回，终端显示 Login successful
3. 按 Enter 继续

浏览器没自动打开？ 在登录提示处按 c 复制链接，粘贴到浏览器。

浏览器里显示了一串登录码而不是跳转回来？ 把那串码粘贴到终端的 Paste code here if prompted 处。这在 WSL2、SSH、容器里很常见（浏览器访问不到本机的回调端口）。

支持哪种账号

登录相关的常用命令

凭证优先级（很重要）

同时存在多种凭证时，Claude Code 按下面顺序选第一个可用的：

1. 云平台凭证（设了 CLAUDE_CODE_USE_BEDROCK / _VERTEX / _FOUNDRY 时）
2. ANTHROPIC_AUTH_TOKEN
3. ANTHROPIC_API_KEY
4. apiKeyHelper 脚本输出
5. CLAUDE_CODE_OAUTH_TOKEN
6. Anthropic profile / 联邦凭证
7. /login 的订阅 OAuth 凭证 ← 大多数人走这条

⚠️ 踩坑提醒：这是新手最常见的「账单异常」原因。你明明买了 Max 订阅，但 shell 里残留一个 ANTHROPIC_API_KEY，Claude Code 就会优先用它，费用走 API 账单。

# 检查
echo "${ANTHROPIC_API_KEY:+API key 已设置}"
# 改回订阅
unset ANTHROPIC_API_KEY

然后 /status 确认当前生效的是订阅登录。/status 会标出「没在用」的那份凭证。

在交互模式下，Claude Code 会让你确认一次是否使用这个 API key，选择会被记住。想改回来用 /config 里的 Use custom API key 开关（只有环境里有 key 时这个开关才出现）。-p 非交互模式下不做询问，有 key 就直接用。

一台机器上登录多个账号

用 CLAUDE_CONFIG_DIR 给每个账号一套独立的配置目录：

# 加到 ~/.zshrc 或 ~/.bashrc
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

claude-work 和 claude 各有独立的 settings、会话历史、登录状态。

🔍 补充细节：不创建 API key 的 Console 登录方式，凭证存放在配置目录之外，因此这种登录不能靠 CLAUDE_CONFIG_DIR 隔离。

凭证存在哪

设了 CLAUDE_CONFIG_DIR 时，.credentials.json 跟着走。

2.6 更新

自动更新（原生安装）

启动时检查，运行中定期检查；后台下载安装，下次启动生效。看上次更新结果：

claude doctor

手动立即更新

claude update

成功时输出 Successfully updated from <旧版本> to version <新版本>；已是最新则输出 Claude Code is up to date (<版本>)。

选发布通道

// ~/.claude/settings.json
{
  "autoUpdatesChannel": "stable"
}

也可以 /config → Auto-update channel 切换。

🔍 补充细节：新模型发布时可能要求比 stable 通道更新的版本。如果你「模型列表里没有这个新模型」，先切到 latest 或运行 claude update。

想固定版本

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

minimumVersion 是下限，不会让你降级。团队里想强制统一版本，用 managed settings 的 requiredMinimumVersion / requiredMaximumVersion。

关掉自动更新

{
  "env": { "DISABLE_AUTOUPDATER": "1" }
}

⚠️：DISABLE_AUTOUPDATER 只关后台检查，claude update 仍可手动更新。要彻底禁止所有更新路径，用 DISABLE_UPDATES。这在用 NFS / 网络存储共享 home 目录的团队里是必须的——一台机器的原地升级会删掉另一台机器正在运行的二进制文件，表现为 shell 报 Bus error。

包管理器安装的更新

brew upgrade claude-code            # 或 claude-code@latest
winget upgrade Anthropic.ClaudeCode
sudo apt update && sudo apt upgrade claude-code
sudo dnf upgrade claude-code
apk update && apk upgrade claude-code

想让 Claude Code 自己在后台跑 Homebrew / WinGet 升级：

{ "env": { "CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "1" } }

apt/dnf/apk 需要提权，只能手动升级。

2.7 卸载

# 原生安装
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude


# Homebrew
brew uninstall --cask claude-code          # 或 claude-code@latest


# WinGet
winget uninstall Anthropic.ClaudeCode


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

删配置文件（会丢失全部设置、MCP 配置、会话历史）：

rm -rf ~/.claude
rm ~/.claude.json
# 项目内（在项目目录执行）
rm -rf .claude .mcp.json

⚠️ 踩坑提醒：VS Code 扩展、JetBrains 插件、桌面端都会写 ~/.claude/。它们还装着的话，删完会被重新创建。要彻底清干净，先卸载这些客户端。

2.8 本章要点

• 原生安装 = 自动更新，最省心；包管理器安装需手动更新
• 装完先 claude --version，再 claude doctor
• 免费版 Claude 官网不含 Claude Code
• 凭证优先级：云平台 > AUTH_TOKEN > API_KEY > apiKeyHelper > OAUTH_TOKEN > profile > /login
• 订阅用户务必 unset ANTHROPIC_API_KEY，否则费用走 API
• 多账号用 CLAUDE_CONFIG_DIR 隔离

下一步 → 第 3 章 第一次会话