注册
ChatGPTCodex

用 Codex 升级依赖、迁移框架版本：先盘点再分阶段，每一步都验证行为不变，附 4 段提示词

让 Codex 做框架或依赖迁移，最忌一句“帮我升级到最新版”。官方用例的做法是：先盘点旧栈的假设，再映射到新栈，分阶段落地，每个阶段跑最小验证。本文给 4 段提示词、分阶段清单和回滚前的检查。

NNathaniel bigo··原创首发·AI 辅助撰写
7 分钟读完
资料核对于 2026-11-05 · 依据官方文档与公开资料整理 Plus 账号
本文根据 Codex 官方用例《Run code migrations》《Upgrade your API integration》和《Prompting》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是软件截图。本站（bigolab.com）不是 OpenAI 官方网站。安装与配置见 /guides/codex-getting-started，本文只讲怎么交代升级任务。

适用于谁

  • 项目里的框架、运行时或依赖版本太旧，想升级又怕“一升就崩”的人；
  • 要把一个模块或整个项目迁移到新技术栈的人；
  • 以前让 AI 帮忙升级，结果一次改了几十个文件、分不清哪里出了问题的人。

结论先说

  1. 不要一步到位。 官方用例的原则是：用兼容层或检查点分阶段落地，而不是一次大重写。
  2. 先盘点，再动手。 让它先列出旧栈的假设：路由、数据模型、认证、配置、构建工具、测试、部署，以及必须保持不变的外部接口。
  3. 行为默认不变。 如果迁移本身会带来可见的变化，要求它事先明确列出这些例外。
  4. 每个阶段后跑最小验证并审查 diff。 可以是 lint、类型检查、聚焦的测试或冒烟测试。
  5. 换模型或 API 版本不只是改名字。 官方提醒：接口可能有变化，模型行为也不同，提示词要重新评估。

用 Codex 做迁移的流程：盘点、映射、分阶段落地、每阶段验证、审查再继续

图：本站根据 官方用例《Run code migrations》 整理的示意图

一、动手前先做的准备

  • 工作区干净。 官方《Prompting》在“委托重构”里提醒：先把当前工作提交或暂存，方便之后清楚地对比改动。
  • 测试能跑。 升级前先让现有测试跑一遍，记下失败的有哪些。否则升级后你分不清是旧问题还是新问题。写测试的做法见 /guides/codex-write-tests-and-run。
  • 读官方升级指南。 框架的破坏性变更以各自官方升级说明为准，把链接或要点贴给 Codex，比让它凭印象判断可靠。
  • 写进 AGENTS.md。 项目的构建命令、测试命令、不能动的目录，写在 AGENTS.md 里它每次都会读，见 /guides/codex-agents-md-how-it-reads。

二、4 段可以直接复制的提示词

方括号里是要你自己填的内容。

1. 先盘点，不改代码

我打算把这个项目从 [旧版本 / 旧技术栈] 升级到 [新版本 / 新技术栈]。请先只读不改：
1. 盘点迁移面：相关依赖、路由、数据访问、认证、配置、构建工具、测试、部署假设，以及必须保持不变的外部接口；
2. 把旧概念映射到新版本，指出哪些没有直接对应；
3. 列出你认为风险最高的 3 个地方，说明原因。
先不要修改任何文件。

2. 出分阶段计划

根据刚才的盘点，给出分阶段迁移计划：
- 每个阶段只做一类改动，用兼容层或检查点，不要一次大重写；
- 每个阶段写明：改哪些文件、不改变什么行为、用什么命令验证；
- 如果迁移本身会造成可见变化，单独列为“例外”，等我确认；
- 每个阶段要有回滚办法。
把计划写进 [MIGRATION_PLAN.md]，我确认后你再开始第一阶段。

3. 执行单个阶段

执行计划的第 [N] 阶段，只做这一阶段。
要求：
- 保持行为不变，例外之外的任何行为变化都要告诉我；
- 做完运行 lint、类型检查和与这些改动相关的最小测试，报告命令和结果；
- 列出改动的文件和每个文件改了什么；
- 如果测试失败，先说明原因，不要为了通过而删除或放宽测试。

4. 升级 OpenAI API 调用（针对用到 OpenAI API 的项目）

