> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# SourceMapDevToolPlugin

本插件实现了对 source map 生成内容进行更细粒度的控制。它也可以根据 [`devtool`](/zh/config/devtool.md) 配置选项的某些设置来自动启用。

## 示例

下面的示例展示了本插件的一些常见用例。

### 基本使用

你可以使用以下代码将配置项 devtool: inline-source-map 替换为等效的自定义插件配置：

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  devtool: false,
  plugins: [new rspack.SourceMapDevToolPlugin({})],
};
```

### 排除 Vendor maps

以下代码会排除 `vendor.js` 输出资源，使其不生成 source map。

```js
new rspack.SourceMapDevToolPlugin({
  filename: '[file].map[query]',
  exclude: ['vendor.js'],
});
```

### 在宿主环境外部化 source map

设置 source map 的 URL。在宿主环境需要授权的情况下很有用。

```js
new rspack.SourceMapDevToolPlugin({
  append: '\n//# sourceMappingURL=https://example.com/sourcemap/[url]',
  filename: '[file].map[query]',
});
```

还有一种场景，source map 存储在上层目录中时：

```
project
|- dist
  |- public
    |- bundle-[hash].js
  |- sourcemaps
    |- bundle-[hash].js.map
```

如下设置：

```js
new rspack.SourceMapDevToolPlugin({
  filename: 'sourcemaps/[file].map',
  publicPath: 'https://example.com/project/',
  fileContext: 'public',
});
```

将会生成以下 URL：

```
https://example.com/project/sourcemaps/bundle-[hash].js.map
```

## 选项

支持以下选项：

### test

- **类型：** `string` `RegExp` `[string, RegExp]`

通过匹配输出资源的文件名，选择要生成 source map 的资源。未设置时，`test` 不会过滤输出资源。

### include

- **类型：** `string` `RegExp` `[string, RegExp]`

使输出文件名与该值匹配的资源生成 source map。

### exclude

- **类型：** `string` `RegExp` `[string, RegExp]`

使输出文件名与该值匹配的资源不生成 source map。

`test`、`include` 和 `exclude` 匹配的是输出资源文件名，例如 `vendor.js`，而非 `src/index.js` 或 `node_modules/package/index.js` 这样的源模块路径。

### filename

- **类型：** `string`

定义生成的 source map 的名称（如果未提供值，则内联）。

### append

- **类型：** `string` `function`

原始资源后追加给定值。通常是 `#sourceMappingURL` 注释。`[url]` 被替换成 source map 文件的 URL。支持路径参数：`[chunk]`、`[filename]` 和 `[contenthash]`。将 `append` 设置为 `false` 可禁用附加操作。

### moduleFilenameTemplate

- **类型：** `string`

详见 [`output.devtoolModuleFilenameTemplate`](/zh/config/output.md#outputdevtoolmodulefilenametemplate)。

### fallbackModuleFilenameTemplate

- **类型：** `string`

详见上面的链接。

### namespace

- **类型：** `string`

详见 [`output.devtoolNamespace`](/zh/config/output.md#outputdevtoolnamespace).

### module

- **类型：** `boolean`
- **默认值：** `true`

指示 loader 是否应该生成 source map 文件。

### columns

- **类型：** `boolean`
- **默认值：** `true`

指示是否使用 column mapping。

### noSources

- **类型：** `boolean`
- **默认值：** `false`

阻止源文件内容被包含在 source map 中。

### publicPath

- **类型：** `string`

使用公共路径前缀生成绝对 URL，例如 `https://example.com/project/`。

### fileContext

- **类型：** `string`

使 `[file]` 参数相对于这个目录。

`fileContext` 选项在你希望将 source map 存储在上级目录以避免绝对 `[url]` 中出现 `../../` 时非常有用。

### sourceRoot

- **类型：** `string`

为 source map 中的 `sourceRoot` 属性提供自定义值。

:::tip 提示
将 `module` 或 `columns` 设置为 `false` 将生成不太准确的 source map，但同时也能显著提高编译性能。
:::

:::tip 提示
如果你想要在[开发模式](/zh/config/mode.md#development)中为这个插件使用自定义配置，请确保禁用默认配置。即设置 `devtool: false`。
:::


本页改编自 [webpack 文档](https://webpack.docschina.org/plugins/source-map-dev-tool-plugin/)，遵循 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)，且已作修改。