hermes update 升级失败、卡住、升级后报错怎么办

升级前先留一条退路

升级最怕的从来不是失败本身,而是升到一半坏了、又退不回去。所以 `hermes update` 之前,先把当前这套能正常用的环境整体打包:

hermes version
hermes backup

`hermes version` 先记下当前版本号,出问题时好对照;`hermes backup` 把整个 Hermes home 打成一个 zip,`~/.hermes/config.yaml` 和 `~/.hermes/.env` 都在里面。这两条就是 `hermes update` 真正的后悔药:升级后只要发现新版本不对劲,用 `hermes import` 从这个 zip 整体退回升级前的状态,几分钟回到原样,配置、密钥、会话一个不丢。把"升级前先 backup"养成肌肉记忆,比升坏之后才满世界找办法划算太多。zip 按日期命个名,顺手挪到这台机器以外的地方更稳妥。

卡在下载:多半还是 GitHub 那一跳

`hermes update` 要从上游拉新版本,国内卡在这一步,和当初装的时候卡 install.sh 是同一类毛病——到 GitHub 这一跳不稳。先给当前终端配上你自己的代理,再重试:

export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890
hermes update

端口换成你本机代理实际的端口。这里有个常被忽略的因果:如果你当初是配了代理或镜像才把 Hermes 装上的,那升级同样需要这套网络条件,别指望裸连能成。判断是不是网络卡死也简单——同一时刻单独 curl 一下 GitHub 上任意一个文件,半天没反应,就先把网络治好,而不是对着 `hermes update` 反复重跑。重跑十遍,网络那跳不通,照样十遍都卡在原地。

升级后命令报错:先补非 Python 依赖

有一类问题长这样:`hermes update` 本身跑完了、没报错,但升级后用某些功能时报错,提示找不到 node、ripgrep、ffmpeg 或者浏览器。这不是升级坏了,而是新版本引入或更新了非 Python 依赖,本体升上去了、这些外部依赖没跟着补上。专门补一条命令就行,完全不必整体重装:

hermes postinstall
hermes doctor
hermes status

`hermes postinstall` 负责补装 node、浏览器、ripgrep、ffmpeg 这类非 Python 依赖;补完用 `hermes doctor` 把依赖检查再过一遍,确认缺的那项已经补齐;`hermes status` 看组件总览,确认整体回到就绪状态。顺序别反:先 postinstall 补一遍,再 doctor 看还缺不缺,比反过来先盯着缺什么再纠结要省事。这一类"升完才发现缺东西"的问题,十有八九用一次 postinstall 就解决了,根本轮不到重装。

想看升级到底出了什么岔:翻日志

如果升级过程不顺、又说不清卡在哪一步,别凭印象猜,直接看日志:

hermes logs
hermes status

`hermes logs` 负责查看和过滤日志文件,把升级前后那个时间窗的记录翻出来,失败原因、卡在哪个环节往往写得清清楚楚;`hermes status` 配合着看当前各组件还正不正常。一个口诀帮你分工:想知道"现在是什么状态"用 `hermes status`,想知道"刚才发生了什么"用 `hermes logs`,先看现状再回放过程。翻日志时只读出问题那几分钟的记录就够,从头读到尾是最浪费时间的走法。

真升坏了:用升级前那个 zip 整体回退

如果升级后行为明显不对、`hermes doctor` 一堆报错,而你又确实在升级前跑过 `hermes backup`,那就别耗着,直接回退:

hermes import
hermes version
hermes doctor

`hermes import` 从之前那个 zip 把整套环境恢复回去;`hermes version` 确认版本号退回到了升级前那个;`hermes doctor` 确认依赖恢复正常。回退不会丢配置和会话,因为它们本来就被一起打进了那个 home 目录的 zip 里。但回退之后别立刻原样再升一遍——先搞清上次为什么坏:是网络半路断了,还是依赖没补齐?把根因解决了再升,否则只是把同一个坑重踩一次。

别动不动就 uninstall 重装

升级一出问题,很多人第一反应是 `hermes uninstall` 卸掉重装一遍。这几乎总是性价比最低的选择,而且重装会把你的配置环境一起搅乱,没必要。把上面几步过一遍,你会发现绝大多数升级故障都落在三类里:网络没治好(配代理重试)、依赖没补齐(`postinstall`)、新版本不合用(`import` 回退)。这三类没有一类需要卸载重装来解决。真正该考虑重装的,只有一种极端情况——安装目录被改得乱七八糟、`doctor` 和 `import` 都救不回来,而你手头又没有可用的 backup zip。换句话说,重装是穷尽其他办法后的最后一招,不是遇到升级报错的第一反应。能定位的问题,靠定位解决,别靠重装碰运气;碰对了你也不知道为什么对,下次照样栽。

一句话把次序记牢:升级前 `backup` 留退路,卡下载先治网络,升完缺依赖跑 `postinstall`,说不清就翻 `logs`,真坏了用 `import` 回退,实在无解才轮到 `uninstall` 重装。每一步各管一段,按这个次序走,`hermes update` 出问题基本不会把你拖进反复重装的泥潭。

还没有真实场景？可以先领取 [Free Starter 模板包](/free-template-pack)，从低风险只读任务开始试跑。