轉譯:Babel、TypeScript 編譯器與 SWC
背景
2014 年之前,撰寫現代 JavaScript 意味著等待瀏覽器跟上腳步。ECMAScript 2015(ES6)引入了 類別、箭頭函式、解構賦值與模組。各家瀏覽器的支援時程不一,Internet Explorer 更是落後 數年,因此團隊實務上的選擇只有兩個:繼續停留在 ES5,或接受有一部分使用者會看到破損的 頁面。
Babel 徹底改變了這個限制。透過將現代 JavaScript 編譯成舊版語法,它解開了「你能寫什麼」 和「瀏覽器能執行什麼」之間的耦合。開發者開始在規格定稿當天就採用 ES2015+ 特性,而不是 等待兩到四年讓瀏覽器廣泛支援。「現在就用」成為前端開發的運作模式。
轉譯(transpilation)是原始碼對原始碼的編譯:輸入與輸出都是人類可讀的原始碼,只是方言或 功能集不同。這有別於編譯成機器碼(Rust、C++ 編譯器的工作)或位元組碼(JVM、.NET CLR 所 消費的格式)。現代前端專案中主要的轉譯工作包括:
- 語法降階(Syntax lowering) — 將
async/await、可選鏈結、空值合併運算子、類別欄位 轉換成舊版執行環境能理解的 ES5 或 ES2015 語法。 - 型別剝離(Type stripping) — 移除 TypeScript 型別標注,使輸出成為瀏覽器或 Node.js 可執行的合法 JavaScript。
- JSX 轉換 — 將
<Component />轉換為React.createElement(Component, null)或等效 的自動 runtime 呼叫。 - Polyfill 注入(Polyfill injection) — 為目標環境缺少的 API(如
Promise、Array.prototype.flat)加入執行期實作,通常來自 core-js 函式庫;語法轉換本身無法補上 缺少的內建功能。
這些工作外表相似,但效能特徵截然不同。型別剝離本質上是文字轉換:一旦找到標注的邊界, 刪除操作就很直接。型別檢查則要驗證 user.id 在你承諾的地方確實是 string。要回答 這個問題,需要解析 user 來自哪個 import,並跨檔案邊界追蹤型別推斷,而不只是讀懂眼前 這一個檔案。這正是現代建置流程把剝離與檢查拆成兩個獨立步驟的原因:一個在每次存檔時快速 執行,另一個則只在 CI 中執行一次、作為關卡。
視覺化
現代專案中 TypeScript 原始碼的雙路徑流程:
TypeScript 原始碼(.ts / .tsx)
│
├─────────────────────────────────────────────────┐
│ │
▼ ▼
tsc --noEmit SWC / esbuild
(全程式分析) (逐檔,可平行)
│ │
▼ ▼
型別錯誤 JS 輸出(.js)
(在 CI 中回報) (無型別,無 JSX)
通過 / 失敗 │
▼
打包工具(Rollup /
Webpack / esbuild)
│
▼
正式環境打包結果左路徑在每次 CI 任務執行一次。右路徑在開發環境中於每次存檔時執行。
範例
1. 含 browserslist 的 Babel 設定
.babelrc.json:
{
"presets": [
[
"@babel/preset-env",
{
"useBuiltIns": "usage",
"corejs": "3.37"
}
],
["@babel/preset-react", { "runtime": "automatic" }],
"@babel/preset-typescript"
]
}package.json(browserslist 欄位,由 @babel/preset-env 自動讀取):
{
"browserslist": ["> 0.5%", "last 2 versions", "not dead"]
}useBuiltIns: "usage" 搭配 corejs: "3.37",會讓 Babel 掃描每個檔案,找出目標瀏覽器 缺少的 API(例如 Promise、Array.prototype.flat),只插入對應的 polyfill,來源是 core-js(生態系中多數專案採用的 polyfill 函式 庫),而不必把整個 core-js 套件都送到每一頁。
@babel/preset-env 會查詢 browserslist 資料庫,判斷要套用哪些語法轉換。若沒有 browserslist 設定,它就沒有目標資訊,預設會轉換所有內容,產生比必要更大、更慢的輸出。
@babel/preset-typescript 剝離 TypeScript 標注;它不做型別檢查。需要另外執行 tsc --noEmit 才能捕捉型別錯誤。
2. 含注解的 tsconfig.json 關鍵選項
{
"compilerOptions": {
// 輸出語法版本。"ES2022" 對 Node 18+ 與現代瀏覽器是安全的選擇。
// 當 SWC 或 esbuild 負責 emit 時,tsc 仍會讀取此欄位進行型別推斷。
"target": "ES2022",
// "bundler"(TypeScript 5.0+):模擬 Vite/Webpack 解析模組的方式。
// 遵守 package.json "exports",允許相對 import 不附副檔名。
// 僅對無打包工具的 Node.js CLI/函式庫使用 "node16"。
"moduleResolution": "bundler",
// 使用 moduleResolution "bundler" 時的必要設定。
"module": "ESNext",
// 啟用:strictNullChecks、noImplicitAny、strictFunctionTypes 等。
// 新專案從 true 開始;在既有程式碼上加入需要修復錯誤。
"strict": true,
// 路徑別名——也必須在打包工具中配置相同的別名。
"paths": {
"@/*": ["./src/*"]
},
// 不寫出 .js 檔案;tsc 僅用於型別檢查。
// 若 tsc 是你的 emit 步驟(在打包工具專案中很少見),則移除此旗標。
"noEmit": true,
// 在型別檢查中包含 .tsx 檔案。
"jsx": "react-jsx"
},
"include": ["src"]
}3. Next.js:SWC 編譯器設定
next.config.mjs(Next.js 13+;SWC 已是預設,無需額外旗標):
/** @type {import('next').NextConfig} */
const nextConfig = {
// SWC 自 Next.js 12 起即為預設編譯器。
// 以下選項設定 SWC 特有的轉換。
compiler: {
// 從正式環境建置中移除 console.log 呼叫。
removeConsole: process.env.NODE_ENV === "production",
// 啟用 styled-components 支援(取代 babel-plugin-styled-components)。
styledComponents: true,
},
// 若存在 .babelrc,Next.js 會自動退回使用 Babel。
// 無法強制在有 .babelrc 的情況下使用 SWC——請刪除 .babelrc。
};
export default nextConfig;從 Babel 遷移到 Next.js 中的 SWC:刪除 .babelrc(或 .babelrc.json),並從 devDependencies 移除 babel-loader。下次執行 next dev 或 next build 時,Next.js 就會使用 SWC。若有自訂 Babel 外掛且找不到對應的 SWC 版本,保留 .babelrc 檔案即可。 Next.js 會逐檔退回使用 Babel。
4. CI 指令:型別檢查後再轉譯
# 在 CI 的建置前執行。有任何型別錯誤即以非零值退出。
pnpm tsc --noEmit
# 若 tsc 通過,使用 SWC 輸出可發布的結果。
# -d 設定輸出目錄;--source-maps 包含 source map。
pnpm swc src -d dist --source-maps
# 或在 Next.js 專案中,讓框架統籌兩者:
pnpm tsc --noEmit && pnpm next buildVite 自 2.0(2021 年)起,內部就用 esbuild 處理 TypeScript 轉譯與 JS 轉換。Vite 8 (2026 年)以單一的 Rust 打包工具 Rolldown 取代了這個開發階段的 esbuild 步驟,以及 Rollup 的正式環境打包,Rolldown 建構在 oxc 工具鏈之上。無論哪一種, 這個系譜中的打包工具都不會在建置過程中做型別檢查,因此需將 tsc --noEmit 作為獨立 步驟加在建置之前或之後,而非取代它:
pnpm tsc --noEmit && pnpm vite build5. 透過 @swc/core 以程式方式使用 SWC
import { transform } from "@swc/core";
const result = await transform(
`const greet = (name: string) => \`Hello, \${name}\`;`,
{
jsc: {
parser: { syntax: "typescript" },
target: "es2020",
},
sourceMaps: true,
}
);
console.log(result.code);
// const greet = (name) => `Hello, ${name}`;最佳實踐
在 CI 中應將型別檢查(tsc --noEmit)與轉譯(SWC 或 esbuild)分離,並將型別檢查設為必要的 CI 步驟。 型別剝離是逐檔且可平行的;型別檢查則需要全程式分析,單次執行的成本大致等同於檢查整個專案。實作方式仍然重要:TypeScript 7 的原生 Go 編譯器把這項成本削減了約 10 倍,優於先前以 JavaScript 撰寫的 tsc(詳見下方〈設計思維〉)。以 SWC 負責轉換、tsc --noEmit 作為阻塞式 CI 關卡,能在開發時提供最快的熱路徑,同時確保型別錯誤在合併前被捕捉。對 Vite 專案而言,pnpm tsc --noEmit && pnpm vite build 是標準模式。
所有使用 @babel/preset-env 的專案,都應明確設定 browserslist 目標。 沒有 browserslist 設定,@babel/preset-env 就沒有目標瀏覽器的資訊,可能套用所有轉換(產生不必要的大型輸出),也可能一個都不套用。請在 package.json("browserslist" 欄位)或 .browserslistrc 檔案中定義目標,並隨著你的支援範圍演進而持續更新。
以 Vite、Webpack 或其他打包工具建置的專案,tsconfig.json 中應使用 moduleResolution: "bundler"(TypeScript 5.0+)。node 解析策略不理解 package.json 的 exports 欄位,而現代雙格式套件(dual-format package)用此欄位選擇 CJS 或 ESM。使用錯誤的解析模式,會導致 TypeScript 對合法的打包工具解析 import 發出錯誤的型別錯誤。當 tsc 僅用於型別檢查時,應搭配 "module": "ESNext" 和 "noEmit": true。
絕對不能將 @babel/preset-typescript 視為型別檢查工具。 Babel 剝離 TypeScript 標注時不驗證它們。一個含有錯誤型別標注的檔案仍會成功轉譯,不產生任何錯誤。型別錯誤只有在 tsc --noEmit 對整個專案執行時才會浮現。使用 Babel 而沒有獨立的 tsc 步驟,對型別安全毫無保障。
路徑別名必須在 tsconfig.json 和打包工具中分別設定:它們是各自獨立的系統。tsconfig.json 中的 paths 能滿足 TypeScript 進行型別檢查的模組解析需求,但 SWC、esbuild 和 Vite 各自使用獨立的別名設定。只在 tsconfig 中定義 paths 對打包工具的執行時期模組解析毫無影響。必須在 Vite 中設定 resolve.alias(或在你的打包工具中設定等效項),以匹配 tsconfig.json 中的每一個別名。
設計思維
Babel 為何具有變革性。 在 Babel 出現之前,一項功能標準化後,團隊往往要再等兩到四年才能真正上線:這段時間包含 瀏覽器廠商實作支援,以及 Internet Explorer 的使用者佔比降到團隊可接受的門檻以下。Babel 把這段等待壓縮到只剩幾天。TC39 一旦定稿提案,對應的外掛通常一週內就會問世,團隊因此得以 在瀏覽器原生支援可選鏈結與空值合併運算子之前,就在正式環境中使用它們。後續所有的轉譯器, 包括 SWC 與 esbuild,都繼承了這個假設:開發者如今預期編譯步驟是發布 JavaScript 的常態 環節。
TypeScript 為何贏得型別安全之爭。 TypeScript 並不是第一個嘗試為 JavaScript 加入靜態型別的工具。Closure Compiler 與 Flow 都更早出現。TypeScript 勝出有三個結構性原因。第一,它的型別系統是結構化(structural) 而非名義化(nominal)的:若兩個型別具有相同的形狀,它們就相容。這讓採用得以漸進:接受 { name: string } 的函式,對任何擁有 name 字串屬性的物件都能生效,無需明確宣告意圖。 第二,TypeScript 允許增量採用:一個 .js 檔案改名為 .ts 而不做其他修改,就是合法的 TypeScript。團隊可以逐檔遷移,歷時數月,而不必進行全面重寫。第三,生態系對齊了: DefinitelyTyped 為數千個 npm 套件提供型別定義,主要框架(React、Vue、Angular)也發布了 第一方型別。到 2023 年,TypeScript 已成為任何這些框架新專案的預設起點。
SWC 與 esbuild 為何在轉譯速度上取代 Babel。 Babel 的瓶頸在於 JavaScript 執行環境。將一個檔案解析成 AST、透過外掛鏈遍歷該 AST,再將 修改後的 AST 節點印回原始碼,這一切都在 V8 中執行。V8 的通用運算能力很快,但 AST 操作 屬於高配置量(allocation-heavy)的工作:每個節點都是一個物件,每次轉換都會建立新物件, 最終都要交給垃圾回收器(GC)清理。SWC 用 Rust 完成相同的工作,Rust 編譯成原生碼,沒有 GC 暫停的問題,並能在多條 OS 執行緒上同時處理多個檔案。
在 SWC 自家的單檔案基準測試中,SWC 在單執行緒上比 Babel 快約 18 倍(616 次對 34 次 運算/秒;該測試中 SWC 的目標是 ES3、Babel 的目標是 ES5,對 Babel 而言是較容易的目標), 而在多個轉換透過 Node 工作執行緒(worker threads)並行執行時,最高可達約 70 倍 (100 個並行操作下為 2,199 次對 32 次運算/秒)。這應視為供應商自製單檔案基準測試給出的 上限,而不是你自己的程式碼庫會看到的普遍倍數。
esbuild 以 Go 採取相同的原生碼方案,特別注重平行處理。第三個原生轉譯器 oxc (JavaScript Oxidation Compiler,以 Rust 撰寫)隨後加入 SWC 與 esbuild 的行列,目前為 Rolldown(Vite 8 預設使用的打包工具)提供解析與轉換層。三者都刻意省略型別檢查:型別 檢查需要一次看到整個程式,而逐檔轉譯器永遠只看得到眼前這一個檔案。將檢查與轉譯分離, 可在熱路徑(開發時每次存檔)中獲得最快的轉換,同時在 CI 中只執行一次昂貴的檢查。
tsc --noEmit + SWC 的模式,以及 TypeScript 7 帶來的改變。 型別檢查與轉譯是效能特徵截然不同的兩個獨立關注點,而且這個落差是結構性的。只檢查單一 檔案並不夠:TypeScript 必須解析該檔案所依賴的 import,並跨這些檔案追蹤型別推斷,才能 確認 user.id 真的是 string,因此單次檢查的成本大致等同於檢查整個專案。轉譯則沒有 這個要求:SWC 或 esbuild 可以完全不開啟其他檔案,就剝離並降階單一檔案。
在這個結構性落差之上,實作方式能帶來多少改善並非固定不變。2026 年 7 月發布的 TypeScript 7.0,以 Go 撰寫的原生版本取代了原本以 JavaScript 撰寫的編譯器(開發代號 Project Corsa,預覽階段以 tsgo 之名釋出)。根據微軟自己的基準測試,檢查 VS Code 程式碼庫(約 150 萬行)所需的時間從 77.8 秒降到 7.5 秒,快了約 10 倍,而檢查的範圍與 規則的嚴格程度都沒有改變。這重新調整了本節的權衡:在 TypeScript 7 上,CI 中的 tsc --noEmit 遠比在 TypeScript 6 上便宜,若一個專案當初改用純 SWC 建置正是為了迴避 緩慢的 tsc 步驟,現在這個理由已經站不太住腳。全程式分析仍是必要的,因此檢查與轉譯 仍是兩個獨立的工作,但檢查那一半的成本剛剛下降了一個數量級。
將兩個關注點解耦,仍然可以把各自交給最適合的工具:
- 在開發環境:SWC 依需求轉換檔案,帶來快速的熱模組替換(Hot Module Replacement,HMR) 更新,通常每個檔案在 100 毫秒以下。
- 在 CI:
tsc --noEmit對整個專案執行一次,回報型別錯誤。若通過,SWC 產生可發布的輸出。
Vite(2.0,2021 年 2 月)是最早將這個分離模式設為預設的主要工具之一,以 esbuild 逐檔 轉譯 TypeScript,並將型別檢查留給編輯器或獨立執行的 tsc。Next.js 12(2021 年 10 月) 將同樣的分離模式帶進主流 React 框架,把預設編譯器從 Babel 切換到 SWC,且不需要任何 程式碼變更。根據 Vercel 的發布文章,這次切換帶來約 3 倍更快的 Fast Refresh 與約 5 倍 更快的正式環境建置。同一篇文章中另有一個數字,即以 Rust 進行編譯比 Babel 快 17 倍, 衡量的是原始轉換吞吐量,並非刷新時間的數字。若存在 .babelrc 檔案,Next.js 仍會自動 退回使用 Babel,為有自訂 Babel 外掛的專案保留相容性。
moduleResolution: "bundler" 為何存在。 TypeScript 的 node 解析模式模擬了 Node.js 中 require() 的運作方式:給定 import x from './foo',它會先嘗試 ./foo.js,再嘗試 ./foo/index.js,最後退回到 foo 的 package.json 中的 main 欄位。Vite 和 Webpack 等打包工具的解析方式不同。 它們遵守 package.json 的 exports 欄位(node 解析完全忽略此欄位),而現代大多數 雙格式套件都是靠這個欄位分別公告 ESM 與 CJS 的進入點。在 Vite 專案中使用 moduleResolution: "node16" 或 "node",會讓 TypeScript 對那些在建置時能正確解析的 import 發出錯誤的型別錯誤,因為型別檢查器套用的規則與打包工具並不一致。TypeScript 5.0 引入 moduleResolution: "bundler" 來填補這個落差:它會像打包工具一樣查閱 exports 欄位,讓型別檢查與打包對「某個 import 實際解析到哪個檔案」達成一致。
深入探討
執行期型別剝離
以上內容都假設瀏覽器或 Node.js 載入程式碼之前,會先執行一道建置步驟,把 .ts 轉成 .js。這個假設在後端與工具程式碼上已經站不住腳。Node.js 從 v22 起加入了直接執行 .ts 檔案的實驗性支援,在 v23.6(2025 年 1 月)取消旗標限制、可直接使用,並自 v24 (截至 2026 年的 LTS 版本線)起預設啟用。在內部,Node 使用一個叫 amaro 的模組,它是 @swc/wasm-typescript (SWC TypeScript 剖析器的 WebAssembly 版本)的包裝層,用來移除型別標注,並以等長的 空白取代,讓堆疊追蹤(stack trace)仍能指向正確的行號。這裡沒有型別檢查步驟:Node 只執行使用可剝離語法(erasable syntax)的 .ts 檔案,遇到型別檢查器才需要解析的 結構,例如會產生執行期程式碼的 enum 宣告與命名空間,就會報錯。
Bun 與 Deno 從第一個版本起就能直接執行 TypeScript,使用的是各自內建的轉譯器,而非 Node 的 amaro。隨著 Node 24 預設剝離型別,加上 Bun 與 Deno 原生執行 TypeScript,愈來 愈多後端與工具程式碼不再需要獨立的轉譯步驟。這些都不能取代 tsc --noEmit 捕捉型別 錯誤的功能;它們只是省去了過去讓 .ts 檔案成為合法 JavaScript 所需的那道步驟,而且 不適用於前端程式碼。前端程式碼仍然要送到只看得懂 JavaScript 的瀏覽器執行。
失敗模式
除了〈最佳實踐〉中提到的設定錯誤之外,還有一些問題只有在專案實際橫跨 tsc、SWC 或 esbuild,以及打包工具時才會浮現,因為這三者是用不同規則讀取同一份原始碼。
在 Next.js 專案中不必要地保留 .babelrc。.babelrc 檔案會讓 Next.js 對所有檔案停用 SWC 並退回 Babel,而不只是需要自訂外掛的 檔案。若只需要一個外掛,在承擔 Babel 完整效能代價之前,應先評估是否有對應的 SWC 外掛, 或 Next.js 內建的編譯器選項能提供相同功能。
const enum 與執行期命名空間在 SWC 與 esbuild 下會悄悄失效。tsc 會查找 const enum 的宣告(可能位於與 import 不同的檔案),並在每個使用處內聯 (inline)其數值。SWC 與 esbuild 逐檔轉譯,永遠看不到那個宣告,因此只會產生一般物件 而不是內聯數值,執行期輸出會與純 tsc 建置不同。請在 tsconfig.json 中設定 isolatedModules: true,讓 TypeScript 自己標記出 const enum 的使用,以及其他無法 在逐檔編譯下存活的結構(例如執行期命名空間合併),並在透過 SWC 或 esbuild 出檔的程式 碼中避免使用它們。
沒有 verbatimModuleSyntax 時,僅型別的 import 會被不一致地清除。 當一個檔案同時從同一個模組匯入型別與值時,TypeScript 的預設設定有時會因為這個 import 「看起來像」僅型別而將它省略,有時則不會,這取決於 isolatedModules 與 import 的寫法。 像 SWC 這類逐檔轉譯器只看得到 import 陳述式本身,必須自行猜測它在執行期是否存活;猜錯 過去曾導致「找不到模組」錯誤,以及值被悄悄遺漏。請設定 verbatimModuleSyntax: true (TypeScript 5.0+),並明確寫出 import type { Foo } from "./types" 語法,讓流程中 的每個工具讀到相同的意圖,而不必各自推斷。
SWC 與 tsc 的裝飾器中繼資料不同。 依賴 emitDecoratorMetadata 的函式庫,常見的是在執行期讀取參數設計時期型別的依賴 注入(dependency-injection)框架,需要編譯器在裝飾器轉換的同時輸出這份中繼資料。 tsc 完整支援這項功能。SWC 的裝飾器支援過去只涵蓋裝飾器轉換本身,未必符合 tsc 完整的中繼資料輸出,因此在 tsc 下能正常運作的裝飾器程式碼,換到 SWC 下可能出現 遺漏或泛用 Object 中繼資料的問題。在把裝飾器密集的專案移出 tsc 出檔之前,請查閱 SWC 目前文件中已知的裝飾器中繼資料落差。
當檢查與輸出分別透過不同工具執行時,source map 會出現偏移。tsc --noEmit 不產生任何輸出,因此對 source map 毫無貢獻;真正輸出程式碼的工具 (SWC、esbuild 或 Babel)會各自獨立產生自己的 map。如果該工具處理的是與原始碼不同的 中間形式,例如處理的是 Babel 轉換後的檔案而非原始 .ts,正式環境的堆疊追蹤就可能 指向錯誤的行號。每次變更負責最終輸出的工具之後,都應該在已知的行號丟出錯誤,並確認 瀏覽器或錯誤追蹤工具指向的是同一行,藉此驗證 source map。
延伸閱讀
- FEE-800 — 建置工具總覽:本文所屬的大型建置工具格局。
- FEE-801 — 打包工具(Webpack、Rollup、esbuild):打包工具如何在內部調用轉譯器。
- FEE-307 — ES 模組:
moduleResolution: "bundler"為之設計的模組格式。 - FEE-804 —
package.json欄位:exports、main、module——moduleResolution: "bundler"所查閱的欄位。
參考資料
- SWC 文件
- SWC 與 Babel 效能比較
- Babel @babel/preset-env
- Babel @babel/preset-typescript
- TypeScript tsconfig 參考
- TypeScript 5.0 — 宣布 moduleResolution: bundler
- TypeScript 模組解析指南
- 快 10 倍的 TypeScript(原生 Go 編譯器發布公告)
- TypeScript 7.0 發布公告
- Node.js 文件 — 模組:TypeScript
- Marvin Hagemeister,「加速 JavaScript 生態系:一次一個函式庫」
- Oxc — JavaScript 氧化編譯器
- Vite 8.0 發布公告(Rolldown)
- Next.js 編譯器架構
- Next.js 12 發布 — SWC 預設編譯器
- browserslist