前言：「只是把版本號改大一點」，真的只是這樣嗎？

「dependency bump 而已，把 package.json 裡的版本號改一改，跑一次測試看綠不綠燈，很難吧？」

如果只是升級一個普通的工具函式庫，這句話大致成立。但當升級對象是 TypeScript 本身——一個直接參與「這段程式碼合不合法」判定的編譯器——版本號背後藏著的東西，遠比一次 pnpm update 能處理的還多。今天用 PHPUnit & Pest Test Explorer 這個真實專案裡一次「升 TypeScript 大版本」的 PR，具體看看這種升級會踩到哪些不容易靠「跑測試」就抓到的坑。

今日目標

• 看一個真實的 TypeScript 大版本升級 PR，內容包含哪些相容性調整
• 理解為什麼「型別檢查工具本身升級」跟「一般函式庫升級」是不同量級的風險
• 認識三種 TS6 升級時真實出現的相容性變化：隱式型別涵蓋範圍、跨套件路徑解析、棄用警告
• 建立「升級編譯器/語言工具本身」該額外檢查什麼的具體清單

一次真實的升級：TypeScript 5 到 6

PHPUnit & Pest Test Explorer 這個真實專案有一個把整個 workspace 依賴一次性升級的 PR，其中一項是把兩個子套件的 TypeScript 從 5 升到 6。這個 PR 的說明裡具體記錄了幾個因為這次升級而必須額外處理的相容性調整，不是單純改個版本號就過關：

第一個坑：types 陣列一旦出現，隱式涵蓋的型別宣告就消失了。 TypeScript 6 改變了一個行為——一旦 tsconfig.json 裡明確寫了 "types" 陣列，原本會自動涵蓋進來的 @types/* 套件型別宣告，就不再隱式生效了。這個 PR 裡因此要補上 "types": ["node"]，另一個子套件的測試設定也要多加 "mocha"，不然編譯器會找不到這些套件原本提供的型別。

第二個坑：跨套件的原始碼路徑映射，在新版下踩到更嚴格的邊界檢查。 專案裡原本有一條指向另一個內部套件原始碼路徑的 tsconfig path mapping，讓一個套件可以直接引用另一個套件還沒編譯過的原始碼。TypeScript 6 對跨套件邊界的 rootDir 檢查變嚴格了，這條路徑映射因此被移除，改成透過已經建置完成的套件（node_modules/dist）來解析依賴——這代表建置順序本身也變成一個必須確認的前提，不只是型別對不對的問題。

第三個坑：一個原本會讓建置工具悄悄崩潰的棄用警告，需要明確標注才能壓下去。 升級後出現一個跟 baseUrl 相關的棄用警告，這個警告不只是「印出來嚇你一跳」而已，它會讓建置工具產生型別宣告檔案（.d.ts）的那個步驟直接崩潰。PR 裡加了 "ignoreDeprecations": "6.0" 這個設定項，明確告訴編譯器「這個棄用警告我知道，先不要讓它擋住建置」。

為什麼這種問題「跑測試」抓不太到

用一組對照來看這件事：

❌ 只看「測試有沒有過」的升級流程：
1. 改版本號
2. pnpm install
3. 跑單元測試套件
4. 綠燈 → 合併
→ 型別檢查層級的變化（types 隱式涵蓋範圍改變、
  rootDir 邊界檢查變嚴格）不一定會反映在執行期測試結果上，
  尤其當受影響的型別剛好沒有被任何測試案例直接用到時

✅ 把「型別檢查」跟「建置流程」都列入升級檢查範圍：
1. 改版本號
2. pnpm install
3. 完整跑一次 tsc --noEmit（型別檢查，不只是執行測試）
4. 完整跑一次正式建置流程（含 .d.ts 產生這類容易被
   棄用警告打斷的步驟），不是只跑開發模式
5. 跑單元測試套件
6. 綠燈 → 合併
→ 型別檢查失敗、建置步驟崩潰，這兩類問題只有在真的跑過
  對應流程時才會現形，光看單元測試綠燈不夠

升級一個工具函式庫，影響的是「這個函式庫提供的功能對不對」；升級一個編譯器/語言工具本身，影響的是「你原本能寫的程式碼，現在還算不算合法」——後者的檢查範圍，天生就比「跑一次測試套件」要廣。

這正好呼應這個系列的主題句：AI 能加速的是「改版本號、跑升級流程」這類機械性工作，但「升級到這個版本之後，還有哪些檢查層級需要重新確認」這件事，需要對「這次升級的對象是什麼類型的工具」有判斷力——AI 如果只把 dependency bump 都當成同一類問題處理，遇到編譯器/語言工具的升級時，很容易漏掉型別檢查跟建置流程這兩個測試套件覆蓋不到的層面。

AI 在這類升級裡該扮演什麼角色

具體到 AI 協作的分工：AI 適合做的是機械性的部分——改版本號、跑升級指令、閱讀升級對象的 changelog/release notes 找出「已知的破壞性變更」清單；但「這次升級要額外驗證哪些檢查層級」這個判斷，需要先分辨清楚「這是一般函式庫升級，還是編譯器/語言工具本身的升級」，這個分類本身就是需要人保留的判斷，因為兩者需要的驗證廣度完全不同。

今日思考題

回想你上一次升級專案裡的編譯器、語言版本、或是任何會影響「程式碼合不合法」判定的核心工具：那次升級,你除了跑測試套件之外，有沒有額外確認過完整的型別檢查跟建置流程？

今日重點回顧

• 升級 TypeScript 這類編譯器/語言工具，跟升級一般函式庫是不同量級的風險，因為它改變的是「程式碼合不合法」的判定範圍
• 真實案例裡的三個坑：types 陣列讓隱式型別涵蓋消失、跨套件路徑映射踩到更嚴格的邊界檢查、棄用警告讓建置步驟崩潰
• 這幾類問題不一定會反映在執行期測試結果上，只跑單元測試套件不夠，要額外跑完整的型別檢查跟建置流程
• AI 適合做機械性的升級操作跟 changelog 蒐集，但「這次升級屬於哪一類、需要驗證到什麼廣度」的判斷要留給人

明日預告

明天要換一個完全不同的情境：從 issue 討論到實作一個新功能的完整過程——一個功能怎麼從使用者的需求描述，變成程式碼裡的具體實作。