企业官网建设流程全解析

OpenCode 实战升级全记录：从0.1.x迁移到最新版一次搞定

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode

旧版 opencode 用了半年，现在要升到最新版，却不确定配置文件、安装路径、权限声明是否要动。本文给出一条完整的升级路径：卸载、重装、配置迁移、回滚预案和自检表一次讲清，照做即可在十分钟内完成切换。

一、改动速览

官方 README 中有明确提示："Remove versions older than 0.1.x before installing."——出处：本仓库 README。

二、动手前清单

• 确认当前安装方式（脚本 / npm / brew）——卸载命令按方式区分
• 记录当前版本号——回滚时要装回这个版本
• 备份全局配置目录~/.config/opencode/——这是恢复点
• 备份项目根目录的opencode.json（如有）——这是恢复点
• 确认没有正在跑的长会话——避免迁移期间写入冲突

三、核心操作

3.1 执行前：记录状态，完成备份

先确认版本和二进制位置，再做备份。下面三条命令分别完成这三件事：

opencode --version which opencode BACKUP_DIR=~/opencode-backup-$(date +%Y%m%d) && mkdir -p "$BACKUP_DIR" && cp -r ~/.config/opencode "$BACKUP_DIR/config" && cp ./opencode.json "$BACKUP_DIR/opencode.json" 2>/dev/null; true

备份目录是回滚预案的落脚点。自检通过之前不要删除。

3.2 执行中：卸载、重装、迁移配置

卸载命令按安装方式三选一：

# npm/pnpm/yarn 用户 npm uninstall -g opencode-ai # brew 用户 brew uninstall opencode # 安装脚本用户（默认安装位置为 ~/.opencode/bin） rm -f ~/.opencode/bin/opencode

用官方安装脚本重装，默认装到~/.opencode/bin，脚本也支持用-v锁定版本：

curl -fsSL https://opencode.ai/install | bash # 需要锁定版本时 curl -fsSL https://opencode.ai/install | bash -s -- -v 1.0.180

处理配置：若旧文件名是config.json，改名为opencode.json；删掉不再被读取的顶层theme、keybinds、tui字段（归一化逻辑见源码packages/opencode/src/config/config.ts）。与升级直接相关的字段保留成这样即可：

{ "model": "anthropic/claude-sonnet-4", "permission": { "edit": "ask", "bash": "allow", "webfetch": "deny" } }

最后运行内置迁移命令，确认没有遗留的 v1 数据待转换：

opencode migrate

预期输出No migrations to run.。若提示有待迁移项，按提示完成后重跑一次确认清零。

3.3 执行后：启动验证

打开新终端，启动 TUI，确认版本号与界面渲染正常。

本阶段产出：一个新版本号、一个无报错的 TUI、一份符合新格式的配置。

四、回滚预案 ⚠️

出现以下任一情况，停止前进，执行回滚：

• which opencode仍指向旧路径，重装未生效
• TUI 启动报配置错误，且五分钟内无法定位
• opencode migrate执行失败且报错无法理解

恢复路径：

# 装回 3.1 记录的旧版本 curl -fsSL https://opencode.ai/install | bash -s -- -v <旧版本号> # 从备份还原配置 cp "$BACKUP_DIR/config/opencode.json" ~/.config/opencode/opencode.json

还原后再跑一次opencode --version，确认输出了旧版本号，回滚才算完成。

五、自检

六、FAQ

症状：opencode: command not found原因：shell 的 PATH 缓存仍指向已删除的旧二进制。解决：执行hash -r刷新缓存，或开一个新终端；仍找不到则检查~/.opencode/bin是否在 PATH 中。

症状：主题、键位不生效原因：opencode.json顶层的theme、keybinds字段已被新版忽略。解决：删掉这些字段，到 tui 配置里重新设置；归一化逻辑在packages/opencode/src/config/config.ts。

症状：提示模型不存在或启动回退原因：模型字段是裸名字，不是provider/model格式。解决：改成provider/model形式，例如anthropic/claude-sonnet-4。

七、收尾

升级的稳妥之处在于每一步都留了退路：先备份、记版本、装完再动配置，备份目录在自检全部通过前都不删。执行时先跑opencode migrate，再逐项走完自检表，最后才处理旧备份。更多配置项说明见官方文档：opencode.ai/docs。

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode