结论先说
- 绝不要第一句就让它直接改代码:先用
claude --permission-mode plan(或按Shift+Tab切到 Plan 模式)只读扫描锁文件和废弃语法,输出分步升级清单后再审批动手。 - 严格按「基线测试 → 升运行时与依赖 → 批量修废弃 API → 回归验证」四阶段推进:每完成一阶段提交一次 Git,改坏随时回退。
- 把编译器和单元测试报错当导航仪:切到新版本环境后,让 Claude Code 直接运行构建与测试命令,盯着真实报错逐批清零,比纯靠静态阅读准确得多。
- 阶段之间主动
/clear或/compact腾出上下文:避免几千行npm install或pytest安装日志塞满窗口导致后续修改漏改。 - 长链路重构提前备足订阅额度:跨几十个文件的循环跑测与修复很吃配额,国内开发者可通过本站 Claude Code 订阅专区 或 Claude Max 订阅服务 免外币卡开通升级。

图:本站根据 Claude Code 官方文档:Common workflows 整理的示意图
本文根据 Claude Code 官方文档《Common workflows》《Permission modes》《CLI reference》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。
适用于谁
- 需要把老项目从 Node.js 16/18 升到 22 LTS,或从 Python 3.8/3.9 升到 3.12+ 的开发者;
- 升级运行时后遇到一堆依赖不兼容、C++ 原生模块编译失败或废弃 API(Deprecation)报错的人;
- 想用 Claude Code 批量修报错,又怕它一次性乱改几十个业务文件无法回滚的团队。
一、第一阶段:建隔离分支并用 Plan 模式盘点风险
大版本升级最怕改到一半进退两难。动手前先切出独立分支(或用 claude --worktree 启动独立工作树),再以只读规划模式启动会话:
bash
git checkout -b chore/upgrade-runtime
claude --permission-mode plan
进入会话后,复制下面这段盘点提示词,让模型先做静态体检而不碰任何磁盘文件(Plan 模式的详细用法见 Claude Code Plan 模式怎么用):
text
请先只读检查当前仓库,准备从 Node 18 升级到 Node 22 LTS(或从 Python 3.9 升级到 Python 3.12):
1. 读取 package.json / pyproject.toml、锁文件、Dockerfile 与 .github/workflows 里的版本声明;
2. 列出明确不兼容目标大版本的核心依赖及最低可升版本;
3. 搜索代码库中目标版本已移除或废弃的内置 API(如 Node 的 Buffer 构造器、url.parse,或 Python 的 distutils、asyncio 旧写法、typing 旧注解);
4. 按「改环境配置 → 升基础库 → 改业务代码」给出分步执行顺序,先不要修改任何文件。
拿到清单后重点核对两点:有没有已停更且无替代品的底层库,以及构建脚本和容器镜像版本号是否漏列。
二、第二阶段:切换本地运行时并分层更新依赖
确认方案可行后,先在本机用 nvm、fnm、pyenv 或 uv 切到目标大版本运行时,再按 Shift+Tab 退出只读模式,让 Claude Code 先改版本声明文件并重装依赖:
text
现在进入第 1 步:请只修改环境声明与依赖版本文件(package.json / pyproject.toml / Dockerfile / CI 配置),暂时不要动 src 下的业务代码。优先将不兼容依赖升到兼容当前运行时的最小跨度版本,执行安装并汇报报错。
这里有一个关键原则:不要顺手把所有无关业务框架全升到最新版。例如升 Node 22 时,若老版 Express 仍兼容就先不动,把变量控制在运行时本身;等主干跑通后再单独开 PR 升业务框架。
订阅与账号准备提示:老项目升级依赖与多轮跑测需要高频消耗上下文窗口。若遇到 Pro 额度见底触发限流、又没有境外信用卡升级套餐,可在本站选购 Claude Pro iOS 免上号自助卡密(无需提供密码)或升级更高倍率的 Claude Max 套餐。
三、第三阶段:按模块批量替换废弃 API 与语法报错
依赖装通后,往往会冒出几十处废弃 API 警告或运行时崩溃。此时先执行一次 /compact 清理掉冗长的依赖安装日志,再把修复任务按目录或报错类型喂给模型:
text
依赖已装好。请运行测试套件(npm test 或 pytest -q --tb=short),按报错类型分批修复:
1. 每次只修同一类废弃 API(例如统一替换 datetime.utcnow() 为带时区的 datetime.now(timezone.utc),或替换废弃的 fs.rmdir 递归调用);
2. 请不要修改业务逻辑返回值与对外接口签名;
3. 每修完一类就重跑对应测试文件验证,通过后停下来让我确认 git diff。
如果要允许模型连续运行本地测试而不必每次手点确认,可在会话内配置测试命令白名单,具体配法见 Claude Code 权限模式详解。每修绿一类报错,立即提交一次小颗粒度 Commit(提交与冲突处理见 Claude Code 写 Git 提交、开 PR、解决合并冲突)。
四、升级卡壳时的排错对照表

图:本站根据 Claude Code 官方文档:Common workflows 与排错实践整理的示意图
遇到棘手报错时,对照下表处理比让模型盲目重试更省配额:
| 常见卡点现象 | 根因定位 | 给 Claude Code 的处理指令 |
|---|---|---|
原生模块报 node-gyp 或 C 扩展编译失败 | 旧版二进制包未提供新运行时预编译轮子 | 让它查该包最新维护版或纯 JS/Python 替代包,勿硬改系统编译器 |
| 锁文件报 Peer Dependency 版本死锁 | 两个插件依赖了冲突的次级库版本 | 让它读取依赖树(npm ls 或 uv tree),列出需同步小幅升级的配套插件 |
测试全绿但启动报 DeprecationWarning | 旧写法尚未彻底移除但下个大版本会崩 | 把警告栈贴入对话,加上 --throw-deprecation 或 PYTHONWARNINGS=error 逐个修净 |
| 单次对话越改越乱、反复改回旧写法 | 上下文混入过多失败尝试 | 执行 git checkout -- . 回退当前未提交改动,/clear 清空会话后只喂单个目录重来 |
常见问题
问:能不能让 Claude Code 一次性把 Node 版本和 Webpack、React 全升到最新?
答:不建议。运行时升级和构建框架升级混在一起时,报错堆栈会互相掩盖,模型很容易为了消掉报错去乱删配置。拆成两个独立分支依次推进最稳妥。
问:升级前老项目本身就没有单元测试怎么办?
答:在第一阶段切换版本前,先让 Claude Code 在旧运行时下为核心接口和工具函数补写最小冒烟测试并跑通,以此作为升级后的回归对比基线。
问:升级过程中忘了切分支就把主分支改乱了怎么救?
答:先不要关闭终端,可以让 Claude Code 执行 git stash 再 git checkout -b 挪到新分支,或者按双击 Esc 使用会话检查点回退最近几步文件编辑。入门命令说明见 Claude Code 中文入门教程。
问:国内没有外币卡,或团队采购 Claude Code 升级老项目需要开增值税发票怎么办理?
答:可通过本站 AI 会员充值总览 或 Claude Code 订阅页 下单,支持支付宝、微信支付及 AlipayHK,提供免交密码的自助卡密兑换,并支持申请国内报销用的增值税发票。实时价格以页面展示为准;订阅期内若掉订阅按剩余天数折退,因违反官方条款导致的封号不在质保范围内。
相关教程
- Claude Code Plan 模式怎么用:先出方案再改代码
- Claude Code 权限模式详解:auto、手动、plan、bypass 与权限规则配置
- Claude Code 写 Git 提交、开 PR、解决合并冲突:gh 命令、attribution 设置和回退办法
- Claude Code 中文入门教程(2026):安装、登录、第一个任务、常用命令
参考资料
- Claude Code 官方文档:Common workflows — https://code.claude.com/docs/en/common-workflows
- Claude Code 官方文档:Permission modes — https://code.claude.com/docs/en/permission-modes
- Claude Code 官方文档:CLI reference — https://code.claude.com/docs/en/cli-reference
0 条评论
还没有评论,来抢沙发~