wonder/cs-note
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault backup: 2026-06-09 23:15:17

Browse Source
This commit is contained in:
wonder
2026-06-09 23:15:17 +08:00
parent 31fd89aafe
commit e92c0327d9
111 changed files with 7276 additions and 8846 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude-code-best/docs/auto-updater.md
+80 -85
View File
@@ -1,12 +1,17 @@
---
tags: [claude-code, 自动更新, 安装, 版本管理, CLI]
create time: 2026-06-09 22:30
---
# 自动更新机制
## 概述
Claude Code 拥有一套复杂的多策略自动更新系统，支持三种安装方式、后台静默更新、手动 CLI 命令、服务端版本门控以及更新日志展示。系统设计目标是在最小用户干预下保持 CLI 最新，同时提供回滚和手动控制的兜底手段。
Claude Code 拥有一套多策略自动更新系统，支持三种安装方式（native、npm、包管理器）、后台静默更新、手动 CLI 命令、服务端版本门控以及更新日志展示。设计目标是在最小用户干预下保持 CLI 最新，同时提供回滚和手动控制的兜底手段。
---
## 正文
## 安装类型与更新策略
### 安装类型与更新策略
更新策略由安装方式决定，通过 `src/utils/doctorDiagnostic.ts` 检测：
@@ -18,17 +23,15 @@ Claude Code 拥有一套复杂的多策略自动更新系统，支持三种安
| `package-manager` | 显示通知，附带对应操作系统的升级命令 | 否（仅通知） |
| `development` | 不适用 — 执行 `claude update` 时报错 | 不适用 |
### 策略路由
#### 策略路由
`src/components/AutoUpdaterWrapper.tsx` — 挂载在 React/Ink UI 树中 — 检测安装类型并渲染对应的更新组件：
`src/components/AutoUpdaterWrapper.tsx` 挂载在 React/Ink UI 树中，检测安装类型并渲染对应的更新组件：
- `native` → `NativeAutoUpdater`（二进制下载 + 符号链接）
- `package-manager` → `PackageManagerAutoUpdater`（仅通知）
- 其他 → `AutoUpdater`（基于 JS/npm）
---
## 后台自动更新循环
### 后台自动更新循环
三个更新组件共享相同的轮询模式：
@@ -38,9 +41,10 @@ useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟
组件挂载时（即启动时）也会执行一次检查。
### 前置检查门控
#### 前置检查门控
任何更新尝试之前，系统会依次检查：
> [!tip] 更新前的三道关卡
> 任何更新尝试之前，系统会依次检查三个条件，全部通过才会执行更新。
1. **自动更新是否被禁用？** — `getAutoUpdaterDisabledReason()`（`src/utils/config.ts:1737`）
- `NODE_ENV === 'development'`
@@ -50,7 +54,7 @@ useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟
2. **最大版本上限？** — `getMaxVersion()`（`src/utils/autoUpdater.ts:108`）— 服务端熔断开关，防止更新到已知有问题的版本
3. **是否跳过该版本？** — `shouldSkipVersion()`（`src/utils/autoUpdater.ts:145`）— 尊重用户的 `minimumVersion` 设置，防止切换到 stable 频道时发生意外的版本降级
### Native 自动更新器（`src/components/NativeAutoUpdater.tsx`）
#### Native 自动更新器（`src/components/NativeAutoUpdater.tsx`）
1. 调用 `src/utils/nativeInstaller/installer.ts` 中的 `installLatest()`
2. 通过 `src/utils/nativeInstaller/download.ts` 下载二进制文件（GCS 或 Artifactory）
@@ -60,14 +64,14 @@ useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟
6. 保留最近 2 个版本，清理旧版本
7. 将错误分类上报分析（超时、校验和、权限、磁盘空间不足、npm、网络）
### JS/npm 自动更新器（`src/components/AutoUpdater.tsx`）
#### JS/npm 自动更新器（`src/components/AutoUpdater.tsx`）
1. 调用 `getLatestVersion()` 获取当前 npm dist-tag
2. 通过 semver `gte()` 比较版本
3. 根据安装类型路由到本地或全局安装
4. 使用文件锁（`acquireLock()` / `releaseLock()`）防止并发更新
### 包管理器通知器（`src/components/PackageManagerAutoUpdater.tsx`）
#### 包管理器通知器（`src/components/PackageManagerAutoUpdater.tsx`）
每 30 分钟通过 GCS 存储桶（非 npm）检查更新。**不会自动安装** — 仅显示对应操作系统的升级命令：
@@ -75,9 +79,7 @@ useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟
- Windows: `winget upgrade Anthropic.ClaudeCode`
- Alpine: `apk upgrade claude-code`
---
## 启动版本门控
### 启动版本门控
`src/utils/autoUpdater.ts:70` — `assertMinVersion()`
@@ -89,13 +91,13 @@ void assertMinVersion();
1. 从 GrowthBook 动态配置获取 `tengu_version_config`
2. 如果 `MACRO.VERSION < minVersion`，打印错误信息并调用 `gracefulShutdownSync(1)` — 强制用户更新
3. 这是一个**硬性门控** — 低于最低版本的 CLI 将无法启动
---
> [!warning] 硬性门控
> 低于最低版本的 CLI 将无法启动，这是一个不可绕过的强制更新机制。
## 手动 CLI 命令
### 手动 CLI 命令
### `claude update` / `claude upgrade`
#### `claude update` / `claude upgrade`
**文件**: `src/cli/update.ts`
@@ -110,25 +112,23 @@ void assertMinVersion();
- `npm-global` → 执行 `npm install -g`（含权限检查）
4. 报告当前版本、最新版本、成功/失败状态
### `claude rollback [target]`（仅限内部）
#### `claude rollback [target]`（仅限内部）
回滚到之前的版本。支持 `--list`、`--dry-run`、`--safe` 标志。
### `claude install [target]`
#### `claude install [target]`
安装或重新安装原生构建版本。接受可选的版本目标参数。
### `claude doctor`
#### `claude doctor`
检查自动更新器的健康状态，报告状态、权限和配置信息。
---
## 原生安装器架构
### 原生安装器架构
**文件**: `src/utils/nativeInstaller/installer.ts`
### 二进制文件存储布局
#### 二进制文件存储布局
```
~/.local/share/claude-code/
@@ -139,9 +139,10 @@ void assertMinVersion();
~/.local/bin/claude # 指向当前版本二进制文件的符号链接
```
Windows 系统使用文件复制而非符号链接。
> [!info] Windows 差异
> Windows 系统使用文件复制而非符号链接。
### 核心操作
#### 核心操作
| 函数 | 说明 |
|---|---|
@@ -151,7 +152,7 @@ Windows 系统使用文件复制而非符号链接。
| `lockCurrentVersion()` | 进程生命周期锁，防止正在运行的版本被删除 |
| `cleanupNpmInstallations()` | 迁移到原生安装时清理旧的 npm 安装 |
### 下载与校验
#### 下载与校验
**文件**: `src/utils/nativeInstaller/download.ts`
@@ -161,9 +162,7 @@ Windows 系统使用文件复制而非符号链接。
4. 60 秒卡顿检测（中止停滞的下载）
5. 失败时自动重试 3 次
---
## 文件锁机制
### 文件锁机制
**文件**: `src/utils/autoUpdater.ts:176-268`
@@ -174,11 +173,9 @@ Windows 系统使用文件复制而非符号链接。
- 进程将其 PID 写入锁文件
- `acquireLock()` 和 `releaseLock()` 同时被 JS/npm 和原生安装器使用
---
### 配置
## 配置
### 设置项
#### 设置项
**文件**: `src/utils/settings/types.ts`
@@ -187,7 +184,7 @@ Windows 系统使用文件复制而非符号链接。
| `autoUpdatesChannel` | `'latest' \| 'stable'` | 自动更新的发布频道 |
| `minimumVersion` | string | 最低版本要求，防止意外的版本降级 |
### 全局配置
#### 全局配置
**文件**: `src/utils/config.ts:191-193`
@@ -196,23 +193,19 @@ Windows 系统使用文件复制而非符号链接。
| `autoUpdates` | boolean | 启用/禁用自动更新（旧版） |
| `autoUpdatesProtectedForNative` | boolean | 原生安装始终自动更新 |
### 配置迁移
#### 配置迁移
**文件**: `src/migrations/migrateAutoUpdatesToSettings.ts`
一次性将旧版 `globalConfig.autoUpdates = false` 迁移为 settings 中的 `DISABLE_AUTOUPDATER=1` 环境变量。定义于 `src/migrations/migrateAutoUpdatesToSettings.ts`（当前未接入启动流程）。
---
## 更新通知去重
### 更新通知去重
**文件**: `src/hooks/useUpdateNotification.ts`
React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变更（major.minor.patch）只显示一次"重启以更新"消息，避免同一版本的重复通知。
---
## 更新日志
### 更新日志
**文件**: `src/utils/releaseNotes.ts`
@@ -222,9 +215,7 @@ React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变
4. 展示比 `lastReleaseNotesSeen` 更新的版本的更新日志
5. 使用 semver 比较确定需要展示哪些日志
---
## 版本比较
### 版本比较
**文件**: `src/utils/semver.ts`
@@ -232,9 +223,7 @@ React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变
- 在 Bun 环境下使用 `Bun.semver.order()`（快 20 倍）
- 在 Node.js 环境下回退到 npm `semver` 包
---
## 分析事件
### 分析事件
所有更新相关的遥测数据使用 `tengu_` 前缀的事件：
@@ -251,9 +240,7 @@ React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变
| 手动更新 | `tengu_update_check` |
| 迁移 | `tengu_migrate_autoupdates_to_settings`、`tengu_migrate_autoupdates_error` |
---
## 关键文件索引
### 关键文件索引
| 文件 | 职责 |
|---|---|
@@ -274,39 +261,47 @@ React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变
| `src/migrations/migrateAutoUpdatesToSettings.ts` | 旧版配置迁移 |
| `src/screens/Doctor.tsx` | Doctor 命令 UI，展示自动更新状态 |
---
### 流程图
## 流程图
```mermaid
graph TD
subgraph startup["启动阶段"]
A["assertMinVersion()"] -->|版本过低| B["硬性拦截，拒绝启动"]
C["migrateAutoUpdatesToSettings()"] --> D["一次性配置迁移"]
E["checkForReleaseNotes()"] --> F["展示新版本的更新日志"]
end
subgraph runtime["REPL 运行中（每 30 分钟）"]
G["AutoUpdaterWrapper 检测安装类型"]
G -->|native| H["NativeAutoUpdater"]
G -->|npm-global/local| I["AutoUpdater"]
G -->|package-manager| J["PackageManagerAutoUpdater"]
H --> H1["从 GCS/Artifactory 获取版本"]
H1 --> H2["检查最大版本上限（服务端控制）"]
H2 --> H3["检查 minimumVersion 设置（跳过）"]
H3 --> H4["acquireLock()"]
H4 --> H5["downloadAndVerifyBinary()（SHA256 校验，3 次重试）"]
H5 --> H6["安装到 versions/ 目录"]
H6 --> H7["更新符号链接"]
H7 --> H8["cleanupOldVersions()（保留 2 个版本）"]
I --> I1["从 npm registry 获取最新版本"]
I1 --> I2["semver 版本比较"]
I2 --> I3["acquireLock()"]
I3 --> I4["npm install -g / 本地安装"]
J --> J1["从 GCS 获取版本"]
J1 --> J2["显示升级命令（不自动安装）"]
end
subgraph manual["手动操作"]
K["claude update"] --> L["完整诊断 + 安装编排"]
end
```
启动阶段
├── 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 → 完整诊断 + 安装编排
```
- [[external-dependencies]] — 远程服务器依赖（GCS、npm registry 等）
- [[performance-reporter]] — 性能报告（更新过程的性能指标）
- [[telemetry-remote-config-audit]] — 遥测系统（更新事件上报）