跳转至

OpenCode v2 npm 安装方式升级指南

适用于通过 npm 全局安装 OpenCode 的 Linux 机器。


一、确认当前安装方式

升级前先确认装的是什么、装在哪:

# 看全局安装了哪些 opencode 相关包
npm ls -g --depth=0 | grep -i opencode

# 看实际生效的可执行文件位置和版本
which opencode
opencode --version

# 看 npm 全局 bin 目录(升级后新版会落在这里)
npm config get prefix

判断依据

输出 含义 该走哪条路
@opencode/cli v2(正确包名) 本文档,直接升级
opencode-ai v1(旧包) 先卸载,再装 @opencode/cli
opencode-v2 第三方无关包 卸载,再装 @opencode/cli

⚠️ 包名务必记准:v2 的官方 npm 包是 @opencode/cli(不带 -ai 后缀)。 容易混淆的坑: - @opencode-ai/cli — 另一个包,只有 0.0.0-beta 预发布版,不是正式版 - opencode — npm 上根本不存在(404) - opencode-ai — 是 v1 的旧包,latest 停在 1.x


二、升级(已装 @opencode/cli 的情况)

npm install -g @opencode/cli@latest

验证:

opencode --version

关于版本号

  • @opencode/cli 的正式版走 2.x 线,与 Homebrew 的 opencode-v2 是同一条版本线(同一份二进制,只是分发渠道不同)
  • 官方 dist-tags:
tag 用途
latest 稳定正式版,生产用这个
beta 预发布版
dev 每次提交构建的开发版

想尝鲜可以显式指定,但一般不建议:

npm install -g @opencode/cli@beta     # 预发布
npm install -g @opencode/cli@dev      # 开发版

三、从 v1(opencode-ai)迁移到 v2

v1 和 v2 是两个不同的包,不能原地 npm update 升上去,必须先卸载再装:

# 1. 卸载 v1
npm uninstall -g opencode-ai

# 2. 清掉残留(如果 which opencode 仍指向旧路径)
which opencode          # 确认没有残留
# 若有残留,手动删除那个软链接:
# rm -f <上一步输出的路径>

# 3. 安装 v2
npm install -g @opencode/cli@latest

# 4. 新开一个 shell 让 PATH 生效,再验证
hash -r
opencode --version

💡 hash -r 清掉 shell 的命令路径缓存,否则可能仍指向已删除的旧二进制。

配置兼容性

v1 的配置文件(~/.config/opencode/opencode.jsonc)v2 基本能直接读,但插件字段有变化:

  • v1 用 "plugin" 字段,v2 改为 "plugins"
  • v1 的插件实现(尤其是本地 TS 插件)在 v2 下无法运行,升级后需要移除或改写

检查并清理:

# 备份
cp ~/.config/opencode/opencode.jsonc \
   ~/.config/opencode/opencode.jsonc.pre-v2-$(date +%Y%m%d)

# 搜出插件引用
grep -n 'plugin' ~/.config/opencode/opencode.jsonc

如果确认不用旧插件,把 "plugin" 字段整段删掉即可;其余键(model / small_model / lsp / mcp / provider)保持不动。

同时清理 v1 遗留的插件缓存(可选,纯腾空间):

du -sh ~/.cache/opencode/ 2>/dev/null

v2 自己的数据在 ~/.local/share/opencode/,~/.cache/opencode/ 若是升级前遗留、且配置里无引用,可安全删除。


四、数据库与历史 Session 迁移

是否需要手动处理 DB?

不需要手动编辑、转换或导入数据库。 OpenCode v2 会在首次启动后台服务时自动执行 V1→V2 数据迁移和 schema migration。升级时不要删除、重命名或覆盖原数据库,也不要把旧数据库手动复制到新位置。

需要手动做的是:停服务并备份,不是改数据库。

OpenCode 的数据通常位于:

~/.local/share/opencode/opencode.db
~/.local/share/opencode/opencode.db-wal
~/.local/share/opencode/opencode.db-shm

如果当前版本支持,先用命令确认实际路径:

opencode debug paths db
opencode debug paths data
opencode debug paths config

升级前备份

必须先停止所有会访问数据库的 OpenCode 进程,尤其是 TUI、Web 服务和后台 service:

# 按实际部署方式执行;不存在的服务可以忽略
systemctl --user stop opencode-web.service 2>/dev/null || true
opencode service stop 2>/dev/null || true

# 确认没有残留进程
pgrep -a opencode || true

然后同时备份主数据库及 WAL/SHM 文件:

STAMP=$(date +%Y%m%d-%H%M%S)
BACKUP="$HOME/Backups/opencode-pre-v2-$STAMP"
DATA="$HOME/.local/share/opencode"

mkdir -p "$BACKUP/data"
cp -a "$DATA/opencode.db" "$BACKUP/data/"
cp -a "$DATA/opencode.db-wal" "$BACKUP/data/" 2>/dev/null || true
cp -a "$DATA/opencode.db-shm" "$BACKUP/data/" 2>/dev/null || true
cp -a "$HOME/.config/opencode" "$BACKUP/config" 2>/dev/null || true
chmod -R go-rwx "$BACKUP"

