如何升级 Claude Code：按安装方式更新，解决版本不变和升级失败

Claude Code 提示有新版本，运行更新命令后版本号却没变；或者终端已经更新，编辑器里的功能仍然没有变化。遇到这些情况，先确认当前运行的是哪一份程序，以及它由什么工具安装。

本文介绍 Claude Code 命令行客户端的升级方法，覆盖原生安装、npm、Homebrew 和 WinGet。升级客户端用于获得相应版本的功能和修复；模型使用权限、账号套餐及 API 服务配置，需要分别核对。

一、升级前，先查版本和安装来源

在系统终端中执行，而不是把命令输入 Claude Code 的聊天框：

claude --version
claude doctor

第一条记录当前版本，第二条查看安装和配置诊断。再检查系统实际调用的程序路径。

macOS、Linux、WSL：

type -a claude

Windows PowerShell：

Get-Command claude -All
where.exe claude

如果出现多个路径，可能同时存在 npm、原生安装或其他来源的副本。记住当前优先执行的路径，后面更新对应安装。Windows 和 WSL 也要分别检查：在 PowerShell 更新，不代表 WSL 内的程序一起更新。

开始前保存项目改动、结束正在进行的任务，并备份自行修改过的配置。公司统一管理的环境，应沿用团队规定的版本和安装来源。

二、按安装方式选择升级命令

以下分支选择与你的安装方式对应的一项即可。

1. 原生安装：运行 claude update

通过官方原生安装脚本安装的用户，可以执行：

claude update

完成后退出旧会话，重新启动 Claude Code，再查版本：

claude --version

官方文档说明，原生安装默认会在后台检查并安装更新，更新在下次启动时生效。因此，旧会话一直没有退出，是“更新了但界面没变化”的一种排查方向。

如果提示已经是最新版本，要结合当前更新通道判断，不能直接拿不同通道的版本号比较。来源：Claude Code 官方安装与更新文档

2. npm 安装：显式安装 latest 标签

如果原来通过 npm 全局安装，执行：

npm install -g @anthropic-ai/claude-code@latest
claude --version

这也是当前官方文档给出的 npm 升级方法。文档特别提醒，npm update -g 会受到原始安装的版本范围影响，可能无法更新到最新发布版本。

npm 安装还需要满足当前包的 Node.js 要求。本次核验时，官方文档列出的要求为 Node.js 22 或以上；出现 EBADENGINE 时先检查 node -v。这一要求针对 npm 安装方式，不能据此认定所有 Claude Code 安装都依赖 Node.js。

遇到目录写入权限错误，先检查 npm 全局安装目录及其归属，按官方排错指引处理。来源：官方 npm 安装说明

3. Homebrew 安装：更新实际安装的 cask

macOS 用户先刷新 Homebrew 索引，再更新对应包：

brew update
brew upgrade claude-code

如果安装的是 claude-code@latest，则使用：

brew upgrade claude-code@latest

当前官方文档区分了这两个 cask：claude-code 跟随 stable，claude-code@latest 跟随 latest。按已安装的名称操作，完成后重新启动并运行 claude --version。

4. WinGet 安装：通过 WinGet 升级

Windows 用户在 PowerShell 中执行：

winget upgrade Anthropic.ClaudeCode

如果提示程序正在使用，先退出 Claude Code，再重新执行。Windows 可能锁定运行中的可执行文件。官方文档说明，Homebrew 和 WinGet 安装默认需要通过包管理器更新。来源：官方更新说明

三、为什么升级后仍不是想要的版本？

先检查更新通道。对由 Claude Code 自身管理更新的安装，可以在会话内通过 /config 查看 Auto-update channel；相关配置字段为：

{
  "autoUpdatesChannel": "stable"
}

这是需要合并到现有配置中的字段示例，不要用它覆盖完整配置文件。

latest 用于及时获取新版本，stable 采用延后的稳定发布节奏。Homebrew 的通道则由 cask 名称决定。若目标功能明确要求某个最低版本，先核对功能文档与当前通道，再决定是否切换。来源：官方更新通道说明

再检查命令路径。若升级成功但版本没变，重新运行第一节的路径查询，确认刚更新的程序是否就是终端正在调用的程序。使用 Node.js 版本管理器的用户，也要检查当前 Node.js 环境对应的 npm 全局目录。

最后重新运行 claude doctor。如果是下载失败，保留具体网络错误；如果是权限失败，检查安装目录；如果是版本已更新但 API 调用失败，则进入接入配置排查。

四、通过 DDS Hub 接入的用户，升级后检查什么？

已经通过 DDS Hub（呆呆兽 Hub）接入 Claude Code 的用户，可以把客户端更新与服务连接验证分两步完成：先确认版本，再检查原有接入配置是否仍被当前终端读取。

重点核对服务地址、令牌是否有效，以及令牌对应的分组和客户端条件。DDS Hub 当前 Claude Code 教程提供了相关配置说明；其 FAQ 也列出了未分配分组、客户端限制、日限额和上游连接等不同错误。DDS Hub 配置教程｜报错指南

如果升级后出现 401、403 或 429，结合完整错误信息核查认证、权限和额度。仅凭状态码无法确定根因，也不能把升级客户端当作解决所有连接问题的办法。排查时记录变量是否存在即可，避免把完整 Token 打印到终端截图。

准备恢复日常使用时，先在熟悉的项目中做一个小范围任务，检查响应与工具执行是否正常，再继续较大的工作。DDS Hub 是第三方接入服务，客户端发布与升级方法仍以 Anthropic 官方文档为准。

本文操作依据于 2026 年 10 月 22 日访问的官方文档整理，命令未在本文中实际执行。后续安装方式或参数发生变化时，请核对对应官方章节。

本作品采用《CC 协议》，转载必须注明作者和本文链接