SWC 配置 #

配置文件结构 #

SWC 配置文件 .swcrc 的完整结构:

json
{
  "jsc": {
    "parser": { },
    "transform": { },
    "target": "es5",
    "loose": false,
    "externalHelpers": false,
    "keepClassNames": false
  },
  "module": { },
  "minify": false,
  "sourceMaps": false,
  "test": ".*\\.js$",
  "exclude": [],
  "env": { }
}

jsc 配置 #

jsc(JavaScript Compiler)是 SWC 的核心配置部分。

parser 配置 #

ECMAScript 解析器 #

json
{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": false,
      "dynamicImport": false,
      "privateMethod": false,
      "functionBind": false,
      "exportDefaultFrom": false,
      "exportNamespaceFrom": false,
      "decorators": false,
      "decoratorsBeforeExport": false,
      "topLevelAwait": false,
      "importMeta": false
    }
  }
}
选项 类型 默认值 描述
syntax string “ecmascript” 语法类型
jsx boolean false 启用 JSX 解析
dynamicImport boolean false 启用动态导入
privateMethod boolean false 启用私有方法
functionBind boolean false 启用函数绑定 ::
exportDefaultFrom boolean false 启用 export default from
exportNamespaceFrom boolean false 启用 export * as ns from
decorators boolean false 启用装饰器
decoratorsBeforeExport boolean false 装饰器在导出前
topLevelAwait boolean false 启用顶层 await
importMeta boolean false 启用 import.meta

TypeScript 解析器 #

json
{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": false,
      "decorators": false,
      "dynamicImport": false,
      "dts": false,
      "noEarlyErrors": false
    }
  }
}
选项 类型 默认值 描述
syntax string “typescript” 语法类型
tsx boolean false 启用 TSX
decorators boolean false 启用装饰器
dynamicImport boolean false 启用动态导入
dts boolean false 解析 .d.ts 文件
noEarlyErrors boolean false 延迟错误报告

transform 配置 #

React 转换 #

json
{
  "jsc": {
    "transform": {
      "react": {
        "runtime": "classic",
        "importSource": "react",
        "pragma": "React.createElement",
        "pragmaFrag": "React.Fragment",
        "throwIfNamespace": true,
        "development": false,
        "useBuiltins": false,
        "refresh": {
          "refreshReg": "$RefreshReg$",
          "refreshSig": "$RefreshSig$",
          "emitFullSignatures": false
        }
      }
    }
  }
}
选项 类型 默认值 描述
runtime string “classic” JSX 运行时模式
importSource string “react” 导入源
pragma string “React.createElement” JSX 元素函数
pragmaFrag string “React.Fragment” JSX 片段函数
throwIfNamespace boolean true 命名空间标签抛错
development boolean false 开发模式
useBuiltins boolean false 使用内置方法

运行时模式 #

json
// Classic 运行时
{
  "jsc": {
    "transform": {
      "react": {
        "runtime": "classic"
      }
    }
  }
}

// Automatic 运行时(推荐)
{
  "jsc": {
    "transform": {
      "react": {
        "runtime": "automatic"
      }
    }
  }
}

装饰器配置 #

json
{
  "jsc": {
    "transform": {
      "decoratorVersion": "2022-03",
      "legacyDecorator": true
    }
  }
}

target 配置 #

指定编译目标:

json
{
  "jsc": {
    "target": "es2015"
  }
}

支持的目标值 #

目标 描述
es5 ES5(IE11 兼容)
es2015 ES2015(ES6)
es2016 ES2016
es2017 ES2017
es2018 ES2018
es2019 ES2019
es2020 ES2020
es2021 ES2021
es2022 ES2022

loose 配置 #

启用宽松模式,生成更简单但可能不完全符合规范的代码:

json
{
  "jsc": {
    "loose": true
  }
}

externalHelpers 配置 #

使用外部辅助函数:

json
{
  "jsc": {
    "externalHelpers": true
  }
}

需要安装 @swc/helpers

bash
npm install @swc/helpers

keepClassNames 配置 #

保留类名(用于反射等场景):

json
{
  "jsc": {
    "keepClassNames": true
  }
}

experimental 配置 #

实验性功能配置:

json
{
  "jsc": {
    "experimental": {
      "plugins": [
        ["@swc/plugin-my-plugin", { "option": "value" }]
      ],
      "cacheRoot": "/tmp/swc-cache"
    }
  }
}

module 配置 #

CommonJS 模块 #

json
{
  "module": {
    "type": "commonjs",
    "strict": false,
    "strictMode": true,
    "lazy": false,
    "noInterop": false,
    "ignoreDynamic": true,
    "allowTopLevelThis": false
  }
}
选项 类型 默认值 描述
type string - 模块类型
strict boolean false 严格模式导出
strictMode boolean true 添加 “use strict”
lazy boolean false 延迟加载
noInterop boolean false 禁用 interop
ignoreDynamic boolean true 忽略动态导入
allowTopLevelThis boolean false 允许顶层 this

ES Modules #

json
{
  "module": {
    "type": "es6",
    "strict": false,
    "noInterop": false
  }
}

AMD 模块 #

json
{
  "module": {
    "type": "amd",
    "moduleId": "my-module",
    "strict": false
  }
}

UMD 模块 #

json
{
  "module": {
    "type": "umd",
    "moduleId": "my-module",
    "globals": {
      "lodash": "_",
      "jquery": "$"
    }
  }
}

SystemJS 模块 #

json
{
  "module": {
    "type": "systemjs"
  }
}

minify 配置 #

基本压缩配置 #

json
{
  "minify": true
}

