#Devtool

devtool 用于控制 Rspack 为输出代码生成哪些调试信息，包括是否生成 source map，以及 source map 的输出方式和映射精度。不同的配置会影响浏览器开发工具和错误监控工具将打包代码还原到原始源码的能力，也会影响构建速度以及源码暴露风险。

• 类型：

type Devtool = string | false;

• 默认值： development 模式为 cheap-module-source-map，production 模式为 false

#推荐配置

以下示例通过 process.env.NODE_ENV 区分开发和生产环境。

#仅开发环境启用

如果仅在开发阶段需要调试信息，生产环境不需要生成 source map，使用以下配置：

const isDev = process.env.NODE_ENV === 'development';

export default {
  devtool: isDev ? 'cheap-module-source-map' : false,
};

• 开发环境： 使用 cheap-module-source-map，生成行级 source map，在调试精度和构建速度之间取得平衡。
• 生产环境： 设为 false，不生成 source map，也不会增加 source map 的生成开销。

#全部禁用

如果两个环境都不需要 source map，使用以下配置：

export default {
  devtool: false,
};

该配置的构建开销最低，也不会输出 .map 文件。缺点是浏览器报错和生产错误堆栈只能指向打包后的代码，无法还原到原始源码。

#全部启用

如果开发阶段需要快速的 source map，同时希望在生产环境获得完整的行列映射，使用以下配置：

const isDev = process.env.NODE_ENV === 'development';

export default {
  devtool: isDev ? 'cheap-module-source-map' : 'source-map',
};

• 开发环境： 使用构建速度更快的 cheap-module-source-map。
• 生产环境： 使用 source-map，生成包含行列映射的独立 .map 文件，并在 bundle 中添加 sourceMappingURL 注释。只要 .map 文件可访问，浏览器开发工具就能自动加载它。该配置适合直接调试生产代码，但会增加构建时间，并可能向用户暴露源码。

#生产环境隐藏引用

如果生产环境需要 source map 来还原错误堆栈，但不希望浏览器从 bundle 中自动发现它，使用以下配置：

const isDev = process.env.NODE_ENV === 'development';

export default {
  devtool: isDev ? 'cheap-module-source-map' : 'hidden-source-map',
};

• 开发环境： 使用构建速度更快的 cheap-module-source-map。
• 生产环境： 使用 hidden-source-map，生成包含完整行列映射的独立 .map 文件，但不在 bundle 中添加 //# sourceMappingURL 注释。该配置适合将 source map 私下上传到错误监控服务，用于还原生产错误堆栈。

#常用值

下表比较了常用配置的映射精度、输出方式和适用场景。

#修饰符

不带修饰符的 source-map 会生成包含行列映射的独立 .map 文件，并在 bundle 中添加 sourceMappingURL 注释。你可以添加以下修饰符来改变生成方式、映射精度或 map 内容。

#eval

将每个模块包装在 eval() 中。当它与 source-map 组合为 eval-source-map 时，每个模块的 source map 会以 Data URL 的形式写入对应的 eval()，从而避免合并 chunk 级 source map，提升重新构建速度。该修饰符通常只用于开发环境。

单独使用 devtool: 'eval' 时不会生成 source map，而是通过 //# sourceURL 为每个模块提供可读的模块名称，只能定位到模块，不能映射回原始源码。

#inline

将 source map 以 Data URL 的形式内联到 bundle 中，不生成独立的 .map 文件，例如 inline-source-map。这便于传输单个文件，但会明显增大 bundle 体积。默认情况下，source map 还会把源码内容一并包含在 bundle 中；与 nosources 组合时除外。因此，该修饰符通常只用于开发或测试。

#hidden

生成独立的 .map 文件，但不在 bundle 中添加 //# sourceMappingURL 注释，例如 hidden-source-map。浏览器不会自动发现该文件，适合将 source map 私下上传到错误监控服务。它不会阻止用户直接访问已公开部署的 .map 文件。

#nosources

从 source map 中移除 sourcesContent，例如 nosources-source-map。map 仍然包含原始文件名、目录结构和映射信息，可以用于还原错误堆栈，但不能单独向开发工具提供原始源码内容。

#cheap

只生成行映射，不生成列映射，以减少 source map 的计算开销，例如 cheap-source-map。单独使用时会忽略 loader 提供的 source map，因此映射结果指向 loader 转换后的代码，而不是原始源码。

#module

仅与 cheap 组合使用，例如 cheap-module-source-map。它会处理 loader 提供的 source map，将行映射还原到原始源码。与 cheap-source-map 相比，它的映射结果更准确，但计算开销也略高。不使用 cheap 时，source-map 默认就会处理 loader 的 source map，无需添加 module。

#debugids

debugids 基于 TC39 Debug ID 提案，为 source map 添加 debugId。例如，使用 source-map-debugids 时，Rspack 还会在对应的输出资源中添加匹配的 //# debugId 注释，便于错误监控工具关联构建产物与 source map。

Rspack 会校验修饰符的顺序，格式必须为 [inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map[-debugids]。其中 inline、hidden 和 eval 互斥，module 只能跟在 cheap 之后，debugids 位于末尾。

#相关配置

• output.sourceMapFilename：自定义独立 source map 文件的名称。
• output.devtoolModuleFilenameTemplate、output.devtoolFallbackModuleFilenameTemplate 和 output.devtoolNamespace：控制 source map 中的模块名称，并避免多个构建之间的名称冲突。
• rules[].extractSourceMap：从输入文件的 sourceMappingURL 注释中提取现有的 source map。

#精细控制

如需更细粒度地控制 source map 的生成方式，将 devtool 设为 false，并改用 SourceMapDevToolPlugin；对于基于 eval 的 source map，改用 EvalSourceMapDevToolPlugin。