CC 4.0 协议
本节内容派生于以下链接指向的内容 ,并遵守 CC BY 4.0 许可证的规定。
以下内容如果没有特殊声明,可以认为都是基于原内容的修改和删减后的结果。
Module parser
module.parser 用于控制 Rspack 如何解析不同类型的模块。它会影响依赖收集、import.meta 和动态 import() 等语法的识别,以及各类模块自己的解析行为。
parser
- 类型:
Object - 默认值:
{}
使用 module.parser 可以按模块类型配置解析器选项。
可配置的 parser 选项分组包括:
asset: Asset parser 选项javascript,javascript/auto,javascript/dynamic,javascript/esm: JavaScript parser 选项json: JSON parser 选项css,css/auto,css/global,css/module: CSS parser 选项
asset
asset 模块的解析器选项。
asset.dataUrlCondition
- 类型:
{ maxSize: number } - 默认值:
{ maxSize: 8096 }
如果当前模块的小于等于 maxSize,那么模块将被 Base64 编码,否则模块将会以文件形式被输出。该选项仅能作用于 Asset modules。
javascript
javascript 模块的解析器选项。
javascript.commonjsMagicComments
- 类型:
boolean - 默认值:
false
为 CommonJS 启用 Magic comments 支持。
目前仅支持 webpackIgnore 注释:
javascript.dynamicImportMode
- 类型:
'lazy' | 'eager' | 'weak' | 'lazy-once' - 默认值:
'lazy'
指定动态导入的全局模式,详见webpackMode。
javascript.dynamicImportPrefetch
- 类型:
boolean | number - 默认值:
false
指定动态导入的全局 prefetch,详见webpackPrefetch。
javascript.dynamicImportPreload
- 类型:
boolean | number - 默认值:
false
指定动态导入的全局 preload,详见webpackPreload。
javascript.dynamicImportFetchPriority
- 类型:
'low' | 'high' | 'auto' - 默认值:
'auto'
指定动态导入的全局 fetchPriority,详见webpackFetchPriority。
javascript.url
- 类型:
true | false | 'relative' | 'new-url-relative' - 默认值:
true
启用 new URL() 语法解析。
true:生成包含根 URL 的绝对 URL(默认行为)。'relative':生成不包含根 URL 的相对 URL。'new-url-relative':相对于公共路径的相对 URL。
当使用 'new-url-relative' 时,Rspack 将在编译时计算出相对于公共路径的相对 URL:
当使用 'relative' 时,Rspack 将生成运行时代码,为 new URL() 语法计算出相对的 URL,结果 URL 中不包含根 URL:
javascript.exprContextCritical
- 类型:
boolean | undefined - 默认值:
true
启用完全动态依赖(import(variable))的警告。
javascript.wrappedContextCritical
- 类型:
boolean | undefined - 默认值:
false
启用部分动态依赖(import("./path/to/" + variable))的警告。
javascript.unknownContextCritical
- 类型:
boolean | undefined - 默认值:
true
在使用 require 函数时,如果无法进行静态分析(require(variable)),是否进行警告。
javascript.wrappedContextRegExp
- 类型:
RegExp | undefined - 默认值:
/.*/
设置正则表达式,用于匹配包裹的动态依赖。
javascript.importMeta
- 类型:
boolean | 'preserve-unknown' - 默认值: 当输出为 ESM 格式 时,默认值为
'preserve-unknown',其他情况默认值为true
用于控制是否要解析和替换源代码中的 import.meta,可选值有:
"preserve-unknown": 已知的import.meta字段 会在编译期被替换,其他字段会被保留并在运行时被计算。true: 所有import.meta字段在编译期被替换。false: 所有import.meta字段都在运行时被计算。
javascript.exportsPresence
- 类型:
'error' | 'warn' | 'auto' | false - 默认值:
'error'
当使用了不存在的导出或存在冲突的重导出时,是否进行警告或报错。
"error":进行报错。"warn":进行警告。"auto":根据模块是否为严格 ESM,如果是严格 ESM 则报错,否则警告。false:关闭该功能。
javascript.importExportsPresence
- 类型:
'error' | 'warn' | 'auto' | false
当使用了不存在的导出时,是否进行警告或报错。默认会遵循 module.parser.javascript.exportsPresence 的配置。
javascript.reexportExportsPresence
- 类型:
'error' | 'warn' | 'auto' | false
当使用了存在冲突的重导出时,是否进行警告或报错。默认会遵循 module.parser.javascript.exportsPresence 的配置。
javascript.typeReexportsPresence
- 类型:
'no-tolerant' | 'tolerant' | 'tolerant-no-check' - 默认值:
'no-tolerant'
是否宽容重导出类型的报错,常见有以下两种场景:
重导出类型时,由于 TypeA、TypeB 是类型,但使用在 export {} 值空间中,导致报错:
使用 Rspack 打包 TypeScript 时,我们强烈推荐开启 tsconfig.json 中的 isolatedModules(使用其他 bundler 时也推荐开启,因为这符合 bundler 如何编译 TypeScript:.ts 文件之间相互独立,独立进行编译),此时对于重导出类型会收到 TypeScript 提示:Re-exporting a type when 'isolatedModules' is enabled requires using 'export type'.。
'no-tolerant':默认行为,不会对重导出类型进行宽容处理,遇到上述情况会报错。'tolerant':会对重导出类型进行宽容处理,同时检查子模块中是否有对应的类型导出,由于需要收集子模块中的类型导出信息,该配置需要和 builtin:swc-loader 的collectTypeScriptInfo.typeExports配合使用。'tolerant-no-check':会对重导出类型进行宽容处理,但不会检查子模块中是否有对应的类型导出,此时可能存在误将本该报错的场景宽容掉(通常 IDE 也会有相应提示),由于不需要检查子模块,所以性能也会更好。
详细示例可参考:type reexports presence 示例
javascript.worker
- 类型:
string[] | boolean
为 Worker 解析提供自定义的语法,常用于支持 Worklet:
查看 Web Workers 了解更多。
javascript.overrideStrict
- 类型:
'strict' | 'non-strict'
将模块覆盖为严格模式或非严格模式。
这可能会影响模块的行为(某些行为在严格模式和非严格模式之间有所不同),因此请谨慎配置此选项。
javascript.commonjs
- 类型:
boolean | { exports?: boolean | 'skipInEsm' } - 默认值:
true
控制 CommonJS 相关的解析行为。true 会保持 Rspack 对 CommonJS 导出赋值的默认转换;设置 { exports: 'skipInEsm' } 时,当模块以 ESM 方式执行会跳过对应的重写,从而保留原始的运行时副作用;配置为 false 则关闭所有 CommonJS 导出处理。
javascript.requireAlias
- 类型:
boolean - 默认值:
false
控制是否解析和转换 CommonJS require 函数的重命名。
当设置为 true 时,Rspack 会解析和转换将 require 赋值给变量或作为参数传递的情况(例如:const req = require; req('./module'))。
javascript.requireAsExpression
- 类型:
boolean - 默认值:
true
控制是否解析作为表达式使用的 require。
当设置为 true 时,Rspack 会解析作为表达式使用的 require(例如:const req = require; req('./module'))并发出警告。当设置为 false 时,这种模式会被忽略。
javascript.requireDynamic
- 类型:
boolean - 默认值:
true
控制是否解析动态 require 调用。
当设置为 false 时,Rspack 不会解析模块路径不是静态字符串的动态 require 调用(例如:require(variable))。如果代码中不使用动态 require,可以提高构建性能。
javascript.requireResolve
- 类型:
boolean - 默认值:
true
控制是否解析 require.resolve() 调用。
当设置为 false 时,Rspack 不会解析 require.resolve() 调用。如果代码中不使用 require.resolve(),可以提高构建性能。
javascript.importDynamic
- 类型:
boolean - 默认值:
true
控制是否解析动态 import() 调用。
当设置为 false 时,Rspack 不会解析模块路径不是静态字符串的动态 import() 调用(例如:import(variable))。如果代码中不使用动态导入,可以提高构建性能。
javascript.strictThisContextOnImports
- 类型:
boolean - 默认值:
false
控制导入模块以对象调用方法的方式调用导出的函数时,Rspack 是否严格保留 this 绑定。
这主要影响模块导出的函数中使用 this 来表示当前模块的场景,例如:
上面的例子中,开启后会输出 42;关闭时为了获得更好的 tree shaking 优化,value 被视为未使用而被移除,结果变成 undefined。
- 设置为
true时,Rspack 会更严格地遵循规范,优先保证运行时this语义正确,但会导致 tree shaking 优化效果下降。 - 设置为
false时,Rspack 会生成更好的优化结果,但可能会导致运行时this语义不正确。
由于该用法在实际开发 ES 模块中非常少见,且开启会影响 tree shaking 优化效果,因此默认值为 false。
如在实际开发时遇到该场景,建议优先避免使用该用法,如无法避免则建议使用 module rule condition 为指定模块单独配置。
javascript.jsx
- 类型:
boolean - 默认值:
false
让 JavaScript 解析器能够识别 JSX 语法,这样语法解析和压缩等流程就可以在保留 JSX 的情况下继续工作。
当你在 loader 中将 JSX 的模式设置为 "preserve",希望把 JSX 的转换留给后续工具(例如输出 JSX 的类库或依赖自定义 JSX runtime 的场景)时,可以开启该选项。
该选项目前仅在 Rspack 中实验性提供,未来可能调整或移除。
javascript.importMetaResolve
- 类型:
boolean - 默认值:
false
让 JavaScript 解析器能够解析 import.meta.resolve() 语法。
目前 import.meta.resolve("./module") 打包后的行为和 require.resolve("./module") 类似,会将模块打包进最终的 bundle 中,并且返回该模块的模块 ID。
该选项目前仅在 Rspack 中实验性提供,未来可能调整或移除。
javascript.pureFunctions
- 类型:
string[]
手动将命中模块中的顶层标识符标记为“调用无副作用”,供基于 pure function 的 tree shaking 使用。配置的名字必须能解析到该模块中的某个顶层名 —— 包括顶层的 function/class/变量声明、import 引入的标识符、export { foo as bar } 这类导出别名,以及匹配源模块默认导出(fn 或 arrow)时使用的 default。
这个选项主要面向无法直接修改源码的第三方库。你既可以将其配置在第三方库源文件上,也可以配置在消费侧文件上以断言对某个 import 的调用是 pure 的。
虽然这个选项定义在 module.parser.javascript 下,但在实际使用时通常更推荐通过 module.rules[i].parser 应用它,这样可以更细粒度地为特定模块配置 pureFunctions。
该选项只有在启用 experiments.pureFunctions 时才会生效;如果在命中的模块中找不到对应的顶层绑定,Rspack 会发出警告。
["javascript/auto"]
javascript/auto 模块的解析器选项,和 javascript 的模块的解析器选项相同。
["javascript/dynamic"]
javascript/dynamic 模块的解析器选项,和 javascript 的模块的解析器选项相同。
["javascript/esm"]
javascript/esm 模块的解析器选项,和 javascript 的模块的解析器选项相同。
json
json 模块的解析器选项。
json.exportsDepth
- Type:
number - Default: production 模式为
Number.MAX_SAFE_INTEGER, development 模式为1
设置 Rspack 对于 json 模块导出的分析程度。development 模式下此项默认值为 1,可大幅提升构建效率。
["css/auto"]
css/auto 模块的解析器选项。
["css/auto"].namedExports
- 类型:
boolean - 默认值:
true
使用 ES 模块命名导出来导出 CSS。
当使用 namedExports: true 时,你可以使用命名空间导出或命名导出:
当使用 namedExports: false 时,除了命名空间导出和命名导出之外,还可以用默认导出:
["css/auto"].url
- 类型:
boolean - 默认值:
true
开启或者关闭对 CSS 中的 url 的处理。
当开启该选项 url: true, Rspack 将 url 函数中的路径解析成资源路径。
当关闭该选项 url: false, Rspack 忽略 url 函数,保持内容不变。
["css/auto"].resolveImport
- 类型:
boolean | ((context: { url: string, media: string | undefined, resourcePath: string, supports: string | undefined, layer: string | undefined }) => boolean) - 默认值:
true
配置是否处理 @import。
true: 启用所有@import规则的处理(默认)。false: 禁用所有@import规则的处理。function: 仅处理满足条件的@import规则。
["css/auto"].import
- 类型:
boolean - 默认值:
true
配置是否处理 CSS @import 规则。
true: 解析并处理@import规则(默认)。false: 在生成的 CSS 中保留@import规则,不进行解析。
["css/auto"].animation
- 类型:
boolean - 默认值:
true
启用或禁用对本地 @keyframes 标识符及其 animation 或 animation-name 使用处的重命名。
["css/auto"].customIdents
- 类型:
boolean - 默认值:
false
启用或禁用对自定义标识符的重命名,例如本地 @counter-style 和 @font-palette-values 名称。
["css/auto"].dashedIdents
- 类型:
boolean - 默认值:
false
启用或禁用对 dashed identifiers 的重命名,例如 CSS 自定义属性和 @property 声明。
css
css 模块的解析器选项。
css.namedExports
和 module.parser["css/auto"].namedExports 一样。
css.url
和 module.parser["css/auto"].url 一样。
css.resolveImport
参考 module.parser["css/auto"].resolveImport。
css.import
和 module.parser["css/auto"].import 一样。
css.animation
和 module.parser["css/auto"].animation 一样。
css.customIdents
和 module.parser["css/auto"].customIdents 一样。
css.dashedIdents
和 module.parser["css/auto"].dashedIdents 一样。
["css/global"]
css/global 模块的解析器选项。
["css/global"].namedExports
和 module.parser["css/auto"].namedExports 一样。
["css/global"].url
和 module.parser["css/auto"].url 一样。
["css/global"].resolveImport
参考 module.parser["css/auto"].resolveImport。
["css/global"].import
和 module.parser["css/auto"].import 一样。
["css/global"].animation
和 module.parser["css/auto"].animation 一样。
["css/global"].customIdents
和 module.parser["css/auto"].customIdents 一样。
["css/global"].dashedIdents
和 module.parser["css/auto"].dashedIdents 一样。
["css/module"]
css/module 模块的解析器选项。
["css/module"].namedExports
和 module.parser["css/auto"].namedExports 一样。
["css/module"].url
和 module.parser["css/auto"].url 一样。
["css/module"].resolveImport
参考 module.parser["css/auto"].resolveImport。
["css/module"].import
和 module.parser["css/auto"].import 一样。
["css/module"].animation
和 module.parser["css/auto"].animation 一样。
["css/module"].customIdents
和 module.parser["css/auto"].customIdents 一样。
["css/module"].dashedIdents
和 module.parser["css/auto"].dashedIdents 一样。

