rollup 介绍及配置
rollup 介绍及配置
Rollup 允许我们使用新的模块系统编写代码，然后将其编译回现有的支持格式，例如 CommonJS 模块、AMD 模块和 IIFE 样式脚本。这意味着我们可以编写 对未来兼容 的代码，并且还具有以下几点好处：
- 去除未引用代码
Rollup 还可以静态分析我们导入的代码，并将排除任何实际上没有使用的内容。这使我们可以在现有的工具和模块的基础上构建，而不需要添加额外的依赖项或使项目的大小变得臃肿。 - 解析 cjs 格式代码
通过 commonjs插件，我们可以实现将 cjs 格式的代码转化成 es 模块。 - 发布 es 模块
为了确保我们的 ES 模块可以立即被处理 CommonJS 的工具，例如 Node.js 和 webpack 使用，我们可以使用 Rollup 编译成 UMD 或 CommonJS 格式，然后在 package.json 文件中使用 main 属性指向编译后的版本。如果我们的 package.json 文件还有一个 module 字段，那么像 Rollup 和 webpack 2+ 这样的可感知 ES 模块的工具将直接 导入 ES 模块版本。
安装
全局安装：
npm install rollup -g
安装好后就可以使得 rollup 作为全局命令行工具使用。
rollup main.js --file bundle.js --format cjs
全局安装会存在一个问题：当多人协同开发时可能会使用不同的rollup版本，这样可能会导致出现一些差异。使用本地安装，作为项目依赖可能是更好的选择。
本地安装：
npm install rollup --save-dev
npm install rollup -D
安装完成后，可以通过 npx 命令在项目的根目录中运行：
npx rollup main.js --file bundle.js --format cjs
使用
我们通常使用一个 rollup 的配置文件以简化命令行使用并启用高级 Rollup 功能。
配置文件
在根目录下新建一个 rollup.config.js （rollup.config.ts）文件。
// rollup.config.js
export default {
input: 'main.js',
output: {
file: 'bundle.js',
},
};
配置文件可以是一个 ES 模块（查看使用原生 Node ES 模块时的注意事项），也可以是 CommonJS，因为 Rollup 遵循 Node ESM 语义。
如果我们使用 TypeScript 编写的配置文件，需要安装 @rollup/plugin-typescript 插件，并在启动命令的时候添加 --configPlugin 选项：
rollup --config rollup.config.ts --configPlugin typescript
使用 --configPlugin 选项将始终强制将我们的配置文件先转换为 CommonJS 格式。
我们可以从配置文件中导出一个数组，以便一次从多个不相关的输入进行打包，即使在监视模式下也可以。要使用相同的输入打出不同的包，我们需要为每个输入提供一个输出选项数组：
export default [
{
input: 'main.js',
output: {
file: 'dist/bundle.js',
format: 'cjs'
}
},
{
input: 'app.js',
output: [{
file: 'dist/app.cjs',
format: 'cjs'
}, {
file: 'dist/bundle.mjs',
format: 'es'
}]
},
]
异步创建配置文件
rollup 可以处理解析为对象或者数组的 promise：
import fetch from 'node-fetch';
export default fetch('/some-remote-service-which-returns-actual-config');
或者使用 promise.all 处理数组：
export default Promise.all([fetch('get-config-1'), fetch('get-config-2')]);
我们还可以导出一个返回任何上述配置格式的函数。该函数将传递当前的命令行参数，以便可以动态地调整我们的配置。
如果我们使用 config 作为前缀（规范）定义自己的命令行选项，我们甚至可以自定义它们：
import defaultConfig from './rollup.default.config.js';
import debugConfig from './rollup.debug.config.js';
export default commandLineArgs => {
if (commandLineArgs.configDebug === true) {
return debugConfig;
}
return defaultConfig;
};
运行 rollup --config --configDebug，将使用调试配置。
默认情况下，命令行参数将始终覆盖从配置文件中导出的相应值。如果我们想更改这种行为，可以通过从 commandLineArgs 对象中删除它们来让 Rollup 忽略命令行参数：
export default commandLineArgs => {
const inputBase = commandLineArgs.input || 'main.js';
// 这会使 Rollup 忽略 CLI 参数
delete commandLineArgs.input;
return {
input: 'src/entries/' + inputBase,
output: { ... }
}
}
智能提示
使用 defineConfig 辅助函数，提供了智能提示的功能：
import { defineConfig } from 'rollup';
export default defineConfig({
input: 'main.js'
});
代码分割
代码分割是指有些情况下 Rollup 会自动将代码拆分成块，例如动态加载或多个入口点，还有一种方法可以显式地告诉 Rollup 将哪些模块拆分成单独的块，这是通过 output.manualChunks 选项实现的。
要使用代码分割功能实现惰性动态加载（其中某些导入的模块仅在执行函数后加载），比如动态加载 foo.js：
export default function () {
import('./foo.js').then(({ default: foo }) => console.log(foo));
}
如果想要把全部代码块放入同一个文件里，那么就需要设置 inlineDynamicImports: true。
{
output: {
manualChunks(id) {
if (id.includes('foo.js')) {
return 'foo';
}
},
}
}
manualChunks 不支持与 inlineDynamicImports 一起配置。
配置文件各字段解析
external
用于匹配需要排除在 bundle 外部的模块。
值可以是一个接收模块 id 参数并返回 true （表示外部依赖）或 false （表示非外部依赖）的函数，也可以是一个模块 ID 数组或者正则表达式。除此之外，它还可以只是单个的模块 ID 或正则表达式。被匹配的模块 ID 应该满足以下条件之一：
- 外部依赖的名称，需要和引入语句中写法完全一致。例如，如果想标记 import “dependency.js” 为外部依赖，就需要使用 “dependency.js” 作为模块 ID；而如果要标记 import “dependency” 为外部依赖，则使用 “dependency”。
- 解析过的模块 ID（如文件的绝对路径）。
import { fileURLToPath } from 'node:url'; export default { //..., external: [ 'some-externally-required-library', fileURLToPath( new URL( 'src/some-local-file-that-should-not-be-bundled.js', import.meta.url ) ), /node_modules/ ] };
input
用于指定 bundle 的入口文件。
{
input: 'index.js'
}
如果值为一个入口文件的数组或一个将名称映射到入口文件的对象，那么它们将被打包到单独的输出 chunks 中。
// 数组
{
input: ['index.js', 'main.js']
}
// 对象
{
input: {
index: 'index.js',
main: 'main.js'
}
}
除非使用 output.file 选项，否则生成的 chunk 名称将遵循 output.entryFileNames 选项设置。当该选项的值为对象形式时，对象的属性名将作为文件名中的 [name]，而对于值为数组形式，数组的值将作为入口文件名。
当选项的值使用对象形式时，可以通过在名称中添加 / 来将入口文件放入不同的子文件夹。
export default {
...,
input: {
a: 'src/main-a.js',
'b/index': 'src/main-b.js'
},
output: {
...,
entryFileNames: 'entry-[name].js'
}
};
output
file
用于指定要写入的文件。如果适用的话，也可以用于生成 sourcemap。只有在生成的 chunk 不超过一个的情况下才可以使用。
{
input: 'index.js',
output: {
file: 'bundle.js',
},
}
如果此时入口文件有多个，就不能使用 file 配置，而是 dir，否则就会报错。
单个入口文件但是通过import引入了其他模块，如果只想生成一个 chunk，那么需要配置 inlineDynamicImports: true。
dir
用于指定所有生成的 chunk 被放置在哪个目录中。如果生成一个以上的 chunk，那么这个选项是必需的。否则，可以使用 file 选项来代替。
{
input: ['index.js','main.js'],
output: {
dir: 'dist',
},
}
format
用于指定生成的 bundle 的格式。满足以下其中之一：
- amd – 异步模块加载，适用于 RequireJS 等模块加载器。
- cjs – CommonJS，适用于 Node 环境和其他打包工具。
- es（默认） – 将 bundle 保留为 ES 模块文件，适用于其他打包工具，以及支持 <script type=module> 标签的浏览器。
- iife – 自执行函数，适用于 <script> 标签（如果我们想为我们的应用程序创建 bundle，那么我们可能会使用它）。iife 表示“自执行 函数表达式”。
- umd – 通用模块定义规范，同时支持 amd，cjs 和 iife。
- system – SystemJS 模块加载器的原生格式。
{
input: 'index.js',
format: 'cjs',
output: 'bundle.js'
}
globals
用于在 umd / iife 格式的 bundle 中，使用 id: variableName 键值对指定外部依赖。例如，在这样的情况下：
import $ from 'jquery';
我们需要告诉 Rollup jquery 是一个外部依赖，jquery 模块的 ID 为全局变量 $
// rollup.config.js
export default {
input: 'index.js',
external: ['jquery'],
output: {
format: 'iife',
name: 'MyBundle',
globals: {
jquery: '$'
}
}
};
/*
var MyBundle = (function ($) {
// ...
}($));
*/
name
对于输出格式为 iife / umd 的 bundle 来说，若想要使用全局变量名来表示我们的 bundle 时，该选项是必要的。同一页面上的其他脚本可以使用这个变量名来访问我们的 bundle 输出。
// rollup.config.js
export default {
...,
output: {
file: 'bundle.js',
format: 'iife',
name: 'MyBundle'
}
};
// var MyBundle = (function () {...})
extend
用于指定是否扩展 umd 或 iife 格式中 name 选项定义的全局变量。当值为 true 时，该全局变量将定义为 (global.name = global.name || {})。当值为 false 时，name 选项指定的全局变量将被覆盖为 (global.name = {})。
generatedCode
该用于制定 Rollup 可以在生成的代码中安全地使用哪些语言特性。这不会转译任何用户的代码，而只改变 Rollup 在包装器和辅助函数中使用的代码。我们可以从几个预设中选择一个：
- “es5”（默认）：不能使用 ES2015+ 的特性，比如箭头函数，不能使用引号包裹的预留词汇作为属性名。
- “es2015”：使用任意 ES2015 之前的 JavaScript 特性。
hashCharacters
这个选项决定了 Rollup 在生成文件哈希时可以使用的字符集。
- 默认的 “base64” 选项会使用包含 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_ 这些 url 安全的字符串 base-64 哈希。
- “base36” 选项只会使用小写字母和数字 abcdefghijklmnopqrstuvwxyz0123456789。
- “hex” 选项会生成包含 abcdef0123456789 这些字符的十六进制哈希。
assetFileNames
该选项的值是一个匹配模式，用于自定义构建结果中的[静态资源]名称，或者值为一个函数（((assetInfo: AssetInfo) => string)），对每个资源调用以返回匹配模式。这种模式支持以下的占位符：
- [extname]：包含点的静态资源文件扩展名，例如 .css。
- [ext]：不包含点的文件扩展名，例如 css。
- [hash]：基于静态资源内容的哈希。也可以通过例如 [hash:10] 设置一个特定的哈希值长度。默认情况下，它会生成一个 base-64 的哈希值。如果我们需要减少字符集的大小，可以查看 output.hashCharacters。
- [name]：静态资源的名称，不包含扩展名。
正斜杠 / 可以用来划分文件到子目录。当值为函数时，assetInfo 是 generateBundle 中没有 fileName 的简化版本
banner、footer
该选项用于在 bundle 前或后添加一个字符串。其值也可以是一个返回 string 的 Promise 异步函数（注意：banner 和 footer 选项不会破坏 sourcemaps）。
{
input: 'index.js',
banner: '// banner',
footer: '// footer'
}
chunkFileNames
该选项用于对代码分割中产生的 chunk 自定义命名，其值也可以是一个函数（((chunkInfo: ChunkInfo) => string)），对每个 chunk 调用以返回匹配模式。这种模式支持以下的占位符：
- [format]：输出（output）选项中定义的格式（format），例如 es 或 cjs。
- [hash]：仅基于最终生成的 chunk 内容的哈希值，其中包括 renderChunk 中的转换部分和其依赖文件哈希值。我们也可以通过例如 [hash:10] 设置一个特定的哈希值长度。默认情况下，它会生成一个 base-64 的哈希值。如果我们需要减少字符集的大小，可以查看 output.hashCharacters。
- [name]：chunk 的名称。它可以通过 output.manualChunks 选项显示的设置，或者通过插件调用 this.emitFile 设置。否则，它将会根据 chunk 的内容确定。
正斜杠 / 可以用来划分文件到子目录。当值为函数时，chunkInfo 是 generateBundle 的简化版本，其中不包含依赖于文件名的属性，且没有关于所渲染模块的信息，因为只有在文件名生成之后才会渲染。
// 函数
{
chunkFileNames: (chunkInfo) => {
return '[format]/[hash]-[name].js';
},
}
// 字符
{
chunkFileNames: '[format]/[hash]-[name].js',
}
compact
该选项用于压缩 Rollup 产生的额外代码。请注意，这个选项不会影响用户的代码。这个选择在构建已经压缩好的代码时是很有用的。
dynamicImportInCjs
虽然 CommonJS 输出最初只支持 require(…) 语法来引入依赖，但最近的 Node 版本也开始支持 import(…) 语法，这是从 CommonJS 文件中引入 ES 模块的唯一方法。如果这个选项默认值为 true，表示 Rollup 会在 CommonJS 输出中保持外部依赖以 import(…) 表达式动态引入。将值设置为 false，以使用 require(…) 语法重写动态引入。
entryFileNames
用于指定 chunks 的入口文件模式，其值也可以是一个函数，对每个入口 chunk 调用以返回匹配模式。这种模式支持以下的占位符：
- [format]：输出（output）选项中定义的格式（format），例如 es 或 cjs。
- [hash]：仅基于最终生成的入口 chunk 内容的哈希值，其中包括 renderChunk 中的转换部分和其依赖文件哈希值。我们也可以通过例如 [hash:10] 设置一个特定的哈希值长度。默认情况下，它会生成一个 base-64 的哈希值。如果我们需要减少字符集的大小，可以查看 output.hashCharacters。
- [name]：入口文件的文件名（不包含扩展名），除非当入口文件为对象时，才用来定义不同的名称。
用法跟 chunkFileNames 一样，只不过输入的是打包后的入口文件名：
{
entryFileNames: (chunkInfo) => {
return 'entry-[name]-[hash].js';
},
}
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');
// ...
});
sourcemap
如果该选项值为 true，那么将生成一个独立的 sourcemap 文件。如果值为 “inline”，那么 sourcemap 会以 data URI 的形式附加到 output 文件末尾。如果值为 “hidden”，那么它的表现和 true 相同，除了 bundle 文件中将没有 sourcemap 的注释。
{
sourcemap: 'hidden'
}
sourcemapBaseUrl
默认情况下，Rollup 生成的 sourcemap 使用相对 URL 路径来引用它们描述的文件（sourcemap: true 的情况下）。该选项可提供一个绝对基础 URL 路径，例如 https://example.com，sourcemap 将使用绝对 URL 路径来代替。
sourcemapExcludeSources
如果该选项的值为 true，那么实际源代码将不会被添加到 sourcemap 文件中，从而使其变得更小。
validate
该选项用于重新解析每个生成的 chunk，以检测生成的代码是否是有效的 JavaScript 代码。这对于调试使用 renderChunk 钩子转换代码的插件所产生的输出时很有用。
如果代码是无效的，将抛出警告。请注意，如果没有错误被抛出，我们就可以检查输出代码。要把这个警告提升为错误，我们可以在 onwarn 中查询。
plugins
该选项用于指定输出插件。
cache
用于指定之前 bundle 的 cache 属性（默认为 true）。使用该设置，Rollup 将只会对改变的模块重新分析，从而加速观察模式中后续的构建。将此选项明确设置为 false 将阻止 bundle 生成 cache 属性，也将导致插件的缓存失效。
logLevel
‘warn’ | ‘info’ | ‘debug’
决定哪些日志将被处理。默认的 logLevel 为 “info”，这意味着 info 和 warning 日志将被处理，而 debug 日志将被忽略，这意味着它们既不会传递给插件 onLog 钩子，也不会传递给 onLog 选项或打印到控制台。
makeAbsoluteExternalsRelative
决定外部依赖的绝对路径是否应该在输出中转换为相对路径。
maxParallelFileOps
限制 rollup 在读取模块或写入 chunk 时，同时能打开的文件数量（默认20）。如果没有限制或者数值足够高，构建可能会失败，显示“EMFILE: Too many open files”（EMFILE：打开的文件数过多）。这取决于操作系统限制的句柄数（open file handles）大小。
原文地址：https://blog.csdn.net/qq_42880714/article/details/136527896
免责声明：本站文章内容转载自网络资源，如本站内容侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！