⚠️ 不要只备份 opencode.db。 如果 SQLite 处于 WAL 模式,尚未合并的数据可能在 opencode.db-wal 中;恢复时也要把 DB、WAL、SHM 作为一组处理。

Session 能否继承?

通常可以继承,但不是无条件保证。 只要以下条件不变,v2 会尝试导入并继续使用原有项目和历史 Session:

  • 使用同一个 Linux 用户;
  • $HOME、XDG_DATA_HOME、XDG_CONFIG_HOME 没有改变;
  • 使用同一个 OpenCode 数据目录;
  • 从原来的项目目录启动,项目路径没有被移动或改名。

首次启动后验证:

opencode service start
opencode service status
opencode session list --format json --max-count 20

cd /path/to/the/original/project
opencode

如果历史 Session 没有出现,不要马上删除或覆盖数据库。先检查:

opencode debug paths db
opencode api get /api/info

# 如果使用 systemd Web 服务
journalctl --user -u opencode-web.service -n 200 --no-pager

# OpenCode 日志目录
ls -lah ~/.local/share/opencode/log/

重点搜索这些关键词:V1Migration、opencode-next.db、SQLiteError、migration。

官方迁移指南保证的是配置文件和文件型定义(agents、commands、skills 等)的兼容,并没有承诺所有历史 Session 在任何旧数据库 schema 下都能 100% 无损迁移。已知问题示例:某些较旧的 opencode-next.db 缺少当前导入器预期的 nullable 列,可能导致 V1→V2 导入失败并重试:

回滚原则

如果迁移失败:

  1. 停止 v2 的所有进程;
  2. 保留 v2 生成的日志和任何 opencode-next.db,便于诊断;
  3. 用备份中的 opencode.db、opencode.db-wal、opencode.db-shm 恢复原数据;
  4. 再恢复旧版 CLI,确认 Session 可见后再处理迁移问题。

不要在 v2 仍运行时覆盖数据库,也不要删除原始备份。


五、升级后必做的验证

# 1. 版本正确
opencode --version

# 2. 命令可用
opencode --help

# 3. 用真实项目跑一次(放一个你自己的项目路径)
cd /path/to/your/project
opencode run "列出当前目录的文件"

三条都过,升级才算完成。第 3 条尤其重要——它能一次性验证配置解析、provider 鉴权、模型调用是否都正常。


六、已知注意事项

  1. Node 版本:@opencode/cli 的 package.json 未声明 engines 字段,即没有硬性 Node 版本下限。但包内带 postinstall 脚本(node ./postinstall.mjs)安装后落位平台二进制,建议 Node ≥ 18、npm ≥ 9。升级 npm 前建议先 node --version 看一眼。

  2. 二进制按平台分发:安装时 npm 会通过 optionalDependencies 拉取对应平台的包,例如:

  3. @opencode/cli-linux-x64
  4. @opencode/cli-linux-arm64
  5. @opencode/cli-linux-x64-musl(Alpine 等 musl 发行版)
  6. @opencode/cli-linux-x64-baseline(老 CPU 指令集降级版)

若你的机器是 Alpine 或老 CPU,npm 会自动匹配;匹配失败时安装会报错,届时对照上表确认平台标签。

  1. 两个可执行名:包同时提供 opencode 和 opencode2 两个 bin 名,指向同一个二进制。如果机器上还留着 Homebrew 版的 opencode,会互相覆盖 PATH——同一个 shell 里只应存在一种安装方式。

  2. postinstall 被跳过的情况:某些环境(如 npm ci --ignore-scripts)会跳过 postinstall,导致二进制没落位、命令不可用。若装完 opencode 命令不存在,检查是否禁用了脚本:

    npm config get ignore-scripts   # 应为 false
    

  3. 权限问题:若 npm install -g 报 EACCES,说明全局目录需要 root。推荐用 nvm / fnm 等版本管理器,或配置用户级 prefix,不建议直接 sudo npm install -g(会把文件 owner 变成 root,后续升级又出问题):

    npm config set prefix ~/.npm-global
    export PATH="$HOME/.npm-global/bin:$PATH"   # 写进 ~/.bashrc 或 ~/.zshrc
    


七、回滚

npm 安装没有自动回滚,需要手动指定旧版本:

# 查看可用版本
npm view @opencode/cli versions --json | tail -20

# 装回指定版本
npm install -g @opencode/[email protected]

回滚后配置如有改动,从备份恢复:

cp ~/.config/opencode/opencode.jsonc.pre-v2-20260925 \
   ~/.config/opencode/opencode.jsonc

八、速查

# 升级到最新稳定版
npm install -g @opencode/cli@latest

# 查看当前版本
opencode --version

# 查看 npm 上有哪些版本
npm view @opencode/cli versions --json

# 从 v1 迁移
npm uninstall -g opencode-ai && npm install -g @opencode/cli@latest

最后更新:2026-09-28 · 适用 @opencode/cli 2.x