请把这个项目里的 OpenAI 调用升级到官方当前推荐的模型和接口。
- 先盘点现在用了哪些模型、接口和工具假设；
- 给出最小的迁移计划；
- 除非新接口或新模型要求，否则不改变现有行为；
- 按官方最新的提示词指南更新提示词；
- 列出需要我手动复核的提示词、工具或返回格式变化。

第 4 段对应官方《Upgrade your API integration》，该用例还提到可以在提示词里点名官方文档技能（OpenAI Docs skill）来读取最新文档，并建议建立评测流程，每次改动后跑一遍防止回退。

三、怎么判断这一阶段可以“过”

每个迁移阶段完成后怎么判断：测试失败、行为变化、改动范围过大、依赖锁文件变化大、涉及安全或支付

图：本站根据 官方用例《Run code migrations》 整理的示意图

官方说每个里程碑之后要跑最小验证并审查 diff。具体到你自己操作：

  • 先看测试和构建：能不能通过，新增失败的是哪些；
  • 再看 diff：改动是否只涉及这一阶段该改的文件，锁文件的变化是否在预期内；
  • 手动走一遍关键流程：登录、支付、数据读写这类自动测试可能覆盖不到的路径；
  • 没过就退回：用 Git 回到阶段开始前的状态，缩小范围重试，不要在一个坏掉的基础上继续叠加；
  • 涉及安全、支付、权限的升级：自己逐行审查，先在测试环境验证。可以让它再做一遍审查，见 /guides/codex-code-review。

四、长迁移的两个官方建议

官方《Run code migrations》还给了两个适合长任务的做法：

  • ExecPlans：让 Codex 为系统的每一部分写一份执行计划文档，记录迁移决策、目标状态和每次验证的结果，方便之后复查；
  • 目标（goal）：对于需要跨多轮持续推进的迁移片段，设定一个目标，写清结束状态、对等性检查、回滚预期和停止条件。

是否有这些功能取决于你使用的 Codex 版本，以官方当前文档为准。

常见问题

Q：它说升级完成，但构建报了一堆新错误？

把完整报错给它，要求先分类（哪些是升级引起的，哪些是原本就有的），再逐类处理。

Q：可以一次升级多个大版本吗？

官方的原则是增量。跨多个大版本时，按版本逐个升级通常更容易定位问题，具体路径以框架官方升级指南为准。

Q：额度会不会很快用完？

长任务消耗较大。Codex 随 ChatGPT 套餐提供，额度以官方页面为准，选择模型和推理强度见 /guides/codex-switch-model-reasoning-effort，需要更多额度可以看看 /chongzhi/chatgpt-plus 里的说明。

参考资料

  • Codex 官方用例：Run code migrations — https://learn.chatgpt.com/use-cases/code-migrations
  • Codex 官方用例：Upgrade your API integration — https://learn.chatgpt.com/use-cases/api-integration-migrations
  • Codex 官方文档：Prompting — https://learn.chatgpt.com/docs/prompting

