SWC 安装与配置 #

安装方式 #

SWC 提供多种安装方式，可以根据你的需求选择。

使用 npm #

bash

# 全局安装
npm install -g @swc/cli @swc/core

# 项目安装（推荐）
npm install --save-dev @swc/cli @swc/core

使用 yarn #

bash

# 全局安装
yarn global add @swc/cli @swc/core

# 项目安装（推荐）
yarn add -D @swc/cli @swc/core

使用 pnpm #

bash

# 全局安装
pnpm add -g @swc/cli @swc/core

# 项目安装（推荐）
pnpm add -D @swc/cli @swc/core

包说明 #

SWC 由两个主要包组成：

text

┌─────────────────────────────────────────────────────────────┐
│                      SWC 包结构                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  @swc/core                                                  │
│  ├── 核心编译功能                                            │
│  ├── Rust 编译器的 Node.js 绑定                              │
│  ├── 支持多平台二进制文件                                     │
│  └── 提供 JavaScript API                                    │
│                                                              │
│  @swc/cli                                                   │
│  ├── 命令行工具                                              │
│  ├── 提供交互式命令                                          │
│  ├── 文件监听功能                                            │
│  └── 输出配置选项                                            │
│                                                              │
└─────────────────────────────────────────────────────────────┘

快速开始 #

1. 创建项目 #

bash

# 创建项目目录
mkdir my-swc-project
cd my-swc-project

# 初始化 package.json
npm init -y

2. 安装依赖 #

bash

npm install --save-dev @swc/cli @swc/core

3. 创建源文件 #

javascript

// src/index.js
const greet = (name) => {
  return `Hello, ${name}!`;
};

class Person {
  constructor(name) {
    this.name = name;
  }

  sayHello() {
    return greet(this.name);
  }
}

export { Person, greet };

4. 运行编译 #

bash

# 编译单个文件
npx swc src/index.js -o dist/index.js

# 编译整个目录
npx swc src -d dist

5. 查看结果 #

javascript

// dist/index.js
"use strict";
Object.defineProperty(exports, "__esModule", {
    value: true
});
Object.defineProperty(exports, "Person", {
    enumerable: true,
    get: function() {
        return Person;
    }
});
Object.defineProperty(exports, "greet", {
    enumerable: true,
    get: function() {
        return greet;
    }
});
const greet = (name)=>{
    return `Hello, ${name}!`;
};
class Person {
    constructor(name){
        this.name = name;
    }
    sayHello() {
        return greet(this.name);
    }
}

配置文件 #

创建配置文件 #

SWC 使用 .swcrc 作为配置文件：

bash

# 在项目根目录创建配置文件
touch .swcrc

基本配置结构 #

json

{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": false,
      "dynamicImport": false,
      "privateMethod": false,
      "functionBind": false,
      "exportDefaultFrom": false,
      "exportNamespaceFrom": false,
      "decorators": false,
      "decoratorsBeforeExport": false,
      "topLevelAwait": false
    },
    "transform": null,
    "target": "es5",
    "loose": false,
    "externalHelpers": false,
    "keepClassNames": false
  },
  "module": {
    "type": "commonjs",
    "strict": false,
    "strictMode": true,
    "lazy": false,
    "noInterop": false
  },
  "sourceMaps": false,
  "minify": false
}

配置文件位置 #

text

my-project/
├── .swcrc              # 主配置文件
├── src/
│   ├── .swcrc          # src 目录特定配置
│   ├── index.js
│   └── utils/
│       └── .swcrc      # utils 目录特定配置
└── dist/

常用配置示例 #

JavaScript 项目 #

json

{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": true
    },
    "target": "es2015"
  },
  "module": {
    "type": "commonjs"
  },
  "sourceMaps": true
}

TypeScript 项目 #

json

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

React 项目 #

json

{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": true
    },
    "transform": {
      "react": {
        "runtime": "automatic",
        "importSource": "react",
        "pragma": "React.createElement",
        "pragmaFrag": "React.Fragment",
        "throwIfNamespace": true,
        "development": false,
        "useBuiltins": false
      }
    },
    "target": "es2015"
  },
  "module": {
    "type": "es6"
  }
}

库开发配置 #

json

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

package.json 集成 #

添加脚本命令 #

