TypeScript 6 升級清單：先補 tsconfig 隱藏預設，再處理 deprecated 設定

先理解 TypeScript 6 改變的是哪些預設#

TypeScript 6.0 的 release notes 把升級分成兩類：一類是「以前依賴隱藏預設，現在要明確指定」；另一類是 deprecated 選項在未來版本會消失。先分開處理，排查時才不會把設定錯誤和程式碼錯誤混在一起。

這份表是「先找差異」用的索引，不代表每個專案都要採用同一組值。尤其 library、Node application、Vite／Astro application 的 module 邊界不同，不能直接複製別人的完整 tsconfig。

第一步：把編譯器真正採用的設定印出來#

不要先看 IDE 的紅線。先在升級前和升級後各執行一次 --showConfig，把輸出存成不進版控的暫存檔，才能知道差異來自 TypeScript 版本、extends 鏈，還是工作區的另一份設定。

1
pnpm exec tsc --showConfig -p tsconfig.json > /tmp/tsconfig-before-or-after.json
2
pnpm exec tsc --noEmit -p tsconfig.json

如果專案有多份設定，例如 tsconfig.app.json、tsconfig.node.json 或測試專用設定，必須對每一份執行一次。tsc 不帶 -p 時，實際載入的檔案可能不是你正在看的那一份；CI 也可能使用另一個工作目錄。

升級檢查時至少記錄以下欄位：

• compilerOptions.types、rootDir、outDir。
• module、moduleResolution、target 與 lib。
• strict、noUncheckedSideEffectImports 和 allowJs。
• extends 展開後是否把 base config 的值覆寫掉。

第二步：補上 types 和 rootDir 的專案邊界#

TypeScript 6 將 types 的預設改成 []，這不等於「不載入任何套件」，而是只讓你明確列出的 @types 套件提供全域型別。Node.js 專案常見的寫法是：

1
{
2
  "compilerOptions": {
3
    "types": ["node"],
4
    "rootDir": "./src",
5
    "outDir": "./dist"
6
  }
7
}

測試檔案若需要 Vitest、Jest 或 Playwright 的全域型別，建議在測試專用 tsconfig 加入對應值，不要為了讓 production source 通過而把所有測試型別灌進主設定：

1
{
2
  "extends": "./tsconfig.json",
3
  "compilerOptions": {
4
    "types": ["node", "vitest/globals"]
5
  },
6
  "include": ["src", "tests"]
7
}

rootDir 則是輸出結構的邊界。若以前讓編譯器依照所有輸入檔案自行推導，新增 scripts/ 或測試資料夾後，輸出可能被迫反映更高層目錄。把應用程式的 src 明確設為 rootDir 後，若有跨出 src 的檔案，錯誤反而能提醒你重新決定 include 邊界，而不是默默改變 dist 結構。

第三步：依執行環境選 module 與 moduleResolution#

不要把 module 和 moduleResolution 當成可以各自隨意切換的兩個開關。它們要和最終執行者一致：

moduleResolution: "node"（也常標成 node10）的問題不是今天一定不能編譯，而是它代表舊的解析模型。先確認 package exports 和實際部署方式，再一次把 module 與 resolution 換成相配的組合；不要只為了消掉警告，把 moduleResolution 單獨改成另一個值。

若專案同時有 source build 和 test runner，建議把它們的設定拆開，並在 CI 中分別跑 type-check、unit test 與 production build。這比讓一個超大的 tsconfig 同時迎合所有工具更容易維護。

ignoreDeprecations 只能用來爭取時間#

升級過程中可能先看到一批 deprecated 設定。可以暫時加入：

1
{
2
  "compilerOptions": {
3
    "ignoreDeprecations": "6.0"
4
  }
5
}

但要把它視為有期限的 migration 開關，並在 issue 或 upgrade checklist 記錄要移除的欄位。它只會隱藏部分棄用警告，不會恢復舊的預設，也不會修好錯誤的 module 邊界。若你加了 ignoreDeprecations 後 build 通過，仍要繼續檢查 dist 結構、執行時 import、declaration 和測試型別。

比較可靠的順序是：

1. 先用 tsc --showConfig 找出實際生效的 deprecated 選項。
2. 確認這個選項是被自己的 tsconfig 還是外部 base config 帶入。
3. 以目標 runtime 或 bundler 的新解析策略取代它。
4. 跑完 production build 和 consumer smoke test 後，移除 ignoreDeprecations。

noUncheckedSideEffectImports 報錯時不要直接加萬用宣告#

前端專案常見的錯誤長這樣：

1
import './global.css'
2
import './register-polyfill'

如果路徑真的拼錯，新的檢查很有價值；先確認檔案名稱、大小寫和 bundler alias。若 import 的是 bundler 處理的非 TypeScript 資產，才考慮在型別宣告中明確描述它，而不是用一個過寬的 declare module '*' 把所有拼字錯誤一起隱藏：

1
declare module '*.css'
2
declare module '*.svg' {
3
  const url: string
4
  export default url
5
}

宣告應該貼近真實資產格式；如果 SVG 在專案中其實會被 loader 轉成 component，就應該依 loader 的型別補充，而不是假設它永遠是 URL。

升級驗收：不要只看 tsc 的 exit code#

完成設定調整後，至少做四層驗證：

1
# 1. 型別與設定
2
pnpm exec tsc --showConfig -p tsconfig.json
3
pnpm exec tsc --noEmit -p tsconfig.json
4

5
# 2. 產出與路徑
6
pnpm build
7

8
# 3. 執行時 module smoke test
9
node dist/server.js
10

11
# 4. 套件 consumer／測試
12
pnpm test

node dist/server.js 只是示意，請換成專案真正的啟動入口。library 則應在乾淨的暫存 consumer 中安裝 tarball，測試 ESM、CommonJS 和 declaration；前端 bundler 應確認 production bundle 可以載入 CSS、圖片和 dynamic import。

如果這是 Astro、Vite 或其他整合框架的升級，可以把本篇的 tsconfig 檢查放進框架升級清單一起跑，例如Astro 7 升級前的 Vite 8 與建置檢查。重點不是追求一份「全域通用」設定，而是確保每個執行邊界都有明確 owner。

結論：先明確化，再移除過渡設定#

TypeScript 6 升級最穩定的策略，是先把編譯器以前代替你猜的部分寫出來：types 管全域型別、rootDir 管 source 邊界、module 與 moduleResolution 管執行環境，ignoreDeprecations 只暫時包住還沒清掉的舊設定。最後用設定展開、production build、runtime smoke test 和 consumer 測試一起驗收，才知道你修的是 warning，還是實際的輸出與執行行為。

常見問題#