升级 Claude Code 前，花几分钟记录版本和入口，能减少升级后的路径排查。升级完成后用新进程确认版本，再做一项小任务检查。
升级前保存四项信息
先整理未完成任务的进度，保存必要文件。接着在终端运行：
claude --version
command -v claude
claude doctor
记录版本、路径、安装方式和诊断中的更新状态。原生安装、Homebrew 和 npm 可能曾在同一台 Mac 上出现，先确认当前使用的是哪一个。
在团队维护文档中记录实际版本、日期、渠道、安装来源和验收结论。不要把访问令牌或客户资料复制进去。
选择与安装来源一致的更新方法
原生安装可使用 claude update；它也默认在后台自动检查更新。Homebrew 默认手动更新，当前 claude-code 对应 stable，claude-code@latest 对应 latest。
# 仅在安装来源为这个 cask 时使用
brew upgrade claude-code
原生安装的渠道可以在 /config 检查。stable 通常延后一周，latest 跟随新发布版本。团队如果需要一致版本，先按团队渠道约定处理。
升级后分两层核对
结束旧的 Claude Code 进程，在新终端再次运行版本、路径与 doctor。对比升级前记录：版本是否变化、路径是否仍指向预期入口、诊断是否报告配置错误。
然后进入一个熟悉项目，只要求读取 README 和定位测试命令。确认能正常读取、回答所引用的路径正确，再进入正式代码修改。这项试跑能检查基础工作流程；项目回归测试仍按项目改动执行。
版本没变的排查顺序
- 确认已经退出旧进程并重新启动。
- 核对 command 路径是否仍指向较旧安装。
- 核对安装来源和升级命令是否一致。
- 检查 stable 是否尚未发布所需版本。
- 查看 doctor 中上次更新失败原因。
官方记录了更新通知可能先于包管理器分发的情况。此时保留安装和诊断记录，等对应包可用后再更新。
常见问题
Q: 升级前要退出所有项目吗？
A: 先保存各项目任务进度，升级后重启需要使用新版本的 Claude Code 进程。
Q: 为什么旧终端和新终端版本不同？
A: 检查进程是否重启以及命令路径；PATH 和多个安装入口可能指向不同版本。
Q: Homebrew 能用原生 autoUpdatesChannel 切渠道吗？
A: 当前 Homebrew 通过 cask 名选择 stable 或 latest，按安装来源核对。
Q: doctor 会启动模型任务吗？
A: 官方将终端中的 claude doctor 描述为只读安装与配置诊断，不启动会话。
Q: 小任务成功就代表项目测试通过吗？
A: 小任务只确认基础读取和响应；项目测试需要单独运行并记录结果。
Q: 同事需要哪些信息来复查升级？
A: 提供日期、升级前后版本、安装来源、渠道、命令路径及 doctor 相关报错，保留任务进度说明。