目录
- 前言
- 一、Rollup 打包 - 基础配置
- 二、Rollup 打包 - 进阶配置
- 1、output
- (1)、assetFileNames
- (2)、banner/footer
- (3)、chunkFileNames
- (4)、compact
- (5)、dynamicImportInCjs
- (6)、entryFileNames
- (7)、extend
- (8)、externalImportAttributes
- (9)、generatedCode
- (10)、hashCharacters
- (11)、hoistTransitiveImports
- (12)、importAttributesKey
- (13)、inlineDynamicImports
- (14)、interop(重点)
- (15)、intro/outro
- (16)、manualChunks(重点)
- (17)、minifyInternalExports
- (18)、paths
- (19)、preserveModules
- (20)、preserveModulesRoot
- (21)、sourcemap
- (22)、sourcemapBaseUrl
- (23)、sourcemapExcludeSources
- (24)、sourcemapFile
- (25)、sourcemapFileNames
- (26)、sourcemapIgnoreList
- (27)、sourcemapPathTransform
- (28)、validate
- (29)、virtualDirname
- 2、cache
- 3、logLevel
- 4、makeAbsoluteExternalsRelative
- 5、maxParallelFileOps
- 6、onLog
- 7、onwarn
- 8、preserveEntrySignatures
- 9、strictDeprecations
前言
在使用 vite 配置其 build 属性时,我们可以通过 build.rollupOptions 来自定义底层的 Rollup 打包配置(Rollup 选项文档)。
一、Rollup 打包 - 基础配置
1、external
打包时要忽略的外部依赖。
取值:
- 一个接收模块 id 参数并返回 true (表示外部依赖)或 false (表示非外部依赖)的函数。
- 一个模块 ID 数组或者正则表达式。
- 单个的模块 ID。
- 正则表达式。
如果存在多个入口,rollup 会转换回相对引入的方式,就像 output.file 或 output.dir 与入口文件或所有入口文件位于相同目录。
2、input
打包的入口文件配置。
取值:
- 数组:
- 它们将被打包到单独的输出 chunks,除非使用 output.file 选项,否则生成的 chunk 名称将遵循 output.entryFileNames 选项设置 | 它们将被打包到单独的输出 chunks。
- 数组的值将作为入口文件名。
- 对象:
- 它们将被打包到单独的输出 chunks,除非使用 output.file 选项,否则生成的 chunk 名称将遵循 output.entryFileNames 选项设置 | 它们将被打包到单独的输出 chunks。
- 对象的属性名将作为文件名中的 [name]。
- 可以通过在名称中添加 / 来将入口文件放入不同的子文件夹。
使用案例
以下例子将根据 entry-a.js 和 entry-b/index.js,产生至少两个入口 chunks,即 index.js文件将输出在 entry-b 文件夹中:
// rollup.config.js
export default {
// ...
input: {
a: 'src/main-a.js',
'b/index': 'src/main-b.js'
},
output: {
// ...
entryFileNames: 'entry-[name].js'
}
};
如果你想将一组文件转换为另一种格式,并同时保持文件结构和导出签名,推荐的方法是将每个文件变成一个入口文件,而不是使用 output.preserveModules,后者可能会导出被除屑优化,并产生由插件创建的虚拟文件。你可以动态地处理,例如通过 glob 包。
import { globSync } from 'glob';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
export default {
input: Object.fromEntries(
globSync('src/**/*.js').map(file => [
// 这里将删除 `src/` 以及每个文件的扩展名。
// 因此,例如 src/nested/foo.js 会变成 nested/foo
path.relative(
'src',
file.slice(0, file.length - path.extname(file).length)
),
// 这里可以将相对路径扩展为绝对路径,例如
// src/nested/foo 会变成 /project/src/nested/foo.js
fileURLToPath(new URL(file, import.meta.url))
])
),
output: {
format: 'es',
dir: 'dist'
}
};
3、output
输出选项配置。
(1)、dir
输出目录。必选。一般设置为“dist”.
(2)、file(了解)
指定要写入的文件。也可以用于生成 sourcemap。只有在生成的 chunk 不超过一个的情况下才可以使用。
(3)、format
输出的格式。该选项用于指定生成的 bundle 的格式:
- amd:异步模块加载,适用于 RequireJS 等模块加载器
- cjs:CommonJS,适用于 Node 环境和其他打包工具(别名:commonjs)
- es:将 bundle 保留为 ES 模块文件,适用于其他打包工具,以及支持
(4)、globals(了解)
将模块 ID 转换为全局变量的函数。该选项用于在 umd / iife bundle 中,使用 id: variableName 键值对指定外部依赖。
例如:我们使用JQuery时,我们需要告诉 Rollup jquery 是外部依赖,jquery 模块的 ID 为全局变量 $
。
import $ from 'jquery';
// rollup.config.js
export default {
// ...
external: ['jquery'],
output: {
format: 'iife',
name: 'MyBundle',
globals: {
jquery: '$'
}
}
};
*/
(5)、name(了解)
如果 format 为 iife 或 umd,则此选项是必需的。同一页面上的其他脚本可以使用这个变量名来访问你的 bundle 输出。
// rollup.config.js
export default {
// ...
output: {
file: 'bundle.js',
format: 'iife',
name: 'MyBundle'
}
};
// var MyBundle = (function () {...
(6)、plugins
该选项用于指定输出插件。
关于如何使用特定输出的插件,请查看 使用输出插件。
关于如何编写自己的插件,请查看 插件。
对于从包中引入的插件,记得要调用引入的插件函数(即调用 commonjs()
)。返回值为假的插件将被忽略,这样可以用来灵活启用或禁用插件。嵌套的插件将扁平化。异步插件将等待和被解决。
并非所有的插件都可以通过该选项使用。output.plugins 仅限于在 bundle.generate() 或 bundle.write() 阶段,即在 Rollup 的主要分析完成后运行钩子的插件才可使用。如果你是一个插件作者,请查看 输出生成钩子 章节以了解哪些钩子可以使用。
以下是一个使用压缩插件作用于其中一个输出的例子:
// rollup.config.js
import terser from '@rollup/plugin-terser';
export default {
input: 'main.js',
output: [
{
file: 'bundle.js',
format: 'es'
},
{
file: 'bundle.min.js',
format: 'es',
plugins: [terser()]
}
]
};
4、plugins
注入使用的插件。
关于如何使用插件的更多信息,请查看 使用插件章节。
关于如何编写你自己的插件,请查看 插件章节(试试看吧,它并不像听起来那么困难,你可以通过 Rollup 插件做很多拓展)。
对于从包中引入的插件,记住要调用引入的插件函数(即调用 commonjs()
)。返回值为假的插件将被忽略,这样可以用来灵活启用或禁用插件。嵌套的插件将扁平化。异步插件将等待和被解决。
下面举个例子:
// rollup.config.js
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';
const isProduction = process.env.NODE_ENV === 'production';
export default (async () => ({
input: 'main.js',
plugins: [
resolve(),
commonjs(),
isProduction && (await import('@rollup/plugin-terser')).default()
],
output: {
file: 'bundle.js',
format: 'cjs'
}
}))();
上述例子还演示了如何使用一个异步 IIFE 和动态引入来避免引入不必要的模块,这可能会使打包过程变慢。
二、Rollup 打包 - 进阶配置
1、output
输出的高阶配置。
(1)、assetFileNames
该选项的值是一个匹配模式,用于自定义构建结果中的静态资源名称,或者值为一个函数,对每个资源调用以返回匹配模式。这种模式支持以下的占位符:
- [extname]:包含点的静态资源文件扩展名,例如 .css。
- [ext]:不包含点的文件扩展名,例如 css。
- [hash]:基于静态资源内容的哈希。也可以通过例如 [hash:10] 设置一个特定的哈希值长度。默认情况下,它会生成一个 base-64 的哈希值。如果你需要减少字符集的大小,可以查看 output.hashCharacters。
- [name]:静态资源的名称,不包含扩展名。
正斜杠 / 可以用来划分文件到子目录。当值为函数时,PreRenderedAsset 是 generateBundle 中 OutputAsset 类型的简化版本,它没有 fileName。另见 output.chunkFileNames,output.entryFileNames。
(2)、banner/footer
该选项用于在 bundle 前或后添加一个字符串。其值也可以是一个返回 string 的 Promise 异步函数(注意:banner 和 footer 选项不会破坏 sourcemaps)。
如果该选项值为函数,那么 chunk 就会包含一些额外的信息,通过 RenderedChunk 类型来表示,它是 generateBundle 钩子中使用的 OutputChunk 类型的简化版本,具有以下区别:
- code 和 map 没有设置,因为该 chunk 还没有被渲染。
- 所有包含哈希值的引用 chunk 文件名将包含哈希占位符。包括 fileName、imports、importedBindings、dynamicImports 和 implicitlyLoadedBefore。当你在该选项返回的代码中使用这样的占位符文件名或部分文件名时,Rollup 将在 generateBundle 之前用实际的哈希值替换掉占位符,确保哈希值反映的是最终生成的 chunk 中的实际内容,包括所有引用的文件哈希值。
chunk 是可变的,在这个钩子中应用的变化将传递到其他插件和生成的 bundle 中。这意味着如果你在这个钩子中增加或删除引入或导出,你应该更新 imports、importedBindings 以及 exports。
// rollup.config.js
export default {
// ...
output: {
// ...
banner: '/* my-library version ' + version + ' */',
footer: '/* follow me on Twitter! @rich_harris */'
}
};
(3)、chunkFileNames
该选项用于对代码分割中产生的 chunk 自定义命名,其值也可以是一个函数,对每个 chunk 调用以返回匹配模式。这种模式支持以下的占位符:
- [format]:输出(output)选项中定义的格式(format),例如 es 或 cjs。
- [hash]:仅基于最终生成的 chunk 内容的哈希值,其中包括 renderChunk 中的转换部分和其依赖文件哈希值。你也可以通过例如 [hash:10] 设置一个特定的哈希值长度。默认情况下,它会生成一个 base-64 的哈希值。如果你需要减少字符集的大小,可以查看 output.hashCharacters。
- [name]:chunk 的名称。它可以通过 output.manualChunks 选项显示的设置,或者通过插件调用 this.emitFile 设置。否则,它将会根据 chunk 的内容确定。
正斜杠 / 可以用来划分文件到子目录。当值为函数时,PreRenderedChunk 就是 generateBundle 中 OutputChunk 类型的简化版本,它没有依赖于文件名的属性,也没有关于所渲染模块的信息,因为渲染只会在文件名生成之后进行。然而,你还是可以访问到 moduleIds 列表。另见 output.assetFileNames,output.entryFileNames。
(4)、compact
该选项用于压缩 Rollup 产生的额外代码。请注意,这个选项不会影响用户的代码。这个选项在构建已经压缩好的代码时是很有用的。
(5)、dynamicImportInCjs
这是从 CommonJS 文件中引入 ES 模块的唯一方法。如果这个选项默认值为 true,表示 Rollup 会在 CommonJS 输出中保持外部依赖以 import(…) 表达式动态引入。将值设置为 false,以使用 require(…) 语法重写动态引入。
(6)、entryFileNames
查看 output.chunkFileNames 以了解 PreRenderedChunk 类型。
该选项用于指定 chunks 的入口文件模式,其值也可以是一个函数,对每个入口 chunk 调用以返回匹配模式。这种模式支持以下的占位符:
- [format]:输出(output)选项中定义的格式(format),例如 es 或 cjs。
- [hash]:仅基于最终生成的入口 chunk 内容的哈希值,其中包括 renderChunk 中的转换部分和其依赖文件哈希值。你也可以通过例如 [hash:10] 设置一个特定的哈希值长度。默认情况下,它会生成一个 base-64 的哈希值。如果你需要减少字符集的大小,可以查看 output.hashCharacters。
- [name]:入口文件的文件名(不包含扩展名),除非当入口文件为对象时,才用来定义不同的名称。
正斜杠 / 可以用来划分文件到子目录。当值为函数时,PreRenderedChunk 就是 generateBundle 中 OutputChunk 类型的简化版本,它没有依赖于文件名的属性,也没有关于所渲染模块的信息,因为渲染只会在文件名生成之后进行。然而,你还是可以访问到 moduleIds 列表。另见 output.assetFileNames,output.chunkFileNames。
在设置 output.preserveModules 选项时,该模式也会生效。需要注意在这种情况下,[name] 将包括来自输出根路径的相对路径以及可能有原始文件的扩展名,如果它不是 .js、.jsx、.mjs、.cjs、.ts、.tsx、.mts 或 .cts 的其中之一。
(7)、extend
该选项用于指定是否扩展 umd 或 iife 格式中 name 选项定义的全局变量。当值为 true 时,该全局变量将定义为 (global.name = global.name || {})。当值为 false 时,name 选项指定的全局变量将被覆盖为 (global.name = {})。
(8)、externalImportAttributes
是否在输出中为外部引入添加导入属性,如果输出格式为 es。默认情况下,属性来自输入文件,但插件可以稍后添加或删除属性。例如,import “foo” assert {type: “json”} 将导致相同的导入出现在输出中,除非将该选项设置为 false。请注意,模块的所有导入都需要具有一致的属性,否则会发出警告。
(9)、generatedCode
该选项用于制定 Rollup 可以在生成的代码中安全地使用哪些语言特性。这不会转译任何用户的代码,而只改变 Rollup 在包装器和辅助函数中使用的代码。你可以从几个预设中选择一个:
- “es5”:不能使用 ES2015+ 的特性,比如箭头函数,不能使用引号包裹的预留词汇作为属性名。
- “es2015”:使用任意 ES2015 之前的 JavaScript 特性。
1⃣️、arrowFunctions
该选项表示是否为自动生成的代码片段使用箭头函数。请注意,在某些地方,比如模块封装器,Rollup 会继续生成用小括号封装的常规函数,因为在一些 JavaScript 引擎中,这些函数会提供 明显更好的性能。
2⃣️、constBindings
该选项表示在某些地方和辅助函数中使用 const 而不是 var。由于代码块的作用域,会使 Rollup 产生更有效的辅助函数。
3⃣️、objectShorthand
该选项表示当属性名称与值匹配时,是否允许在对象中使用别名。
4⃣️、preset
该选项可以选择上面列出的预设之一,同时覆盖一些选项。
5⃣️、reservedNamesAsProps
该选项确定像 default 这样的预留词,是否可以在不加引号的情况下作为属性名。这将使生成的代码语法符合 ES3 标准。但是请注意,为了完全符合 ES3 标准,你可能还需要对一些内置函数进行补丁(polyfill),比如 Object.keys 或 Array.prototype.forEach。
6⃣️、symbols
该选项确定是否允许在自动生成的代码片断中使用 Symbol。目前,该选项只控制命名空间是否将 Symbol.toStringTag 属性设置为正确的 Module 值,这意味着对于一个命名空间来说,String(namespace) 打印为 [object Module]。该值又被用于某些库和框架的特征检测。
(10)、hashCharacters
这个选项决定了 Rollup 在生成文件哈希时可以使用的字符集。
- 默认的 “base64” 选项会使用包含 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_ 这些 url 安全的字符串 base-64 哈希。
- “base36” 选项只会使用小写字母和数字 abcdefghijklmnopqrstuvwxyz0123456789。
- “hex” 选项会生成包含 abcdef0123456789 这些字符的十六进制哈希。
(11)、hoistTransitiveImports
默认情况下,创建多个 chunk 时,入口 chunk 的可传递引入将以空引入的形式被打包。详细信息和背景请查看 “Why do additional imports turn up in my entry chunks when code-splitting?”。该选项的值为 false 将禁用此行为。当使用 output.preserveModules 选项时,该选项会被忽略,使得永远不会取消引入。
(12)、importAttributesKey
该选项决定 Rollup 用于导入属性的关键词集合。
(13)、inlineDynamicImports
该选项用于内联动态引入,而不是用于创建包含新 chunk 的独立 bundle。该选项只在单一输入源时发挥作用。请注意,它会影响执行顺序:如果该模块是内联动态引入,那么它将会被立即执行。
(14)、interop(重点)
该选项用于控制 Rollup 如何处理默认值,命名空间和动态引入像 CommonJS 这样并不支持这些概念的外部依赖格式。
- “default” 意为所需的值应该被视为引入模块的默认出口。
- “esModule” 意为 ES 模块转译为所需模块,其中所需的值对应模块的命名空间,而默认的导出是导出对象的 .default 属性。这是唯一不会注入任何辅助函数的互操作类型。
- “auto” 结合了 “esModule” 和 “default”,通过注入辅助函数,其包含在运行时检测所需的值是否包含 __esModule 属性 的代码。添加这个属性是 TypeScript esModuleInterop、Babel 和其他工具实现的一种解决方式,标志着所需值是 ES 模块编译后的命名空间。
- compat 等同于 “auto”,只是它对默认导出使用了一个稍微不同的辅助函数,其检查是否存在一个 default 属性而不是 __esModule 属性。除了 CommonJS 模块导出的属性 “default” 不应该是默认导出的这种罕见情况,该值通常有助于使互操作“正常工作”,因为它不依赖于特异的实现,而是使用鸭子类型(duck-typing)。
- “defaultOnly” 与 “default” 类似,但有以下几点区别:
- 禁止命名引入。如果遇到这样的引入,Rollup 会抛出一个错误,即使是 es 和 system 格式。这样可以确保 es 版本的代码能够正确引入 Node 中的非内置 CommonJS 模块。
- 虽然命名空间内再次输出 export * from ‘external’; 不被禁止,但会被忽略掉,并且会导致 Rollup 抛出警告,因为如果没有命名的输出,它们并不会产生影响。
- 当一个命名空间对象生成时,Rollup 将会使用一个更简单的辅助函数。
注意:有一些额外的选项对生成互操作的代码有影响:
- 设置 output.externalLiveBindings 为 false 将生成简化的命名空间辅助函数,以及简化提取默认引入的代码。
- 设置 output.freeze 为 false 将防止生成的互操作命名空间对象被冻结(Object.freeze())。
(15)、intro/outro
除了在特定格式中代码不同外,该选项功能和 output.banner/output.footer 类似。
(16)、manualChunks(重点)
该选项允许你创建自定义的公共 chunk。当值为对象形式时,每个属性代表一个 chunk,其中包含列出的模块及其所有依赖,除非他们已经在其他 chunk 中,否则将会是模块图(module graph)的一部分。chunk 的名称由对象属性的键决定。
当该选项值为函数形式时,每个被解析的模块都会经过该函数处理。如果函数返回字符串,那么该模块及其所有依赖将被添加到以返回字符串命名的自定义 chunk 中。
当 manualChunks 值为函数形式时,它的第二个参数是一个对象,包含 getModuleInfo 函数和 getModuleIds 函数,其工作方式与插件上下文中的 this.getModuleInfo 和 this.getModuleIds 相同。
该选项可以用于根据模块在模块图中的位置动态确定它应该被放在哪个自定义 chunk 中。例如:
// 在 “foo” 组件中
function getTranslatedStrings(currentLanguage) {
switch (currentLanguage) {
case 'en':
return import('./foo.strings.en.js');
case 'de':
return import('./foo.strings.de.js');
// ...
}
}
如果有很多这样的组件一起使用,则会导致生成许多很小的动态引入 chunk:尽管我们知道由同一 chunk 引入的所有相同语言的语言文件将始终一起使用,但是 Rollup 并不知道。
下面代码将会合并所有仅由单个入口使用的相一语言文件:
function manualChunks(id, { getModuleInfo }) {
const match = /.*\.strings\.(\w+)\.js/.exec(id);
if (match) {
const language = match[1]; // 例如 “en”
const dependentEntryPoints = [];
// 在这里,我们使用 Set 一次性处理每个依赖模块
// 它可以阻止循环依赖中的无限循环
const idsToHandle = new Set(getModuleInfo(id).dynamicImporters);
for (const moduleId of idsToHandle) {
const { isEntry, dynamicImporters, importers } =
getModuleInfo(moduleId);
if (isEntry || dynamicImporters.length > 0)
dependentEntryPoints.push(moduleId);
// Set 迭代器足够智能,可以处理
// 在迭代过程中添加元素
for (const importerId of importers) idsToHandle.add(importerId);
}
// 如果仅有一个入口,那么我们会根据入口名
// 将它放到独立的 chunk 中
if (dependentEntryPoints.length === 1) {
return `${
dependentEntryPoints[0].split('/').slice(-1)[0].split('.')[0]
}.strings.${language}`;
}
// 对于多个入口,我们会把它放到“共享”的 chunk 中
if (dependentEntryPoints.length > 1) {
return `shared.strings.${language}`;
}
}
}
(17)、minifyInternalExports
默认情况下,在 es、system 格式下或者 output.compact 值为 true 的情况下该选项值为 true,这意味着 Rollup 会尝试把内部变量导出为单个字母的变量,以便更好地压缩代码。
该选项值为 true 时,尽管表面上会导致代码输出变大,但实际上,如果你使用了压缩工具,代码输出会更小。在这种情况下,export { importantValue as i } 理论上会被压缩成,比如 export{a as i},甚至是 export{i},但实际上输出的是 export{ a as importantValue },因为压缩工具通常不会改变导出签名。
(18)、paths
该选项用于将外部依赖 ID 映射为路径。其中,外部依赖 ID 是指该选项 无法解析 的模块或者通过 external 选项明确指定的模块。output.paths 提供的路径会取代模块 ID,在生成的 bundle 中使用,比如你可以从 CDN 中加载依赖:
// app.js
import { selectAll } from 'd3';
selectAll('p').style('color', 'purple');
// ...
// rollup.config.js
export default {
input: 'app.js',
external: ['d3'],
output: {
file: 'bundle.js',
format: 'amd',
paths: {
d3: 'https://d3js.org/d3.v4.min'
}
}
};
// bundle.js
define(['https://d3js.org/d3.v4.min'], function (d3) {
d3.selectAll('p').style('color', 'purple');
// ...
});
(19)、preserveModules
该选项将使用原始模块名作为文件名,为所有模块创建单独的 chunk,而不是创建尽可能少的 chunk。它需要配合 output.dir 选项一起使用。除屑优化(Tree-shaking)仍会对没有被入口使用或者执行阶段没有副作用的文件生效,并删除不属于入口起点的未使用文件的导出。另一方面,如果插件(如 @rollup/plugin-commonjs)为实现某些结果而产生了额外的“虚拟”文件,这些文件将作为实际文件以 ${output.virtualDirname}/fileName.js 的模式产生。
因此,如果你直接想从这些文件中引入,不建议盲目地使用这个选项将整个文件结构转换为另一种格式,因为预期的输出可能会丢失。在这种情况下,你应该把所有文件明确指定为入口,把它们添加到 input 选项对象 中,可以查看那里的例子。
请注意,在转换为 cjs 或 amd 格式时,设置 output.exports 的值为 auto 可以默认把每个文件作为入口点。
(20)、preserveModulesRoot
当 output.preserveModules 值为 true 时,输入模块的目录路径应从 output.dir 路径中剥离出来。
例如,给定以下配置:
export default {
input: ['src/module.js', `src/another/module.js`],
output: [
{
format: 'es',
dir: 'dist',
preserveModules: true,
preserveModulesRoot: 'src'
}
]
};
preserveModulesRoot 设置确保输入的模块会输出到 dist/module.js 和 dist/another/module.js 路径。
在使用 @rollup/plugin-node-resolve 等插件时,这个选项特别有用,它可能导致输出目录结构的变化。当第三方模块没有标记为 external 时,或者在 monorepo 中多个包相互依赖时,没有标记为 external,都可能发生这种情况。
(21)、sourcemap
如果该选项值为 true,那么将生成一个独立的 sourcemap 文件。如果值为 “inline”,那么 sourcemap 会以 data URI 的形式附加到 output 文件末尾。如果值为 “hidden”,那么它的表现和 true 相同,除了 bundle 文件中将没有 sourcemap 的注释。
(22)、sourcemapBaseUrl
默认情况下,Rollup 生成的 sourcemap 使用相对 URL 路径来引用它们描述的文件。该选项可提供一个绝对基础 URL 路径,例如 https://example.com,sourcemap 将使用绝对 URL 路径来代替。
(23)、sourcemapExcludeSources
如果该选项的值为 true,那么实际源代码将不会被添加到 sourcemap 文件中,从而使其变得更小。
(24)、sourcemapFile
该选项用于指定生成 sourcemap 文件的位置。如果是一个绝对路径,那么 sourcemap 文件中的所有 sources 文件路径都相对于该路径。map.file 属性是 sourcemapFile 的基本名称,因为 sourcemap 文件一般是和其构建后的 bundle 处于同一目录。
如果 output 设置了值,那么 sourcemapFile 不是必须的,这种情况下,它的值会通过输出文件名中添加“.map”推断出来。
(25)、sourcemapFileNames
查看 output.chunkFileNames 以了解 PreRenderedChunk 类型。
该选项指定 sourcemap 的模式,或者是一个根据每个 sourcemap 调用以返回此类模式的函数。该模式支持以下占位符:
- [format]:在输出选项中定义的渲染格式,例如 es 或 cjs。
- [hash]:一个仅基于最终生成的 sourcemap 内容的哈希值。也可以通过例如 [hash:10] 设置特定的哈希长度。默认情况下,它会生成一个 base-64 的哈希值。如果你需要减少字符集的大小,可以查看 output.hashCharacters。
- [chunkhash]:与对应生成的 chunk(如果有的话)使用的哈希值相同。
- [name]:除非使用输入的对象形式定义了不同的名称,否则该文件名(不包括扩展名)就是入口起点的名称。
正斜杠 / 可以用来将文件放在子目录中。当使用函数时,chunkInfo 是 generateBundle 中的简化版本,不包含依赖于文件名的属性,也没有关于渲染模块的信息,因为渲染只在生成文件名之后发生。但是,你可以访问其中的 moduleIds 列表。另请参见 output.assetFileNames,output.chunkFileNames。
(26)、sourcemapIgnoreList
该选项决定是否忽略 sourcemap 中列出的源文件,用于填充 x_google_ignoreList source map 扩展。relativeSourcePath 是生成的 .map 文件到相应源文件的相对路径,而 sourcemapPath 是生成的 sourcemap 文件的绝对路径。
例如:
import path from 'node:path';
export default {
input: 'src/main',
output: [
{
file: 'bundle.js',
sourcemapIgnoreList: (relativeSourcePath, sourcemapPath) => {
// 将忽略所有路径中含有 node_modules 的文件
return relativeSourcePath.includes('node_modules');
},
format: 'es',
sourcemap: true
}
]
};
当没有明确指定这个选项时,默认情况下它会把所有路径中带有 node_modules 的文件放在忽略列表中。你可以设置值为 false 来完全关闭忽略列表。
(27)、sourcemapPathTransform
该选项用于 sourcemap 的路径转换。其中,relativeSourcePath 是指从生成的 .map 文件到相对应的源文件的相对路径,而 sourcemapPath 是指生成 sourcemap 文件的绝对路径。
例如:
import path from 'node:path';
export default {
input: 'src/main',
output: [
{
file: 'bundle.js',
sourcemapPathTransform: (relativeSourcePath, sourcemapPath) => {
// 将会把相对路径替换为绝对路径
return path.resolve(
path.dirname(sourcemapPath),
relativeSourcePath
);
},
format: 'es',
sourcemap: true
}
]
};
(28)、validate
该选项用于重新解析每个生成的 chunk,以检测生成的代码是否是有效的 JavaScript 代码。这对于调试使用 renderChunk 钩子转换代码的插件所产生的输出时很有用。
如果代码是无效的,将抛出警告。请注意,如果没有错误被抛出,你就可以检查输出代码。要把这个警告提升为错误,你可以在 onwarn 中查询。
(29)、virtualDirname
该选项用来指定插件(比如 @rollup/plugin-commonjs)可能会生成的"虚拟"文件的目录名。只有当 output.preserveModules 被启用时,这个选项才会被验证。
2、cache
缓存选项配置。
使用该设置,Rollup 将只会对改变的模块重新分析,从而加速观察模式中后续的构建。将此选项明确设置为 false 将阻止 bundle 生成 cache 属性,也将导致插件的缓存失效。
3、logLevel
日志级别。该选项决定哪些日志将被处理。
默认的 logLevel 为 “info”。
- info 和 warning 日志将被处理。
- debug 日志将被忽略,这意味着它们既不会传递给插件 onLog 钩子,也不会传递给 onLog 选项或打印到控制台。
4、makeAbsoluteExternalsRelative
该选项决定外部依赖的绝对路径是否应该在输出中转换为相对路径。值为 true 时,像 import “/Users/Rollup/project/relative.js” 这样的外部引入将被转换为相对路径。
这不仅适用于源文件中的绝对路径,也适用于由插件或 Rollup 核心解析出的绝对路径。
5、maxParallelFileOps
该选项限制 rollup 在读取模块或写入 chunk 时,同时能打开的文件数量。如果没有限制或者数值足够高,构建可能会失败,显示“EMFILE: Too many open files”(EMFILE:打开的文件数过多)。这取决于操作系统限制的句柄数(open file handles)大小。
6、onLog
一个用于截取日志信息的函数。如果未提供,日志将打印到控制台。
例如:
// rollup.config.js
export default {
//...
onLog(level, log, handler) {
if (log.code === 'CIRCULAR_DEPENDENCY') {
return; // 忽略循环依赖警告
}
if (level === 'warn') {
handler('error', log); // 将其他警告转为错误
} else {
handler(level, info); // 否则直接打印出日志
}
}
};
7、onwarn
用于拦截警告信息。它与 onLog 非常相似,但只接收警告。
8、preserveEntrySignatures
该选项用于控制 Rollup 尝试确保入口 chunk 与基础入口模块具有相同的导出。
- strict:Rollup 将在入口 chunk 中创建与相应入口模块中完全相同的导出。如果因为需要向 chunk 中添加额外的内部导出而无法这样做,那么 Rollup 将创建一个“facade”入口 chunk,它将仅从前其他 chunk 中导出必要的绑定,但不包含任何其他代码。对于库来说,推荐使用此设置。
- allow-extension:Rollup 将在入口 chunk 中创建入口模块的所有导出,但是如果有必要,还可以添加其他导出,从而避免出现“facade”入口 chunk。对于不需要严格签名的库,此设置很有意义。
- exports-only:如果入口模块有导出,它的行为就像 “strict”,否则就像 “allow-extension”。
- false:Rollup 不会将入口模块中的任何导出内容添加到相应的 chunk 中,甚至不包含相应的代码,除非这些导出内容在 bundle 的其他位置使用。但是,可以将内部导出添加到入口 chunks 中。对于将入口 chunks 放置在脚本标记中的 Web 应用,推荐使用该设置,因为它可以同时减少 chunks 的数量和 bundle 的大小。
9、strictDeprecations
启用此选项后,当使用废弃的功能时,Rollup 将抛出错误而不是警告。