註冊
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 條評論

登入 後參與評論

還沒有評論，來搶沙發～