Claude Code 更新升级与版本检查教程

Claude Code 能正常启动，这当然让人放心，但别急着下结论。真正吊诡的地方在于更新路径本身：原生安装会在后台静默检查新版本，而 Homebrew、WinGet、Linux 包管理器和 npm 则必须沿着各自的安装来源升级。很多人在这一步翻车——明明看到“已是最新”，实际包管理器根本没动。所以，先确认当前版本和安装状态，再决定是等后台更新还是主动敲命令，才能避免那种“看起来没问题，实际上落后好几个版本”的尴尬。

这套流程在 Windows、macOS 和 Linux 上都通用。终点很明确：记下更新前的版本，确认更新通道，按安装来源执行一次正确的升级，最后用版本号和诊断结果收尾验证。

先锁定更新前的版本基线

1. 入口位置：
   打开实际运行 Claude Code 的终端——Windows 原生安装用 PowerShell 或 CMD，WSL、macOS 和 Linux 则用对应的 Bash 或 Zsh 终端。

   主要动作：
   先跑一遍 claude --version，把输出的版本号记下来；再执行 claude doctor，检查安装类型、配置和最近一次更新尝试。

   成功标志：
   版本命令返回版本号和 Claude Code 名称，doctor 给出诊断结果，没有阻断启动的错误。这个版本号就是后续判断升级是否生效的基线。

   失败处理：
   如果出现 command not found 或“无法识别命令”，先关闭旧终端再重新打开；仍然不行的话，检查 Claude Code 安装目录是否在 PATH 里。doctor 提示配置文件错误，就先按提示修好配置，再进入更新环节。

官方 Advanced setup 页面把 claude --version 和 claude doctor 放在同一个验证区域——前者确认程序和版本，后者负责更细的安装与配置诊断。

分清后台更新适用于哪种安装

2. 入口位置：
   查看 claude doctor 输出的安装信息，然后回忆最初是用 Claude Code 原生安装脚本、Homebrew、WinGet、apt、dnf、apk 还是 npm 装的。

   主要动作：
   原生安装可以依赖后台自动更新——Claude Code 会在启动时和运行期间定期检查，下载与安装在后台进行，新版本通常在下一次启动时生效。如果是包管理器安装的，不要指望这条后台路径，后续升级仍由相同的包管理器负责。

   成功标志：
   清楚知道自己属于“原生自动更新”还是“包管理器更新”，后续命令与最初安装来源保持一致。

   失败处理：
   如果判断不了安装来源，不要混着执行多组命令。先运行 claude doctor，再检查终端的命令位置：Windows 用 where claude，macOS 和 Linux 用 which claude。发现多个路径时，先处理重复安装，避免升级了一份却启动另一份。

截图中的 Auto-updates 说明了两个关键时点：更新在后台下载和安装，下一次启动才切换到新版本；最近一次尝试的结果可以用 doctor 查看。

在 latest 与 stable 之间做一次明确选择

3. 入口位置：
   启动 Claude Code 后输入 /config，找到 Auto-update channel；也可以在用户级 settings.json 中检查 autoUpdatesChannel。

   主要动作：
   希望新功能发布后尽快收到更新时选 latest（这也是默认值）；更看重稳定性时选 stable，该通道通常落后约一周，并跳过存在重大回归的版本。写入设置文件时，把 autoUpdatesChannel 的值设为 latest 或 stable。

   成功标志：
   /config 显示目标通道，或者保存后的 settings.json 能被 Claude Code 正常读取，没有格式错误。

   失败处理：
   设置保存后没有生效，先检查 JSON 的逗号、引号和层级。如果配置由组织统一管理，个人设置可能被覆盖，应以管理员下发的通道为准。Homebrew 安装是通过 cask 名称选择通道的，不要只改这个字段。

官方页面对两个通道的区别说得很直接：latest 接收每次发布，stable 使用通常约一周前、避开重大回归的版本。截图里的 autoUpdatesChannel 示例可以用来核对字段拼写。

原生安装需要立刻升级时运行 claude update

4. 入口位置：
   回到能正常跑 claude --version 的同一个终端，先退出正在运行的 Claude Code 交互会话。

   主要动作：
   执行 claude update。这会立即检查并应用目标通道上的更新，不必等下一次后台检查。

   成功标志：
   有新版本时，终端报告从旧版本更新到新版本；已经位于目标通道最新版本时，终端会明确报告 Claude Code 已是最新状态并显示版本。

   失败处理：
   网络错误时先保留终端原始提示，确认普通网页和 Claude 下载服务都能访问后再处理。权限错误不要直接改用高权限反复执行——先用 doctor 检查安装位置和文件权限。如果 Homebrew、WinGet 或 apk 管理的安装只返回简短的“已是最新”提示，改走下一步的包管理器升级。

Update manually 区域既给出了 claude update，也列明了“成功更新”和“已经最新”两种结果。看清终端属于哪一种，才能判断版本是否真的发生变化。

包管理器安装沿原渠道升级

5. 入口位置：
   打开最初安装 Claude Code 时使用的终端和包管理器。不要先卸载，也不要切换到另一种安装方式。

   主要动作：
   Homebrew 稳定通道执行 brew upgrade claude-code，latest cask 执行 brew upgrade claude-code@latest；WinGet 执行 winget upgrade Anthropic.ClaudeCode；apt、dnf 与 apk 使用各自的正常系统升级流程更新 claude-code；npm 安装执行 npm install -g @anthropic-ai/claude-code@latest。

   成功标志：
   包管理器显示 Claude Code 包被升级，或确认当前仓库中没有更高版本；命令结束时没有依赖、签名或权限错误。

   失败处理：
   npm 不要用 npm update -g 来追最新版本，因为它可能受原有版本范围限制。Homebrew 找不到 cask 时，先确认最初装的是稳定 cask 还是 latest cask；WinGet 找不到包时，先刷新源并核对包 ID。Linux 仓库错误应先修复仓库与签名配置，不要改装另一份二进制来掩盖问题。

用更新后的版本和 doctor 收口

6. 入口位置：
   关闭更新时用的终端，重新打开一个新终端，进入日常项目目录。

   主要动作：
   再次执行 claude --version，与第一步记录的版本号比较；随后执行 claude doctor，确认安装状态、配置和最近更新结果。

   成功标志：
   存在新版本时，版本号已经变化；本来就是最新版本时，版本号保持不变且更新命令明确给出最新状态。doctor 没有新的阻断错误，执行 claude 能进入正常会话。

   失败处理：
   更新命令成功但版本号没变，先用 where claude 或 which claude 检查是否存在多份安装，再确认新终端加载的是刚升级的路径。doctor 报告更新失败，就按安装来源修复网络、仓库、签名或权限问题；不要在同一目录叠加第二种安装方式。

确认这次升级真正生效

1. 版本有记录：
   更新前后的 claude --version 输出已经对比过，知道版本是变化了，还是原本就处于最新状态。

2. 安装来源唯一：
   原生、Homebrew、WinGet、Linux 包管理器或 npm 只保留一条主要更新路径。

3. 通道符合预期：
   latest 或 stable 已按功能速度与稳定性需求选定，没有被组织配置意外覆盖。

4. 诊断可读：
   claude doctor 能完成检查，没有 PATH、配置、仓库或权限方面的阻断错误。

5. 新终端可用：
   重新打开终端后，claude 能在日常项目目录启动，不会调用到另一份旧安装。

6. 图片可访问：
   四张当前官方页面截图都能打开，并分别证明版本诊断、后台更新、发布通道和手动更新。