output.sourceMap

  • 类型:
type SourceMap =
  | boolean
  | {
      js?: Rspack.Configuration['devtool'];
      css?: boolean;
    };
  • 默认值:
const defaultSourceMap = {
  js: mode === 'development' ? 'cheap-module-source-map' : false,
  css: false,
};

用于设置是否生成 source map 文件,以及生成哪一种格式的 source map。

什么是 source map

source map 是保存源代码映射关系的信息文件,它记录了编译后的代码的每一个位置,以及所对应的编译前的位置。通过 source map,可以在调试编译后的代码时,直接查看对应的源代码。

默认行为

默认情况下,Rsbuild 的 source map 生成规则如下:

  • 在开发模式构建时,会生成 JS 文件的 source map,便于进行开发调试;不会生成 CSS 文件的 source map。
  • 在生产模式构建时,不会生成 JS 和 CSS 文件的 source map,以提供最佳的构建性能。

布尔值

如果 output.sourceMaptrue,则会根据 mode 生成 JS 和 CSS 文件的 source map,等价于:

export default {
  output: {
    sourceMap: {
      js: mode === 'development' ? 'cheap-module-source-map' : 'source-map',
      css: true,
    },
  },
};

如果 output.sourceMapfalse,则不会生成 JS 和 CSS 文件的 source map,等价于:

export default {
  output: {
    sourceMap: {
      js: false,
      css: false,
    },
  },
};

JS source map

JS 文件的 source map 通过 sourceMap.js 来控制,可以传入 Rspack devtool 选项支持的所有 source map 格式,设置为 false 为关闭。

比如,如果你需要在所有模式生成高质量的 source map,可以设置为:

export default {
  output: {
    sourceMap: {
      js: 'source-map',
    },
  },
};

你也可以根据 NODE_ENV 来设置不同的 source map 格式:

export default {
  output: {
    sourceMap: {
      js:
        process.env.NODE_ENV === 'production'
          ? // 生产模式使用高质量的 source map 格式
            'source-map'
          : // 开发模式使用性能更好的 source map 格式
            'cheap-module-source-map',
    },
  },
};
WARNING

在生产构建中使用 source-maphidden-source-map 等选项时,请勿将 source maps (.map 文件) 部署到公开访问的 Web 服务器或 CDN 上。公开 source maps 会暴露你的源代码,并且可能带来安全风险。

CSS source map

CSS 文件的 source map 通过 sourceMap.css 来控制,设置为 true 为开启,设置为 false 为关闭。

比如,如果需要生成 CSS 文件的 source map,可以设置为:

export default {
  output: {
    sourceMap: {
      css: true,
    },
  },
};

在生产构建时,我们不推荐同时开启 output.injectStylesoutput.sourceMap.css,因为 output.injectStyles 会将 source map 注入到 JS 文件中,这会增加文件的体积并导致页面加载变慢。

你可以仅在开发模式下开启 CSS 文件的 source map:

export default {
  output: {
    injectStyles: true,
    sourceMap: {
      css: process.env.NODE_ENV === 'development',
    },
  },
};