Nathaniel 的更多内容

  1. 01

    Claude Code 在 Windows 上的常见坑：Git Bash 还是 PowerShell、路径反斜杠、假报错、WSL 怎么选

    Windows 上用 Claude Code，装好之后最容易踩的是：用哪个 shell、路径写法不一致、grep 没匹配就报错、钩子没生效、WSL 和原生怎么选。本文逐条按官方文档整理原因和处理办法，附三段提示词和一张对照表。

    Claude0
  2. 02

    Claude Code Hooks 实战「提交前自动跑测试」：PreToolUse 拦住 git commit，测试不过就退出码 2，附 Windows 注意点

    只写一个完整例子：让 Claude Code 每次要执行 git commit 之前，先自动跑项目测试，没通过就拦下并把输出交给它修。本文按官方 Hooks 文档给出脚本、settings.json 配置、测试方法、排错和 Windows 的两处坑。

    Claude0
  3. 03

    Claude Code 自定义斜杠命令与 Skill 实战：从零写一个「生成更新日志」的 /release-notes，含传参、预执行命令和调试

    概念看过了，还是不知道从哪下手？本文按 Claude Code 官方「Extend Claude with skills」写一个完整可用的例子：用 /release-notes 根据 git 记录生成更新日志，覆盖目录、frontmatter、传参、预执行命令、预授权和调试。

    Claude0
  4. 04

    Claude Code 部署网站：先写 Dockerfile 和 compose 在本机跑通，再按清单上云服务器，别让它直接改线上

    想让 Claude Code 帮你把网站部署到云服务器。本文只写通用做法，按 Docker 官方文档讲：让它写 Dockerfile、.dockerignore 和 compose，在本机跑通，端口和数据卷怎么设，再给出上线清单，并说明为什么不要让它直接动线上机器。

    Claude0
  5. 05

    Claude Code 写爬虫与数据清洗：先查 robots.txt 和网站条款，控制频率，原始数据留一份再清洗

    想让 Claude Code 写爬虫抓数据再清洗。本文先讲合规：robots.txt 不是授权也不是安全措施、网站条款要自己读；再讲怎么用 Python 标准库检查规则、小样本先试、保存原始数据，以及用 pandas 清洗，附四段提示词。

    Claude0
  6. 06

    Claude Code 写 Chrome 扩展：按 Manifest V3 起步，加载未打包的扩展，改了哪些文件要重新加载

    想让 Claude Code 帮你写一个 Chrome 扩展。本文按 Chrome 官方扩展文档讲：manifest.json 的最小写法、在 chrome://extensions 加载未打包的扩展、哪些改动要刷新、怎么看控制台和报错，再给四段提示词，以及权限要尽量少。

    Claude0

同产品的其他教程

  1. 01

    OpenAI API 的 token 怎么算、怎么估算费用：input_tokens 计数接口、tiktoken 和隐藏的输出 token

    发请求前想知道会用多少 token？官方有 Responses 的 input_tokens 计数接口，能把文字、图片、文件、工具定义一起算准；本地 tiktoken 只适合纯文本。本文给 Python 和 Node 示例，讲输出 token 为什么可能比看到的多，以及怎么估算费用。

    ChatGPT0
  2. 02

    OpenAI API Node.js / TypeScript 快速上手：npm install openai、example.mjs 第一个请求，到流式、函数调用、联网搜索

    用 Node.js 调 OpenAI API：设置 OPENAI_API_KEY 环境变量，npm install openai，新建 example.mjs，用 client.responses.create 发出第一个请求。并列出图片、文件、流式、函数调用、联网搜索和错误捕获的 Node 写法。

    ChatGPT0
  3. 03

    OpenAI API 用量层级（usage tiers）与速率限制怎么提升：Free、Build、Launch、Grow 和后台 Limits 页

    OpenAI API 的限速不是固定的：官方按累计购买额度把组织分成 Free、Build、Launch、Grow 四个层级，达到门槛自动升级。本文讲 RPM、TPM 等指标、怎么在后台查自己的限额、响应头怎么读、花费上限和限速的区别，以及怎么让限额变得够用。

    ChatGPT0
  4. 04

    OpenAI API 报错 400、401、403、404、429、500、503 怎么排查：按官方错误码页逐个看原因和解决办法

    调用 OpenAI API 返回 400、401、403、404、429、500、503，各自什么意思？本文按官方 Error codes 页，每个状态码一节，写清官方给的原因和解决办法，并说明 404 在官方页面里的位置、429 的六种情形，附 Python 和 Node 的错误捕获写法。

    ChatGPT0
  5. 05

    OpenAI Realtime API 是什么：语音到语音会话、WebRTC 与 WebSocket、临时密钥和事件机制

    Realtime API 让模型直接处理音频，做可以随时打断的语音助手。本文按官方文档讲它是什么、什么时候用、浏览器接入的流程、session 与事件、可用声音、60 分钟会话上限、安全标识，以及它和转写、文字转语音的分工。

    ChatGPT0
  6. 06

    OpenAI 图像生成 API 怎么用：gpt-image 系列、images.generate 与 Responses 工具、尺寸质量和遮罩编辑

    用 OpenAI API 生成或编辑图片，有 Image API 和 Responses 里的 image_generation 工具两条路。本文按官方文档给 Python 和 Node 示例，讲 gpt-image 模型选择、尺寸质量格式参数、遮罩编辑、被拦截时的错误处理，以及需要组织验证的提醒。

    ChatGPT0

0 条评论

登录 后参与评论

还没有评论，来抢沙发～