#配置 Rspack

Rspack 提供了与 webpack 相似的配置项，通过本章节，你可以了解 Rspack 配置的使用方式。

#配置文件

当你运行 Rspack 的命令行工具时，Rspack 会自动读取当前路径下的 rspack.config.* 文件。

一个基础的 Rspack 配置文件如下所示：

import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});

const { defineConfig } = require('@rspack/cli');

module.exports = defineConfig({
  entry: {
    main: './src/index.js',
  },
});

import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});

#配置文件格式

Rspack 支持以下配置文件格式：

• rspack.config.js: 默认为 CommonJS 格式，如果所在 package.json 的 type 为 "module" 则变成 ES modules 格式。
• rspack.config.ts: TypeScript 格式，参考 TypeScript 配置文件 了解更多。
• rspack.config.cjs: 强制为 CommonJS 格式。
• rspack.config.mjs: 强制为 ES modules 格式。

注意，Rspack 将首先搜索 JS 配置文件，然后才是 TS 配置文件。

CommonJS 和 ES modules的区别请参考 ES modules 和 CommonJS。

#扩展配置

参考扩展配置了解如何从其他文件或包中扩展配置。

#TypeScript 配置文件

在使用 rspack.config.ts 时，你可以选择以下任意一种方式：

#默认行为

Rspack CLI 从 1.5.0 版本开始内置对 TypeScript 配置的支持，默认使用 SWC 来将 TypeScript 代码转换为 CommonJS 格式的 JavaScript 代码。

如果你使用的 Rspack CLI 版本小于 1.5.0，建议升级到最新版本，无需再通过 ts-node 或 esbuild-register 加载配置文件，这些依赖可以被移除。

#原生支持

如果你使用的 JavaScript 运行时已经原生支持 TypeScript，你可以使用内置的 TS 转换来加载配置文件，确保模块解析行为与原生行为一致。

例如，Node.js 已经原生支持 TypeScript，你可以使用以下命令来使用 Node.js 原生加载器来加载配置文件：

• 对于原生支持 TypeScript 的 Node.js v22.18+ 和 v24.3+，你可以运行以下命令来加载 TS 配置：

{
  "scripts": {
    "build": "rspack build --configLoader=native"
  }
}

详见 Node.js - Running TypeScript Natively。

#配置类型检查

使用 defineConfig 工具函数来启用智能补全。对于 JavaScript 配置文件，你可以使用 // @ts-check 注释来启用类型检查。

import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});

// @ts-check
import { defineConfig } from '@rspack/cli';

export default defineConfig({
  entry: {
    main: './src/index.js',
  },
});

你也可以使用 JSDoc 来启用类型检查。

// @ts-check
/** @type {import('@rspack/cli').Configuration} */
const config = {
  entry: {
    main: './src/index.js',
  },
};
export default config;

#指定配置文件

Rspack 命令行支持通过 --config 选项来指定配置文件的名称。

例如，你需要在执行 build 时使用 rspack.prod.config.js 文件，可以在 package.json 中添加如下配置：

{
  "scripts": {
    "dev": "rspack serve",
    "build": "rspack build --config rspack.prod.config.js"
  }
}

也可以将 --config 选项缩写为 -c：

$ rspack build -c rspack.prod.config.js

#导出配置函数

Rspack 支持在 Rspack 配置文件中导出一个函数，你可以在函数中动态计算配置，并返回给 Rspack。

export default function (env, argv) {
  return {
    devtool: env.production ? 'source-map' : 'eval',
  };
}

从上述示例中可以看到，该函数接受两个入参：

• 第一个参数为 env，对应运行 CLI 命令时 --env 选项的值。
• 第二个参数为 argv，包含传递给 CLI 的所有选项。

#判断当前环境

除了通过 env 参数，通过 process.env.NODE_ENV 来判断当前环境是更常见的方式：

export default function (env, argv) {
  const isProduction = process.env.NODE_ENV === 'production';
  return {
    devtool: isProduction ? 'source-map' : 'eval',
  };
}

#合并配置

使用 Rspack 的 extends 选项或者 webpack-merge 包来合并多个 Rspack 配置。

#extends 选项

在使用 @rspack/cli 时，Rspack 提供了 extends 选项，允许你从其他文件或包中扩展配置。

export default {
  extends: './base.rspack.config.mjs',
  output: {
    filename: '[name].bundle.js',
  },
};

该选项仅在 @rspack/cli 中有效，查看 extends 了解更多用法。

#webpack-merge

webpack-merge 是一个社区库，用于合并多个 webpack 配置，也能用于合并 Rspack 配置。

首先安装 webpack-merge：

npm add webpack-merge -D

yarn add webpack-merge -D

pnpm add webpack-merge -D

bun add webpack-merge -D

deno add npm:webpack-merge -D

然后你就可以使用它的 merge 函数来合并配置：

import { merge } from 'webpack-merge';

const isDev = process.env.NODE_ENV === 'development';
const base = {};
const dev = {
  plugins: [new SomeDevPlugin()],
};

export default isDev ? merge(base, dev) : base;

查看 webpack-merge 文档 了解更多。