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 的情况)
验证:
关于版本号
@opencode/cli的正式版走2.x线,与 Homebrew 的opencode-v2是同一条版本线(同一份二进制,只是分发渠道不同)- 官方 dist-tags:
| tag | 用途 |
|---|---|
latest |
稳定正式版,生产用这个 |
beta |
预发布版 |
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 遗留的插件缓存(可选,纯腾空间):
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 进程,尤其是 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 导入失败并重试:
回滚原则
如果迁移失败:
- 停止 v2 的所有进程;
- 保留 v2 生成的日志和任何
opencode-next.db,便于诊断; - 用备份中的
opencode.db、opencode.db-wal、opencode.db-shm恢复原数据; - 再恢复旧版 CLI,确认 Session 可见后再处理迁移问题。
不要在 v2 仍运行时覆盖数据库,也不要删除原始备份。
五、升级后必做的验证
# 1. 版本正确
opencode --version
# 2. 命令可用
opencode --help
# 3. 用真实项目跑一次(放一个你自己的项目路径)
cd /path/to/your/project
opencode run "列出当前目录的文件"
三条都过,升级才算完成。第 3 条尤其重要——它能一次性验证配置解析、provider 鉴权、模型调用是否都正常。
六、已知注意事项
-
Node 版本:
@opencode/cli的package.json未声明engines字段,即没有硬性 Node 版本下限。但包内带postinstall脚本(node ./postinstall.mjs)安装后落位平台二进制,建议 Node ≥ 18、npm ≥ 9。升级 npm 前建议先node --version看一眼。 -
二进制按平台分发:安装时 npm 会通过
optionalDependencies拉取对应平台的包,例如: @opencode/cli-linux-x64@opencode/cli-linux-arm64@opencode/cli-linux-x64-musl(Alpine 等 musl 发行版)@opencode/cli-linux-x64-baseline(老 CPU 指令集降级版)
若你的机器是 Alpine 或老 CPU,npm 会自动匹配;匹配失败时安装会报错,届时对照上表确认平台标签。
-
两个可执行名:包同时提供
opencode和opencode2两个 bin 名,指向同一个二进制。如果机器上还留着 Homebrew 版的opencode,会互相覆盖 PATH——同一个 shell 里只应存在一种安装方式。 -
postinstall被跳过的情况:某些环境(如npm ci --ignore-scripts)会跳过 postinstall,导致二进制没落位、命令不可用。若装完opencode命令不存在,检查是否禁用了脚本: -
权限问题:若
npm install -g报 EACCES,说明全局目录需要 root。推荐用 nvm / fnm 等版本管理器,或配置用户级 prefix,不建议直接sudo npm install -g(会把文件 owner 变成 root,后续升级又出问题):
七、回滚
npm 安装没有自动回滚,需要手动指定旧版本:
# 查看可用版本
npm view @opencode/cli versions --json | tail -20
# 装回指定版本
npm install -g @opencode/cli@2.0.15
回滚后配置如有改动,从备份恢复:
八、速查
# 升级到最新稳定版
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