Wiki AI

OpenCode 升级机制（opencode upgrade 源码分析）

8分钟阅读

opencode upgrade 的源码级分析，覆盖手动升级、TUI 启动时的自动检测两条路径，及各安装方式（curl/npm/brew/scoop/choco）的具体升级动作。基于源码目录 /Users/zhaoweiguo/6ai/opensources/opencode 整理。

入口与调用链

两条触发路径共用同一套底层升级逻辑 Installation（packages/opencode/src/installation/index.ts）：

  • 手动：opencode upgrade → packages/opencode/src/cli/cmd/upgrade.ts，注册于 index.ts:91
  • 自动：TUI 启动 1 秒后由 cli/cmd/tui.ts:266 触发 client.call("checkUpgrade") → cli/tui/worker.ts:59 → cli/upgrade.ts
  • HTTP API（供桌面端/远程 TUI 触发）：server/routes/instance/httpapi/handlers/global.ts:97-146
  • curl 安装方式最终执行仓库根目录的 install 脚本（对外通过 https://opencode.ai/install 提供）
CLI手动: index.ts → cli/cmd/upgrade.ts
TUI自动: tui.ts:266 → worker.ts:59 checkUpgrade() → cli/upgrade.ts upgrade()
              ↓ (两者汇合)
      Installation.method()   检测安装方式
              ↓
      Installation.latest()   查询最新版本
              ↓
      Installation.upgrade()  执行升级命令
              ↓
   emit installation.updated / update-available

版本比较

版本号来自编译期注入的常量 InstallationVersion（packages/core/src/installation/version.ts，未注入时为 "local"）。用 semver 判断发布类型：

// installation/index.ts:24-33
export function getReleaseType(current: string, latest: string): ReleaseType {
  if (newMajor > currMajor) return "major"
  if (newMinor > currMinor) return "minor"
  return "patch"
}

检测安装方式

Installation.method()（installation/index.ts:174-207）：

  1. execPath 含 .opencode/bin 或 .local/bin → 判定为 curl 安装
  2. 否则依次探测 npm list -g / yarn global list / pnpm list -g / bun pm ls -g / brew list --formula opencode / scoop list opencode / choco list opencode
  3. 均未命中 → unknown

查询最新版本

Installation.latest()（installation/index.ts:208-264），按安装方式选不同版本源：

安装方式版本来源
brew（自定义 tap）brew info --json=v2 本地查询
brew（官方）https://formulae.brew.sh/api/formula/opencode.json
npm/pnpm/bunnpm registry（NpmConfig.registry() 读取本地配置，默认 registry.npmjs.org），包名 opencode-ai
chocoChocolatey 社区 OData API
scoopGitHub ScoopInstaller/Main bucket 的 opencode.json manifest
curl / 默认GitHub API repos/anomalyco/opencode/releases/latest

执行升级

Installation.upgrade(method, target)（installation/index.ts:265-321），按 method 分支执行，无统一抽象，每种方式硬编码在各自 case：

方式执行命令
curl下载 https://opencode.ai/install，管道给 bash（降级 sh），带 VERSION=target 环境变量
npm/pnpm/bun{npm|pnpm|bun} install -g opencode-ai@{target}
brew自定义 tap 先 git pull --ff-only，再 brew upgrade {formula}（HOMEBREW_NO_AUTO_UPDATE=1）
chocochoco upgrade opencode --version={target} -y（需管理员权限）
scoopscoop install opencode@{target}

执行完检查退出码，非 0 抛 UpgradeFailedError；成功则跑一次 {execPath} --version 做确认。

curl 安装脚本细节（仓库根目录 install）

  • 检测 OS（darwin/linux/windows）、架构（x64/arm64，Mac Rosetta 强制识别为 arm64）、CPU 是否支持 AVX2（否则用 -baseline 变体）、是否 musl libc（Alpine，用 -musl 变体），拼出下载文件名如 opencode-linux-x64.tar.gz
  • check_version() 短路：当前版本已等于目标版本，直接打印提示 exit 0，跳过下载
  • download_and_install()：curl 下载压缩包 → Linux 用 tar -xzf/其他用 unzip 解压 → mv 覆盖到 $HOME/.opencode/bin/opencode → chmod 755 → rm -rf 清理临时目录
  • 支持 --binary <path> 跳过下载，直接 cp 本地二进制覆盖安装
  • 安装后尝试把 $INSTALL_DIR 写入 shell rc 文件（.zshrc/.bashrc/fish config），不可写则打印手动添加提示

关键设计缺陷：无回滚/备份

