​

自动更新机制

​

概述

​

安装类型与更新策略

​

策略路由

• native → NativeAutoUpdater（二进制下载 + 符号链接）
• package-manager → PackageManagerAutoUpdater（仅通知）
• 其他 → AutoUpdater（基于 JS/npm）

​

后台自动更新循环

useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟

​

前置检查门控

1. 自动更新是否被禁用？ — getAutoUpdaterDisabledReason()（src/utils/config.ts:1735）
   • NODE_ENV === 'development'
   • 设置了 DISABLE_AUTOUPDATER 环境变量
   • 仅限必要流量模式
   • config.autoUpdates === false（native 安装的保护模式除外）
2. 最大版本上限？ — getMaxVersion()（src/utils/autoUpdater.ts:108）— 服务端熔断开关，防止更新到已知有问题的版本
3. 是否跳过该版本？ — shouldSkipVersion()（src/utils/autoUpdater.ts:145）— 尊重用户的 minimumVersion 设置，防止切换到 stable 频道时发生意外的版本降级

​

Native 自动更新器（src/components/NativeAutoUpdater.tsx）

1. 调用 src/utils/nativeInstaller/installer.ts 中的 installLatest()
2. 通过 src/utils/nativeInstaller/download.ts 下载二进制文件（GCS 或 Artifactory）
3. 验证 SHA256 校验和（3 次重试，60 秒卡顿检测）
4. 将版本化二进制文件存储到 XDG 目录
5. 更新符号链接（~/.local/bin/claude → 新版本二进制文件）
6. 保留最近 2 个版本，清理旧版本
7. 将错误分类上报分析（超时、校验和、权限、磁盘空间不足、npm、网络）

​

JS/npm 自动更新器（src/components/AutoUpdater.tsx）

1. 调用 getLatestVersion() 获取当前 npm dist-tag
2. 通过 semver gte() 比较版本
3. 根据安装类型路由到本地或全局安装
4. 使用文件锁（acquireLock() / releaseLock()）防止并发更新

​

包管理器通知器（src/components/PackageManagerAutoUpdater.tsx）

• macOS: brew upgrade claude-code
• Windows: winget upgrade Anthropic.ClaudeCode
• Alpine: apk upgrade claude-code

​

启动版本门控

void assertMinVersion();

1. 从 GrowthBook 动态配置获取 tengu_version_config
2. 如果 MACRO.VERSION < minVersion，打印错误信息并调用 gracefulShutdownSync(1) — 强制用户更新
3. 这是一个硬性门控 — 低于最低版本的 CLI 将无法启动

​

手动 CLI 命令

​

claude update / claude upgrade

1. 运行 getDoctorDiagnostic() 检查系统健康状态
2. 检查是否存在多个安装及配置不一致
3. 根据安装类型路由：
   • development → 报错（“开发版本不支持自动更新”）
   • package-manager → 打印对应操作系统的更新命令
   • native → 使用原生安装器的 updateLatest()
   • npm-local → 在 ~/.claude/local/ 执行 npm install
   • npm-global → 执行 npm install -g（含权限检查）
4. 报告当前版本、最新版本、成功/失败状态

​

claude rollback [target]（仅限内部）

​

claude install [target]

​

claude doctor

​

原生安装器架构

​

二进制文件存储布局

~/.local/share/claude-code/
├── versions/          # 版本化二进制文件 (claude-1.0.3, claude-1.0.4, ...)
├── staging/           # 临时下载暂存区
└── locks/             # 基于 PID 和 mtime 的锁文件

~/.local/bin/claude    # 指向当前版本二进制文件的符号链接

​

核心操作

​

下载与校验

1. 路由到 Artifactory（内部用户）或 GCS 存储桶（外部用户）
2. 下载二进制文件并跟踪进度
3. SHA256 校验和验证
4. 60 秒卡顿检测（中止停滞的下载）
5. 失败时自动重试 3 次

​

文件锁机制

• 锁文件：~/.claude/update.lock（或等效路径）
• 5 分钟超时 — 超过 5 分钟的锁被视为过期，强制获取
• 进程将其 PID 写入锁文件
• acquireLock() 和 releaseLock() 同时被 JS/npm 和原生安装器使用

​

配置

​

设置项

​

全局配置

​

配置迁移

​

更新通知去重

​

更新日志

1. 从 src/setup.ts:387 在每次启动时调用
2. 从 GitHub 获取 changelog
3. 缓存到 ~/.claude/cache/changelog.md
4. 展示比 lastReleaseNotesSeen 更新的版本的更新日志
5. 使用 semver 比较确定需要展示哪些日志

​

版本比较

• 提供 gt()、gte()、lt()、lte()、satisfies()、order()
• 在 Bun 环境下使用 Bun.semver.order()（快 20 倍）
• 在 Node.js 环境下回退到 npm semver 包

​

分析事件

​

关键文件索引

​

流程图

启动阶段
  ├── assertMinVersion() → 版本过低时硬性拦截，拒绝启动
  ├── migrateAutoUpdatesToSettings() → 一次性配置迁移
  └── checkForReleaseNotes() → 展示新版本的更新日志

REPL 运行中（每 30 分钟）
  ├── AutoUpdaterWrapper 检测安装类型
  │
  ├── native → NativeAutoUpdater
  │     ├── 从 GCS/Artifactory 获取版本
  │     ├── 检查最大版本上限（服务端控制）
  │     ├── 检查 minimumVersion 设置（跳过）
  │     ├── acquireLock()
  │     ├── downloadAndVerifyBinary()（SHA256 校验，3 次重试）
  │     ├── 安装到 versions/ 目录
  │     ├── 更新符号链接
  │     └── cleanupOldVersions()（保留 2 个版本）
  │
  ├── npm-global/local → AutoUpdater
  │     ├── 从 npm registry 获取最新版本
  │     ├── semver 版本比较
  │     ├── acquireLock()
  │     └── npm install -g / 本地安装
  │
  └── package-manager → PackageManagerAutoUpdater
        ├── 从 GCS 获取版本
        └── 显示 "Run: brew upgrade ..."（不自动安装）

手动操作
  └── claude update → 完整诊断 + 安装编排