G1Joshi/Agent-Skills

SWC

SWC（极速 Web 编译器）是一个基于 Rust 的可扩展平台。它是 Next.js 和 Deno 内部的编译器。

使用时机

• 高性能 JavaScript/TypeScript 转译：替换 Babel，使用基于 Rust 的编译器，速度快达 20 倍。
• Next.js 与现代打包工具流水线：转译 React JSX、TSX、现代 ECMAScript 特性以及 Webpack/Turbopack 资源。
• 编程式 AST 操作与代码生成：使用 @swc/core Node.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，以避免重复转译器运行时辅助函数桩。
• 务必在 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	在 .swcrc 中未启用对应标志的情况下使用了 TypeScript 语法（例如 JSX 或装饰器）	确保在 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 以触发目标架构的原生二进制文件获取。

参考资料

• SWC 文档