結論先說
- 絕不要一次性全倉重命名加
strict: true,必須按「共存編譯 → 葉子模組先遷 → 獨立嚴格配置鎖定」分階段推進。TypeScript 原生支持allowJs: true與 JS/TS 混合編譯,保證每個小 PR 都能正常構建上線、零阻斷業務發版。 - 用
tsconfig.strict.json把已遷移目錄「鎖死」在嚴格模式,防止邊遷邊回退。主配置先保持寬鬆兼容存量 JS,另建嚴格配置僅include已完成目錄並接入 CI 門禁,遷完一個目錄就往白名單加一個。 - 給 Codex 下達明確的「反作弊護欄」,禁止用
any、as unknown as和@ts-ignore敷衍過關。配合倉庫AGENTS.md約束規則(詳見 /guides/codex-agents-md-guardrails-stop-deleting-tests),並且優先遷移幾乎不依賴其他模組的純工具函數、常量和 DTO 類型層。 - 每次只遷 3–8 個強關聯文件,遷完立即跑
tsc --noEmit與既有行為測試。涉及核心業務邏輯的老文件務必先補特徵測試再加類型(做法見 /guides/codex-refactor-legacy-code-characterization-tests),杜絕為了消類型報錯順手改壞運行時分支。 - 大倉庫分批次遷移並反覆執行類型收斂會持續佔用上下文與周配額。國內沒有外幣卡的開發者可在本站自助開通 ChatGPT Plus 充值 或無 5 小時限額的 ChatGPT Pro 充值,多人研發團隊推進架構升級可諮詢 ChatGPT Business 團隊定製。

圖:本站根據 TypeScript 官方遷移指南 整理的漸進遷移示意圖
本文根據 OpenAI Codex 官方文檔《Codex CLI》《Non-interactive mode》及 TypeScript 官方文檔《Migrating from JavaScript》《TSConfig Reference》整理,資料核對於 2026-11-19。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。
適用於誰
- 維護運行多年、包含數百個
.js/.jsx文件的前端或 Node.js 後端老倉庫,想遷到 TypeScript 卻怕改動太大引發線上故障的工程師; - 曾讓 AI 一次性全倉把
.js批量改名成.ts並開啟strict: true,結果冒出滿屏any、構建中斷且 Diff 根本沒法 Review 的開發者; - 需要在不停止日常業務迭代的前提下,制定可量化、可回滾的 TypeScript 嚴格模式演進路線的技術負責人。
一、四階段配置演進:怎麼做到邊遷邊發版不崩線上
按 TypeScript 官方 tsconfig 能力,把遷移拆成四個可驗證階段,任何階段都能隨時停下來發佈線上版本:
| 遷移階段 | 核心 tsconfig 開關 | 覆蓋範圍 | 線上風險與門禁策略 |
|---|---|---|---|
| 階段 1:混編落地 | allowJs: true、strict: false、noEmit: true | 全倉共存 | 僅打通 TS 工具鏈與構建,零改動存量運行時代碼 |
階段 2:基礎層轉 .ts | 主配置寬鬆 + tsconfig.strict.json 開 strict: true | utils/、types/、constants/ | 葉子模組無業務副作用,遷完即加入嚴格配置白名單 |
| 階段 3:業務層分目錄推進 | 逐目錄把 noImplicitAny 與 strictNullChecks 納入嚴格配置 | services/、components/、routes/ | 每次 PR 限 3–8 文件,先保運行時行為不變再收緊類型 |
| 階段 4:全倉嚴格收口 | 主配置開啟 strict: true、移除過渡文件 | 全倉庫 | 清零歷史 .js,CI 強制 tsc --noEmit 零報錯 |
關鍵配置:tsconfig.strict.json 目錄鎖定模板
在根目錄保留兼容存量 JS 的 tsconfig.json,同時增加一份只盯緊「已遷移目錄」的嚴格配置文件,讓 CI 每次提交都同時跑 tsc -p tsconfig.strict.json --noEmit:
json
{
"extends": "./tsconfig.json",
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"noEmit": true
},
"include": [
"src/types/**/*",
"src/utils/**/*",
"src/services/order/**/*"
]
}
二、先摸清依賴拓撲,再讓 Codex 按「由底向上」順序遷移
如果直接從頂層頁面或主入口控制器開始加類型,Codex 面對滿屏未標註類型的底層依賴,很容易被迫編造錯誤接口或偷懶寫 any。本站建議先跑一次只讀分析,列出最適合動刀的葉子目錄:
bash
codex exec --ephemeral --sandbox read-only \
"請掃描 src/ 目錄下的 .js / .jsx 文件依賴關係(import/require):
1. 按內部入度與出度排序,找出出度為 0 或只依賴第三方包的底層純模組清單;
2. 估算每個目錄的文件數與是否存在動態 eval、隱式掛原型或運行期改對象結構的高危寫法;
3. 給出分 4 批推進遷移的目錄先後順序,暫不修改任何文件。"
拿到順序清單後,把遷移紅線寫進倉庫 AGENTS.md,避免 Codex 走捷徑:
markdown
## TypeScript 遷移護欄
- 嚴禁使用 `any`、雙重斷言 `as unknown as` 或 `@ts-ignore` 掩蓋類型錯誤;確實無法確定的外部輸入必須用 `unknown` 加類型守衛(type guard)收窄。
- 遷移期間禁止順手重構業務邏輯、修改字段名或改變空值/預設值運行時行為;若 `strictNullChecks` 暴露出真實潛在空指針,必須先標出風險點由人工確認後再改。
- 每批修改完成後,必須運行 `npx tsc -p tsconfig.strict.json --noEmit` 與相關單元測試,報告真實通過情況。