json

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "build": "swc src -d dist",
    "build:watch": "swc src -d dist -w",
    "build:prod": "swc src -d dist --no-config -C minify=true",
    "dev": "swc src -d dist -w -s inline"
  },
  "devDependencies": {
    "@swc/cli": "^0.1.62",
    "@swc/core": "^1.3.35"
  }
}

运行脚本 #

bash

# 开发构建
npm run build

# 监听模式
npm run build:watch

# 生产构建
npm run build:prod

# 开发模式（带 source map）
npm run dev

目标环境配置 #

ES5 目标 #

json

{
  "jsc": {
    "target": "es5"
  }
}

ES2015 目标 #

json

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

现代浏览器目标 #

json

{
  "jsc": {
    "target": "es2020"
  }
}

支持的目标值 #

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

模块类型配置 #

CommonJS #

json

{
  "module": {
    "type": "commonjs",
    "strict": false,
    "strictMode": true,
    "lazy": false,
    "noInterop": false
  }
}

ES Modules #

json

{
  "module": {
    "type": "es6"
  }
}

UMD #

json

{
  "module": {
    "type": "umd"
  }
}

AMD #

json

{
  "module": {
    "type": "amd",
    "moduleId": "my-module"
  }
}

Source Map 配置 #

启用 Source Map #

json

{
  "sourceMaps": true
}

内联 Source Map #

json

{
  "sourceMaps": "inline"
}

Source Map 选项 #

json

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

使用 JavaScript API #

基本用法 #

javascript

const swc = require('@swc/core');

// 编译字符串
const result = await swc.transform('const x = 1;', {
  jsc: {
    parser: {
      syntax: 'ecmascript'
    },
    target: 'es2015'
  }
});

console.log(result.code);

编译文件 #

javascript

const swc = require('@swc/core');
const fs = require('fs');

const result = await swc.parseFile('./src/index.js', {
  syntax: 'ecmascript'
});

console.log(result);

使用配置文件 #

javascript

const swc = require('@swc/core');

const result = await swc.transform('const x = 1;', {
  filename: 'index.js',
  configFile: './.swcrc'
});

同步 API #

javascript

const swc = require('@swc/core');

const result = swc.transformSync('const x = 1;', {
  jsc: {
    parser: {
      syntax: 'ecmascript'
    },
    target: 'es2015'
  }
});

console.log(result.code);

从 Babel 迁移 #

安装 SWC #

bash

npm uninstall @babel/core @babel/cli @babel/preset-env
npm install --save-dev @swc/cli @swc/core

转换配置 #

Babel 配置：

javascript

// babel.config.js
module.exports = {
  presets: [
    ['@babel/preset-env', { targets: { node: 'current' } }],
    '@babel/preset-typescript'
  ],
  plugins: ['@babel/plugin-proposal-decorators']
};

等效的 SWC 配置：

json

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true
    },
    "target": "es2015"
  },
  "module": {
    "type": "commonjs"
  }
}

更新脚本 #

json

{
  "scripts": {
    "build": "swc src -d dist",
    "dev": "swc src -d dist -w"
  }
}

常见问题 #

问题一：找不到原生模块 #

bash

Error: Cannot find module '@swc/core-darwin-x64'

解决方案：

bash

# 重新安装
npm rebuild @swc/core

# 或删除 node_modules 重新安装
rm -rf node_modules
npm install

问题二：配置文件不生效 #

检查项：

确认 .swcrc 在项目根目录
检查 JSON 格式是否正确
确认没有命令行参数覆盖配置

问题三：装饰器不工作 #

json

{
  "jsc": {
    "parser": {
      "syntax": "typescript",
      "decorators": true
    },
    "transform": {
      "legacyDecorator": true
    }
  }
}

问题四：JSX 转换问题 #

json

{
  "jsc": {
    "parser": {
      "syntax": "ecmascript",
      "jsx": true
    },
    "transform": {
      "react": {
        "runtime": "automatic",
        "importSource": "react"
      }
    }
  }
}

验证安装 #

检查版本 #

bash

npx swc --version

测试编译 #

bash

echo "const x = 1;" | npx swc

检查配置 #

bash

npx swc --show-config

下一步 #

现在你已经完成了 SWC 的安装和配置，接下来学习命令行工具掌握更多命令行操作！