SWC
SWC（Speedy Web Compiler，快速網頁編譯器）是一個基於 Rust 的可擴展平台。它是 Next.js 和 Deno 內部的編譯器。
使用時機
- 高效能 JavaScript/TypeScript 轉譯：以 Rust 編譯器取代 Babel，速度最高可提升 20 倍。
- Next.js 與現代打包工具管線：轉譯 React JSX、TSX、現代 ECMAScript 功能以及 Webpack/Turbopack 的資產。
- 程式化 AST 操作與程式碼生成：使用
@swc/coreNode.js API 建構快速的客製化建置工具。 - 生產環境資產壓縮：使用
@swc/core壓縮器以極快速度壓縮 JS 和 CSS 套件。
快速入門
1. 最小化 .swcrc
{
"$schema": "https://json.schemastore.org/swcrc",
"jsc": {
"parser": {
"syntax": "typescript",
"tsx": true,
"decorators": true
},
"transform": {
"react": {
"runtime": "automatic"
}
},
"target": "es2022"
},
"minify": false
}
2. 透過 CLI 編譯
npx @swc/cli src -d dist
核心概念
生產環境 SWC 配置（.swcrc）
配置現代 TypeScript、React 19 JSX 執行時期以及模組轉譯：
{
"$schema": "https://json.schemastore.org/swcrc",
"jsc": {
"parser": {
"syntax": "typescript",
"tsx": true,
"decorators": true,
"dynamicImport": true
},
"transform": {
"react": {
"runtime": "automatic",
"refresh": true
}
},
"target": "es2022",
"loose": false,
"externalHelpers": true,
"keepClassNames": true,
"minify": {
"compress": {
"unused": true,
"drop_console": true
},
"mangle": true
}
},
"module": {
"type": "es6"
},
"minify": true,
"sourceMaps": true
}
使用 @swc/core API 進行程式化編譯
在 Node.js 腳本中非同步轉譯原始碼檔案：
import swc from "@swc/core";
import fs from "node:fs/promises";
async function compileTypeScript(filePath) {
const code = await fs.readFile(filePath, "utf-8");
const output = await swc.transform(code, {
filename: filePath,
sourceMaps: true,
jsc": {
parser: { syntax: "typescript", tsx: true },
target: "es2022",
},
module: { type: "commonjs" },
});
console.log("轉譯後的程式碼:\n", output.code);
if (output.map) {
console.log("已產生 Source Map");
}
}
compileTypeScript("./src/index.ts");
高速 CLI 轉譯
直接使用 SWC 命令列編譯目錄樹：
# 將 src/ 轉譯至 dist/，同時產生 Source Map
npx swc src -d dist --copy-files --source-maps
# 使用 swcpack 轉譯並打包
npx swc src/index.ts -o dist/bundle.js --minify
常見模式
使用 @swc/jest 加速 Jest 測試
問題：使用 ts-jest 進行 TypeScript 轉譯會導致測試套件執行速度極慢。
解決方案：將 ts-jest 替換為 @swc/jest。
// jest.config.js
module.exports = {
transform: {
"^.+\\.(t|j)sx?$": [
"@swc/jest",
{
jsc: {
transform: {
react: { runtime: "automatic" },
},
},
},
],
},
};
SWC 打包與壓縮管線
問題：需要為生產建置腳本提供快速的壓縮功能。
解決方案：在 .swcrc 中啟用 minify 選項。
{
"minify": true,
"jsc": {
"minify": {
"compress": {
"drop_console": true
},
"mangle": true
}
}
}
最佳實務（2026 年）
- 務必 安裝
@swc/helpers並啟用externalHelpers: true，以避免重複轉譯器執行時期 Helper 樁的程式碼。 - 務必 在 CI/CD 管線中將 SWC 與
tsc --noEmit搭配使用，因為 SWC 在轉譯程式碼時不會執行型別檢查。 - 務必 將
target配置為"es2022"或更新版本，以充分利用原生的現代瀏覽器功能。 - 務必 使用
@swc/jest或@swc/register大幅加快單元測試的執行速度。 - 切勿 在非必要的情況下依賴 Babel 外掛；請檢查是否有原生 SWC 外掛（Wasm 外掛）可用。
- 切勿 將
.swc建置快取目錄提交至 Git 儲存庫。 - 切勿 在沒有產生 Source Map 的情況下執行 SWC 壓縮，以便進行生產環境除錯。
疑難排解
| 錯誤 / 症狀 | 原因 | 解決方案 |
|---|---|---|
failed to handle: error parsing typescript | 使用 TypeScript 語法（例如 JSX 或裝飾器）但未在 .swcrc 中啟用對應標記 | 確保 jsc.parser 中存在 "syntax": "typescript"、"tsx": true 和 "decorators": true。 |
裝飾器元資料未發出（Reflect.getMetadata 傳回 undefined） | transform.legacyDecorator 和 transform.decoratorMetadata 未配置 | 在 jsc.transform 中設定 "legacyDecorator": true 和 "decoratorMetadata": true。 |
Cannot find module '@swc/core-darwin-arm64' | 在 npm/yarn 安裝過程中，原生二進制檔案安裝失敗 | 執行 npm install --force @swc/core 以觸發針對目標架構的原生二進制檔案下載。 |