圖:本站根據 TypeScript TSConfig 官方參考 整理的漸進配置示意圖
訂閱與帳號準備提示:批量把幾十上百個老舊 JS 模組分批補全精確接口定義並收斂strictNullChecks報錯,需要多輪跨文件上下文讀取(省額技巧可參考 /guides/codex-save-usage-quota-model-reasoning-context-tips)。持續數週的架構升級建議在站內升級 ChatGPT Pro 5x iOS 可覆蓋檔 或 ChatGPT Pro 5x 信用卡不可覆蓋檔;新帳號首次開通 Codex 如遇到短訊驗證阻礙,可參考 Codex 註冊手機驗證服務。
三、單批次遷移的標準提示詞與防崩線上驗收集
每個小批次單獨切一個 Git 分支,把待遷移目錄限定在 3–8 個文件內,按下面模板發起任務:
text
請將 src/utils/pricing.js、src/utils/date.js 與 src/utils/format.js 遷移為 .ts 文件,並使其通過 `npx tsc -p tsconfig.strict.json --noEmit`:
1. 嚴格遵守倉庫 AGENTS.md 中的 TypeScript 遷移護欄,不用 any 或 @ts-ignore;
2. 先檢查全倉調用這 3 個文件的所有位置,確保推斷出的參數與返回值類型覆蓋真實傳參(包含 null/undefined 或字符串數字混傳情況);
3. 保持所有導出名稱與運行時計算結果完全一致,同步更新或補充對應的單元測試;
4. 最後運行 `npx tsc -p tsconfig.strict.json --noEmit` 與對應單測,彙報改動文件與仍需人工確認的隱蔽空值邊界。
批量收尾某個目錄時如果冒出較多同類型編譯或 Lint 報錯,可以配合批處理收斂流程逐類清零(參考 /guides/codex-batch-fix-typescript-eslint-ruff-errors),並在合入前逐條核驗:
- 構建產物等價檢查:比對打包工具(Vite / Webpack / tsc)產出的入口導出和 ESM/CJS 互操作行為,確保外部調用方沒有因預設導出包裝差異報錯;
- 空值防禦不做靜默吞錯:
strictNullChecks常會揪出老代碼裏「本就可能為undefined」的暗雷,用 Codex 補空值判斷時要確認預設回退值是否符合業務預期,而不是隨意返回空字符串或0。
常見問題
問:倉庫裏有一些非常古老、幾乎不再修改的第三方拷貝 .js 腳本,也要硬改寫成 .ts 嗎?
答:不必強行改寫。更務實的做法是保留原 .js 文件,在旁邊補一個同名的 .d.ts 類型聲明文件(讓 Codex 依據其導出簽名生成聲明),既能讓上游嚴格 TS 代碼享受完整類型檢查,又能實現零運行時改動風險。
問:打開 strictNullChecks 後,一個老接口返回結構到處都是可選字段,Codex 寫了滿屏 ?. 可選鏈怎麼辦?
答:這說明接口邊界沒有做運行時歸一化。建議讓 Codex 在網絡請求邊界層或反序列化處集中用 Schema 校驗(如 Zod)或適配器函數把髒數據清洗成確定結構,業務層就能拿到乾淨的非空類型,而不必在幾十個組件裏到處寫防禦判空。
問:國內沒有外幣信用卡,或者公司團隊需要統一採購並開具增值稅發票,怎麼開通適合長期重構升級的 Codex 訂閱?
答:可通過本站 AI 會員充值總覽 按需選購 ChatGPT Plus 自助卡密 或配額更高的 ChatGPT Pro 充值,多人研發團隊可直接諮詢 ChatGPT Business 團隊定製。支持支付寶、微信支付及 AlipayHK,提供卡密自助兌換(無需交出帳號密碼)與客服協助,並支持開具增值稅發票;實時價格以商品頁展示為準,售後執行掉訂閱按剩餘天數折退、封號不在質保範圍規則。
相關教學
- 用 Codex 批量修復 TypeScript / ESLint / Ruff 報錯:按規則分組收斂指南
- 用 Codex 重構老舊代碼先補特徵測試:防改壞隱性邏輯工作流
- 寫好 Codex AGENTS.md 防護護欄:禁止亂刪測試與敷衍繞過
- Codex 省額度實戰技巧:模型選擇、推理強度與上下文控制
- Codex 額度與使用限制:Plus / Pro 能用多少與怎麼查
參考資料
- OpenAI Codex 官方文檔:Codex CLI — https://learn.chatgpt.com/docs/codex/cli
- OpenAI Codex 官方文檔:Non-interactive mode — https://learn.chatgpt.com/docs/non-interactive-mode
- TypeScript 官方手冊:Migrating from JavaScript — https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html
- TypeScript 官方參考:TSConfig Reference — https://www.typescriptlang.org/tsconfig/
0 條評論
還沒有評論,來搶沙發~