#Optimization

优化：该选项用于自定义优化配置。你可以通过 optimization 来自定义优化配置。默认情况下，Rspack 会根据 mode 来选择合适的优化配置。

#optimization.moduleIds

• 类型： 'natural' | 'named' | 'deterministic'
• 默认值：production 模式 为'deterministic', development 模式 为'named'

设置 Rspack 在生成模块 id 时使用的算法。

支持以下字符串值：

export default {
  optimization: {
    moduleIds: 'deterministic',
  },
};

#optimization.chunkIds

• 类型： 'natural' | 'named' | 'deterministic' | 'size' | 'total-size'
• 默认值：development 模式 为'named', production 模式 为'deterministic'

设置 Rspack 在生成 Chunk id 时使用的算法。

支持以下字符串值：

export default {
  optimization: {
    chunkIds: 'deterministic',
  },
};

#optimization.mergeDuplicateChunks

• 类型： boolean
• 默认值：true

是否合并重复的 chunks，将 optimization.mergeDuplicateChunks 设置成 false 来关闭该优化。

export default {
  optimization: {
    mergeDuplicateChunks: false,
  },
};

#optimization.minimize

• 类型： boolean
• 默认值：production 模式 为true, development 模式 为false

是否使用 optimization.minimizer 中声明的压缩器对产物进行压缩。

export default {
  optimization: {
    minimize: true,
  },
};

#optimization.minimizer

• 类型： Array<Plugin>
• 默认值：[new SwcJsMinimizerRspackPlugin(), new LightningCssMinimizerRspackPlugin()]

自定义压缩器。默认使用 rspack.SwcJsMinimizerRspackPlugin 和 rspack.LightningCssMinimizerRspackPlugin。

当设置了 optimization.minimizer 时，默认的压缩器会被禁用。

import TerserPlugin from 'terser-webpack-plugin';

export default {
  optimization: {
    minimizer: [new TerserPlugin()],
  },
};

使用 Rspack 内置的压缩器，并自定义压缩选项：

import { rspack } from '@rspack/core';

export default {
  optimization: {
    // 当声明了 `optimization.minimizer`，默认压缩器会被禁用
    // 但你可以配合使用 '...'，它代表默认压缩器
    minimizer: [
      new rspack.SwcJsMinimizerRspackPlugin({
        minimizerOptions: {
          format: {
            comments: false,
          },
        },
      }),
      new rspack.LightningCssMinimizerRspackPlugin({
        minimizerOptions: {
          errorRecovery: false,
        },
      }),
    ],
  },
};

#optimization.removeAvailableModules

• 类型： boolean
• 默认值：true

是否检测并移除那些已经存在于父 chunks 中的模块。这项优化有助于减少打包产物中的重复模块，这通常可以优化整体的构建性能（通过减小了后续 chunk 优化的计算量）并减小产物体积。

这项优化默认开启，如果需要禁用，可以将 optimization.removeAvailableModules 设置为 false：

export default {
  optimization: {
    removeAvailableModules: false,
  },
};

#optimization.removeEmptyChunks

• 类型： boolean
• 默认值：true

检测并移除打包过程中产生的空 Chunk。将 optimization.removeEmptyChunks 设置为 false 来禁用该优化。

export default {
  optimization: {
    removeEmptyChunks: false,
  },
};

#optimization.runtimeChunk

• 类型： boolean | string | { name: string } | { name: (entrypoint: { name: string }) => string }
• 默认值：false

用来控制 Rspack 的 runtime chunk 如何生成。

默认为 false，这意味着运行时代码会被内联到入口的 chunks 中。

设置为 true 或 'multiple' 会为每个入口添加一个仅包含运行时的额外 chunk。该设置等同于：

export default {
  optimization: {
    runtimeChunk: {
      name: entrypoint => `runtime~${entrypoint.name}`,
    },
  },
};

设置为 'single' 会将所有入口的运行时代码抽离到一个单独的 chunk。该设置等同于：

export default {
  optimization: {
    runtimeChunk: 'runtime',
  },
};

设置为对象时，可以提供 name 属性，该属性代表 runtime chunk 的名称。

export default {
  optimization: {
    runtimeChunk: {
      // 这将生成一个名为 `my-name.js` 的 chunk
      name: 'my-name',
    },
  },
};

#optimization.realContentHash

• 类型： boolean | 'flag'
• 默认值：production 模式 为true, development 模式 为false

在产物处理完成后，添加额外的哈希计算步骤根据产物的文件内容计算该产物的哈希。该功能在生产环境下会默认开启。

如果将 realContentHash 设置为 false，则使用编译流程中的内部数据计算哈希，在某些情况下，即使产物内容完全一致也可能导致哈希变化。

export default {
  //...
  optimization: {
    realContentHash: true,
  },
};

#optimization.splitChunks

• 类型： false | object

Rspack 支持通过 optimization.splitChunks 配置项来对 Chunk 进行拆分。