详细压缩配置 #

json
{
  "jsc": {
    "minify": {
      "compress": {
        "defaults": true,
        "arrows": true,
        "arguments": false,
        "booleans": true,
        "collapse_vars": true,
        "comparisons": true,
        "computed_props": true,
        "conditionals": true,
        "dead_code": true,
        "drop_console": false,
        "drop_debugger": true,
        "evaluate": true,
        "hoist_funs": true,
        "hoist_props": true,
        "hoist_vars": false,
        "if_return": true,
        "join_vars": true,
        "keep_classnames": false,
        "keep_fnames": false,
        "loops": true,
        "negate_iife": true,
        "properties": true,
        "reduce_funcs": true,
        "reduce_vars": true,
        "sequences": true,
        "side_effects": true,
        "switches": true,
        "top_retain": [],
        "typeofs": true,
        "unused": true
      },
      "mangle": {
        "toplevel": false,
        "keep_classnames": false,
        "keep_fnames": false,
        "keep_private_props": false,
        "ie8": false,
        "safari10": false,
        "properties": {
          "regex": "^_",
          "reserved": []
        }
      },
      "format": {
        "comments": "some",
        "ecma": 5,
        "indent_level": 2,
        "preamble": "",
        "quote_style": 0
      }
    }
  },
  "minify": true
}

压缩选项详解 #

compress 选项 #

选项 默认值 描述
defaults true 启用默认优化
arrows true 优化箭头函数
booleans true 优化布尔值
collapse_vars true 折叠变量
comparisons true 优化比较表达式
conditionals true 优化条件表达式
dead_code true 移除死代码
drop_console false 移除 console
drop_debugger true 移除 debugger
evaluate true 计算常量表达式
loops true 优化循环
unused true 移除未使用代码

mangle 选项 #

选项 默认值 描述
toplevel false 混淆顶层作用域
keep_classnames false 保留类名
keep_fnames false 保留函数名
keep_private_props false 保留私有属性
ie8 false IE8 兼容
safari10 false Safari 10 兼容

sourceMaps 配置 #

基本配置 #

json
{
  "sourceMaps": true
}

配置选项 #

描述
true 生成独立的 .map 文件
"inline" 内联到 JS 文件中
"hidden" 生成但不添加注释链接
false 不生成 source map

高级配置 #

json
{
  "sourceMaps": true,
  "sourceRoot": "/src",
  "sourceFileName": "index.js",
  "inlineSourcesContent": true
}

env 配置 #

环境特定配置:

json
{
  "env": {
    "targets": {
      "chrome": "80",
      "firefox": "78",
      "safari": "14",
      "edge": "88",
      "node": "14"
    },
    "coreJs": 3,
    "mode": "usage",
    "debug": true
  }
}

targets 配置 #

json
{
  "env": {
    "targets": {
      "chrome": "80",
      "node": "14"
    }
  }
}

使用 browserslist #

json
{
  "env": {
    "targets": {
      "browsers": ["> 1%", "last 2 versions", "not dead"]
    }
  }
}

coreJs 配置 #

json
{
  "env": {
    "coreJs": "3.29",
    "mode": "usage"
  }
}

test 和 exclude 配置 #

test 配置 #

指定匹配的文件:

json
{
  "test": ".*\\.js$",
  "exclude": []
}

exclude 配置 #

排除特定文件:

json
{
  "test": ".*\\.js$",
  "exclude": [
    "node_modules",
    "**/*.test.js",
    "**/*.spec.js"
  ]
}

完整配置示例 #

JavaScript 项目 #

json
{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": true,
      "dynamicImport": true
    },
    "target": "es2015",
    "loose": false,
    "externalHelpers": false
  },
  "module": {
    "type": "commonjs",
    "strictMode": true
  },
  "sourceMaps": true,
  "minify": false
}

TypeScript 项目 #

json
{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": true,
      "decorators": true,
      "dynamicImport": true
    },
    "transform": {
      "react": {
        "runtime": "automatic"
      }
    },
    "target": "es2015",
    "keepClassNames": true
  },
  "module": {
    "type": "es6"
  },
  "sourceMaps": true
}

React 项目 #

json
{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": true,
      "dynamicImport": true
    },
    "transform": {
      "react": {
        "runtime": "automatic",
        "importSource": "react",
        "development": false
      }
    },
    "target": "es2015"
  },
  "module": {
    "type": "es6"
  },
  "sourceMaps": "inline"
}

生产环境 #

json
{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "tsx": true
    },
    "target": "es2015",
    "minify": {
      "compress": {
        "defaults": true,
        "drop_console": true,
        "drop_debugger": true,
        "unused": true
      },
      "mangle": {
        "toplevel": true
      }
    }
  },
  "module": {
    "type": "commonjs"
  },
  "minify": true,
  "sourceMaps": true
}

库开发 #

json
{
  "jsc": {
    "parser": {
      "syntax": "typescript"
    },
    "target": "es2015",
    "externalHelpers": true,
    "keepClassNames": true
  },
  "module": {
    "type": "commonjs"
  },
  "sourceMaps": true
}

配置继承 #

多配置文件 #

json
// .swcrc
{
  "jsc": {
    "parser": {
      "syntax": "typescript"
    },
    "target": "es2015"
  }
}
json
// src/.swcrc(覆盖父配置)
{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": true
    }
  }
}

使用 extends #

json
{
  "extends": "./base.swcrc",
  "jsc": {
    "target": "es2020"
  }
}

下一步 #

现在你已经掌握了 SWC 的所有配置选项,接下来学习 编译与转译 深入了解编译功能!

最后更新:2026-03-28