OpenCode 2 升级指南：从 v1 平滑迁移不踩坑

开源 AI 编程终端 OpenCode 迎来了大版本跨越。OpenCode 1.19.0 中新增的 opencode upgrade --major 命令，为从 v1 迁移到 OpenCode 2 提供了一条官方通道。但大版本升级从来不是敲一行命令就完事——官方迁移指南明确列出了哪些东西会坏、哪些能带走，以及一套可以照着执行的"周一安全清单"。

升级入口：一条命令背后的取舍

opencode upgrade --major 的定位很明确：让 v1 用户不必手动重装、不必翻文档逐条比对配置，就能跨过主版本号。这条命令降低了"要不要升"的心理门槛，但它解决的是安装层面的问题，不是兼容层面的问题。

真正决定升级体验的，是你的配置里用了多少依赖旧接口的东西。官方迁移指南把重点放在三块：插件、服务器 API、TUI 配置。这三者恰好是 OpenCode 从"个人终端工具"走向"可扩展平台"过程中改动最大的部分。

如果你的用法很朴素——打开终端、对话、改代码——升级大概率无感。但只要碰过插件开发、写过自动化脚本调用 server API、或者深度定制过 TUI 界面，就需要按清单逐项检查。

什么是 TUI 配置？ TUI（Text-based User Interface，文本用户界面）指完全运行在终端里的交互界面，OpenCode 的对话窗口、快捷键、状态栏布局都属于 TUI 范畴。TUI 配置通常是一个独立的配置文件（如 tui.toml 或 keybindings.json），用来定义按键映射、主题配色、面板布局等。之所以在大版本升级中容易出问题，是因为 TUI 配置项与内部组件结构强耦合：一旦 v2 重写了界面渲染层或引入了新的状态管理方式，v1 的配置字段就可能被重命名、合并或直接废弃。实践中，升级后最典型的现象是快捷键失灵、界面回退到默认主题、或启动时提示未知配置项。处理办法不是逐字段猜测，而是对照 v2 的配置 schema 重新生成一份最小配置，再逐项加回自定义内容。

会坏的、能带走的：迁移指南的核心结论

官方指南给出的分类很干脆，没有模棱两可的"可能受影响"。

确定会破坏的部分：

• 插件：插件接口在 v2 中发生了不兼容变更，依赖 v1 插件 API 的扩展需要按新规范改写。
• 服务器 API：server API 的调整会直接影响所有通过 HTTP 或本地端口调用 OpenCode 的自动化流程。
• TUI 配置：终端界面的配置文件结构有变，旧配置项可能被忽略或报错。

能够平滑带走的：

• 核心的项目上下文与工作目录配置
• 基础的模型与 provider 设置
• 日常对话历史与常规使用习惯

这个划分透露出一个信号：OpenCode 2 在"平台能力"层面做了重构，但尽量保住了"日常使用"层面的连续性。对绝大多数普通用户来说，迁移成本主要集中在配置文件的适配，而不是使用方式的重新学习。

server API 是什么，为什么它比插件更容易被忽略？ OpenCode 的 server API 是一组本地 HTTP 接口，允许外部程序通过端口调用 OpenCode 的能力，比如让编辑器插件、CI 脚本或自建面板触发代码补全、查询会话状态。它和插件接口的区别在于：插件跑在 OpenCode 进程内部，而 server API 是跨进程通信，调用方可能是任何语言写的脚本。正因如此，server API 的破坏性变更往往不会在“打开终端用一用”时暴露，而是在某条自动化流水线突然报 404 或参数错误时才被发现。迁移时建议先搜索代码库里所有指向 OpenCode 端口的请求，核对路径前缀、认证方式和请求体字段是否与 v2 文档一致，尤其注意那些靠字符串拼接 URL 的旧脚本。

周一安全清单：把升级变成可控操作

迁移指南推荐的安全流程，本质上是一套降低回滚成本的实践。按顺序执行，可以把"升级翻车"的概率压到很低。

第一步：备份配置目录。 在跑 opencode upgrade --major 之前，把整个配置文件夹复制一份。这是所有后续步骤的前提——有了备份，任何一步出错都能退回原点。

第二步：在非关键项目上试跑。 不要拿主力项目当小白鼠。找一个边缘仓库、或者临时克隆一份代码，先验证升级后的基本功能是否正常。

第三步：逐项检查三类破坏点。 打开你的插件目录、自动化脚本、TUI 配置文件，对照迁移指南逐条确认。插件看接口签名有没有变，脚本看调用的 API 路径和参数有没有调整，TUI 配置看有没有被废弃的字段。

第四步：确认无碍后再升级主力环境。 前两步都通过后，再对日常工作环境执行升级。此时你已经有了备份、有了验证结果，出问题的可能性已经很低。

第五步：保留旧版本路径一段时间。 即使升级成功，也建议让 v1 的可执行文件在 PATH 中多留几天，作为应急退路。

这套流程没有技术含量，但恰恰是很多人跳过的部分。大版本升级的事故，往往不是因为变化本身有多复杂，而是因为用户在没有退路的情况下直接在主环境上操作。

为什么“保留旧版本路径”是清单里最容易被低估的一步？ 在 Unix 类系统里，PATH 环境变量决定了终端优先调用哪个可执行文件。升级到 v2 后，如果 v1 的二进制文件仍留在原路径，只是不在 PATH 最前面，就可以在出问题时临时用绝对路径或调整 PATH 顺序回退，而不必重新下载安装。更稳妥的做法是把 v1 可执行文件重命名备份（如 opencode-v1），并在 shell 配置里加一个临时别名。几天后确认插件和工作流都稳定，再清理旧文件。这一步的价值不在于“一定会用上”，而在于它把升级从不可逆操作变成了可逆操作，从而降低试错的心理成本。

这次升级值得吗

从迁移指南的措辞能读出官方的判断：v2 的重构是为了支撑插件生态和外部集成，而不是为了改而改。如果你正在用 OpenCode 做插件开发、或者把它接入自己的工具链，v2 提供的接口稳定性提升是实打实的收益。

反过来，如果你只是把它当日常编程助手用，升级的动力就没那么急迫。可以先观察一段时间，等社区把插件适配的坑趟平了再跟进。

无论哪种情况，opencode upgrade --major 把升级的"动作"简化了，但"决策"依然在用户手里——先备份、先试跑、先检查，再动手。这三条原则适用于 OpenCode 2，也适用于所有大版本迁移。