该优化选项默认情况下是开启的，你可以将其设为 false 来关闭它。

有关配置此行为的可用选项，请参见 SplitChunksPlugin 页面。

#optimization.providedExports

• 类型： boolean
• 默认值：true

开启后 Rspack 将会分析模块提供哪些导出，包括重导出模块，引用模块不存在的导出时会发出提示。默认情况下，optimization.providedExports 已启用，该分析会增加构建时间，你可以考虑在 development 模式中关闭该配置，关闭后有可能会遇到SideEffects 章节运行时循环依赖的错误。

export default {
  //...
  optimization: {
    providedExports: false,
  },
};

#optimization.sideEffects

• 类型： boolean | 'flag'
• 默认值：production 模式 为true, development 模式 为'flag'

如果你只希望 Rspack 使用手动指定的 sideEffects 标志（通过 package.json 和 module.rule.sideEffects），而不分析源代码，可以这样配置：

export default {
  //...
  optimization: {
    sideEffects: 'flag',
  },
};

配置为 flag 会让 Rspack 仅识别 package.json 中的 sideEffects 标志或者 module.rule.sideEffects（模块配置中的规则），以跳过那些被标记为没有副作用但未被使用的模块。

配置为 true 会让 Rspack 除了识别用户主动标记以外，还会尝试分析未被标记的 module 源码是否包含副作用。

export default {
  //...
  optimization: {
    sideEffects: true,
  },
};

#optimization.usedExports

• 类型： boolean | 'global'
• 默认值：production 模式 为true, development 模式 为false

告诉 Rspack 对每个模块确定使用的导出。这取决于 optimization.providedExports。 optimization.usedExports 收集的信息被其他优化或代码生成使用，即不会为未使用的导出生成导出信息，当所有用法兼容时，导出名称会被缩短为单个字符标识符。压缩器中的死代码消除将受益于此，并且可以删除未使用的导出。

export default {
  //...
  optimization: {
    usedExports: false,
  },
};

如果需要在运行时取消使用的导出分析：

export default {
  //...
  optimization: {
    usedExports: 'global',
  },
};

#optimization.mangleExports

• 类型： boolean | 'deterministic' | 'size'
• 默认值：production 模式 为deterministic, development 模式 为false

optimization.mangleExports 允许控制导出名称的混淆。

支持以下选项：

#optimization.innerGraph

• 类型： boolean
• 默认值：production 模式 为true, development 模式 为false

optimization.innerGraph 告诉 Rspack 是否对变量传递进行更详细的分析，这有助于 Rspack 识别未使用的模块导出，从而减少打包产物的体积。

例如：

import { value } from 'lib';

const value2 = value;

function f1() {
  console.log(value);
}

function f2() {
  console.log(value2);
}

这里我们将 value 赋值给了 value2，value2 和 value 也分别在函数 f2 和 f1 中被访问，但函数没有被调用，因此没有使用到 value2 和 value，因此 value 的导入是可以被删除的。

#optimization.concatenateModules

• 类型： boolean
• 默认值：production 模式 为true, development 模式 为false

开启模块拼接优化，允许将多个模块拼接成单个模块以降低产物体积，提升压缩效率。此优化需要开启 optimization.providedExports 和 optimization.usedExports。默认情况下，optimization.concatenateModules 在 production 模式下启用，其它模式则禁用。

export default {
  optimization: {
    concatenateModules: false,
  },
};

#optimization.nodeEnv

• 类型： boolean | string
• 默认值：false

Rspack 将 process.env.NODE_ENV 设置为给定的字符串。除非该值被明确设置为 false，否则 optimization.nodeEnv 将使用 DefinePlugin。 optimization.nodeEnv 的默认值为 mode，否则将设置为 'production'。

可能的值：

• 任意字符串：设置 process.env.NODE_ENV 的值。
• false：不设置 process.env.NODE_ENV 的值。

export default {
  //...
  optimization: {
    nodeEnv: 'production',
  },
};

#optimization.emitOnErrors

• 类型： boolean
• 默认值：production 模式 为false, development 模式 为true

开启 optimization.emitOnErrors 时，即使编译过程中发生错误，Rspack 也会生成产物。这些错误会被注入到产物代码中，运行它们时会抛出错误。

export default {
  optimization: {
    emitOnErrors: true,
  },
};

#optimization.avoidEntryIife

• 类型： boolean
• 默认值：false

使用 optimization.avoidEntryIife 可以避免在需要时将入口模块包装在 IIFE 中（在 rspack_plugin_javascript 中搜索 "This entry needs to be wrapped in an IIFE because"）。这种方法有助于优化 JavaScript 引擎的性能，并在构建 ESM 库时保证 tree shaking 生效。

目前，optimization.avoidEntryIife 只能优化单个入口模块及其他模块共存时的 IIFE。

export default {
  //...
  optimization: {
    avoidEntryIife: true,
  },
};