无论 TS 侧还是 install 脚本，都没有备份旧二进制或失败回滚逻辑 — 全程直接 mv/cp 覆盖 $INSTALL_DIR/opencode。升级失败时只返回 UpgradeFailedError，若旧文件已被覆盖则无法恢复。这是相较于 how-claude-code-works 等工具值得对比的一个薄弱点。

特殊情况处理

  • 已是最新版本：CLI 命令、自动升级路径、install 脚本三处均有独立短路判断，版本相同直接退出不执行升级
  • 安装方式 unknown：自动路径直接放弃；CLI 命令提示用户可能被包管理器托管，询问是否强装；HTTP API 返回 400
  • 权限不足：仅对 choco 做了专门识别（upgradeFailure() 硬编码提示需管理员权限运行终端），其他方式的权限问题只是原样抛出子进程 stderr
  • 网络失败：自动升级路径 .catch(() => {}) 静默失败，不升级；CLI 手动命令未捕获，会直接抛未处理异常（潜在健壁性问题）；子进程探测统一用 Effect.catch 兜底空结果，避免单个探测失败拖垮整体检测
  • 配置层禁用：config.autoupdate === false 或环境变量 OPENCODE_DISABLE_AUTOUPDATE 跳过自动升级；autoupdate === "notify" 只发通知事件、不自动执行；OPENCODE_ALWAYS_NOTIFY_UPDATE 用于强制走通知分支调试（packages/core/src/flag/flag.ts）

TUI 交互

packages/tui/src/app.tsx:1031-1077 监听 installation.update-available 事件，弹出确认对话框；用户确认则调用 HTTP API /global/upgrade，成功后提示重启并退出；用户跳过则把版本号记入本地 kv（skipped_version），避免重复打扰同一版本。

Windows 平台专项

Windows 下 opencode 不会自替换 .exe，而是依赖安装它的包管理器执行升级。原生 Windows（PowerShell/cmd）环境下的典型路径：

支持的安装方式与升级命令

安装方式探测命令升级执行命令备注
chocochoco list --limit-output opencodechoco upgrade opencode --version={target} -y必须在管理员终端运行，否则失败并提示 “not running from an elevated command shell”，CLI 会提示 “Please run the terminal as Administrator and try again”
scoopscoop list opencodescoop install opencode@{target}注意代码用 install 而非 scoop update；想用 scoop 原生方式可直接 scoop update opencode
npm/pnpm/bunnpm list -g --depth=0 等`{npmpnpm

curl / install 脚本路径在原生 Windows 基本不走

curl 方式会重新拉 https://opencode.ai/install 并管道给 bash/sh 执行。原生 PowerShell/cmd 无自带 bash，故此路径在 Windows 上基本不走；仅在 MSYS2/Git Bash 等 Bash 环境下，install 脚本会识别 MINGW*|MSYS*|CYGWIN* → os=windows，下载 windows-x64.zip 并解压覆盖。

AVX2 baseline 探测（install 脚本）

x64 架构下 install 脚本通过 PowerShell 调 kernel32!IsProcessorFeaturePresent(40) 判断 CPU 是否支持 AVX2，不支持则下载 -baseline 变体（install:144-156）：

powershell.exe -NoProfile -NonInteractive -Command "(Add-Type ... IsProcessorFeaturePresent(40))"

探测结果非 true/1（去空白/大小写后）→ 用 -baseline 变体。

用户侧实操速查

  • 手动升级：opencode upgrade（自动检测方式），或显式指定 opencode upgrade --method choco / --method scoop
  • choco 用户升级前以管理员身份打开终端，否则必失败
  • scoop 用户：opencode upgrade 内部执行 scoop install opencode@<版本>；也可直接 scoop update opencode
  • 关闭自动升级：config 设 autoupdate: false，或环境变量 OPENCODE_DISABLE_AUTOUPDATE=1
  • 只要通知不自动装：autoupdate: "notify" 或 OPENCODE_ALWAYS_NOTIFY_UPDATE=1

关联

  • CLI与命令 — upgrade 命令在完整命令列表中的位置
  • GitHub仓库信息 — install 脚本与发布渠道背景
  • 配置系统 — autoupdate 配置项所属的配置体系
  • 打包与签名 — 发布产物的构建、签名与分发链路（本页分析的升级路径的上游）

来源

源码分析：/Users/zhaoweiguo/6ai/opensources/opencode（packages/opencode/src/installation/index.ts、packages/opencode/src/cli/、仓库根目录 install 脚本、packages/tui/src/app.tsx）。整理：赵卫国 2026-07-24。

关系图谱

反向链接