命令行接口
Rollup 通常应该从命令行使用。你可以提供一个可选的 Rollup 配置文件,以简化命令行使用并启用高级 Rollup 功能。
配置文件
Rollup 配置文件是可选的,但它们非常强大和方便,因此推荐使用。配置文件是一个 ES 模块,它导出一个默认对象,其中包含所需的选项:
export default {
input: 'src/main.js',
output: {
file: 'bundle.js',
format: 'cjs'
}
};
通常,它被称为 rollup.config.js
或 rollup.config.mjs
,并位于项目的根目录中。除非使用 --configPlugin
或 --bundleConfigAsCjs
选项,否则 Rollup 将直接使用 Node 导入该文件。请注意,使用原生 Node ES 模块时存在一些注意事项,因为 Rollup 将遵循 Node ESM 语义。
如果你想使用 require
和 module.exports
编写 CommonJS 模块的配置文件,你应该将文件扩展名更改为 .cjs
。
你也可以使用其他语言编写配置文件,比如 TypeScript。为此,安装相应的 Rollup 插件,例如 @rollup/plugin-typescript
,并使用 --configPlugin
选项:
rollup --config rollup.config.ts --configPlugin typescript
使用 --configPlugin
选项将始终强制将你的配置文件先转换为 CommonJS 格式。同时,查看 Config Intellisense 以获取在配置文件中使用 TypeScript 类型定义的更多方法。
配置文件支持下面列出的选项。有关每个选项的详细信息,请参阅选项大全:
// rollup.config.js
// 可以是数组(即多个输入源)
export default {
// 核心输入选项
external,
input, // 有条件地需要
plugins,
// 进阶输入选项
cache,
logLevel,
makeAbsoluteExternalsRelative,
maxParallelFileOps,
onLog,
onwarn,
preserveEntrySignatures,
strictDeprecations,
// 危险区域
context,
moduleContext,
preserveSymlinks,
shimMissingExports,
treeshake,
// 实验性
experimentalCacheExpiry,
experimentalLogSideEffects,
experimentalMinChunkSize,
perf,
// 必需(可以是数组,用于描述多个输出)
output: {
// 核心输出选项
dir,
file,
format,
globals,
name,
plugins,
// 进阶输出选项
assetFileNames,
banner,
chunkFileNames,
compact,
dynamicImportInCjs,
entryFileNames,
extend,
externalImportAttributes,
footer,
generatedCode,
hoistTransitiveImports,
inlineDynamicImports,
interop,
intro,
manualChunks,
minifyInternalExports,
outro,
paths,
preserveModules,
preserveModulesRoot,
sourcemap,
sourcemapBaseUrl,
sourcemapExcludeSources,
sourcemapFile,
sourcemapFileNames,
sourcemapIgnoreList,
sourcemapPathTransform,
validate,
// 危险区域
amd,
esModule,
exports,
externalLiveBindings,
freeze,
indent,
noConflict,
sanitizeFileName,
strict,
systemNullSetters,
// 实验性
experimentalMinChunkSize
},
watch: {
buildDelay,
chokidar,
clearScreen,
exclude,
include,
skipWrite
}
};
你可以从配置文件中导出一个数组,以便一次从多个不相关的输入进行打包,即使在监视模式下也可以。要使用相同的输入打出不同的包,你需要为每个输入提供一个输出选项数组:
// rollup.config.js (building more than one bundle)
export default [
{
input: 'main-a.js',
output: {
file: 'dist/bundle-a.js',
format: 'cjs'
}
},
{
input: 'main-b.js',
output: [
{
file: 'dist/bundle-b1.js',
format: 'cjs'
},
{
file: 'dist/bundle-b2.js',
format: 'es'
}
]
}
];
如果你想异步创建配置文件,Rollup 也可以处理解析为对象或数组的 Promise
。
// rollup.config.js
import fetch from 'node-fetch';
export default fetch('/some-remote-service-which-returns-actual-config');
类似地,你也可以这样做:
// rollup.config.js (Promise 解析为数组)
export default Promise.all([fetch('get-config-1'), fetch('get-config-2')]);
要使用配置文件来运行 Rollup,请传递 --config
或 -c
标志:
# 向 Rollup 传递自定义配置文件位置
rollup --config my.config.js
# 如果你没有传递文件名,Rollup 将会尝试
# 按照以下顺序加载配置文件:
# rollup.config.mjs -> rollup.config.cjs -> rollup.config.js
rollup --config
你还可以导出一个返回任何上述配置格式的函数。该函数将传递当前的命令行参数,以便你可以动态地调整你的配置以遵循例如 --silent
。如果你使用 config
作为前缀定义自己的命令行选项,你甚至可以自定义它们:
// rollup.config.js
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 忽略命令行参数:
// rollup.config.js
export default commandLineArgs => {
const inputBase = commandLineArgs.input || 'main.js';
// 这会使 Rollup 忽略 CLI 参数
delete commandLineArgs.input;
return {
input: 'src/entries/' + inputBase,
output: { ... }
}
}
填写配置时的智能提示
由于 Rollup 随附了 TypeScript 类型定义,因此你可以使用 JSDoc 类型提示来利用你的 IDE 的智能感知功能:
// rollup.config.js
/**
* @type {import('rollup').RollupOptions}
*/
const config = {
/* 你的配置 */
};
export default config;
或者,你可以使用 defineConfig
辅助函数,它应该提供无需 JSDoc 注释即可使用智能感知的功能:
// rollup.config.js
import { defineConfig } from 'rollup';
export default defineConfig({
/* 你的配置 */
});
除了 RollupOptions
和封装了该类型的 defineConfig
辅助函数之外,以下类型也可能会很有用:
OutputOptions
:配置文件的output
部分Plugin
:提供name
和一些钩子的插件对象。所有钩子都是完全类型化的,以帮助插件开发。PluginImpl
:将选项对象映射到插件对象的函数。大多数公共的 Rollup 插件都遵循这种模式。
你还可以通过 --configPlugin
选项直接使用 TypeScript 编写配置文件。使用 TypeScript,你可以直接导入 RollupOptions
类型:
import type { RollupOptions } from 'rollup';
const config: RollupOptions = {
/* 你的配置 */
};
export default config;
与 JavaScript API 的差异
虽然配置文件提供了一种简单的配置 Rollup 的方式,但它们也限制了 Rollup 可以被调用和配置的方式。特别是如果你正在将 Rollup 嵌入到另一个构建工具中,或者想将其集成到更高级构建流程中,直接从脚本中以编程方式调用 Rollup 可能更好。
如果你想在某个时候从配置文件切换到使用 JavaScript API,则需要了解一些重要的差异:
- 当使用 JavaScript API 时,传递给
rollup.rollup
的配置必须是一个对象,不能被包装在 Promise 或函数中。 - 你不能再使用配置数组。相反,你应该为每个
inputOptions
集运行一次rollup.rollup
。 output
选项将被忽略。相反,你应该为每个outputOptions
集运行一次bundle.generate(outputOptions)
或bundle.write(outputOptions)
。
从一个 NPM 包加载配置
为了实现互操作性,Rollup 还支持从安装到 node_modules
中的包中加载配置文件:
# 这将首先尝试加载包 "rollup-config-my-special-config"
# 如果失败,则尝试加载 "my-special-config"
rollup --config node:my-special-config
使用原生 Node ES 模块时的注意事项
特别是在从旧版本 Rollup 升级时,当使用原生 ES 模块作为配置文件时,有一些需要注意的事项。
获取当前目录
对于 CommonJS 文件,人们经常使用 __dirname
访问当前目录并将相对路径解析为绝对路径。这在原生 ES 模块中不被支持。相反,我们建议使用以下方法 (例如生成外部模块的绝对 id):
// rollup.config.js
import { fileURLToPath } from 'node:url'
export default {
...,
// 为 <currentdir>/src/some-file.js 生成绝对路径
external: [fileURLToPath(new URL('src/some-file.js', import.meta.url))]
};
导入 package.json
导入你的 package 文件可能很有用,例如自动将你的依赖项标记为 “external”。根据你的 Node 版本,有不同的方法来实现此目的:
对于 Node 17.5+,你可以使用导入断言
jsimport pkg from './package.json' assert { type: 'json' }; export default { // Mark package dependencies as "external". Rest of configuration // omitted. external: Object.keys(pkg.dependencies) };
对于旧一些的 Node 版本,你可以使用
createRequire
jsimport { createRequire } from 'node:module'; const require = createRequire(import.meta.url); const pkg = require('./package.json'); // ...
或者直接从磁盘读取并解析其内容
js// rollup.config.mjs import { readFileSync } from 'node:fs'; // 使用 import.meta.url 可以使路径相对于当前源文件而不是 process.cwd()。 // 更多信息参见: // https://nodejs.org/docs/latest-v16.x/api/esm.html#importmetaurl const packageJson = JSON.parse( readFileSync(new URL('./package.json', import.meta.url)) ); // ...
命令行标志
许多选项都有等效的命令行标志。在这些情况下,如果你正在使用配置文件,则此处传递的任何参数都将覆盖配置文件。以下是所有支持的选项列表:
-c, --config <filename> 使用此配置文件
(如果使用参数但未指定值,则默认为 rollup.config.js)
-d, --dir <dirname> 用于块的目录(如果不存在,则打印到 stdout)
-e, --external <ids> 排除模块 ID 的逗号分隔列表
-f, --format <format> 输出类型(amd、cjs、es、iife、umd、system)
-g, --globals <pairs> `moduleID:Global` 对的逗号分隔列表
-h, --help 显示此帮助消息
-i, --input <filename> 输入(替代 <entry file>)
-m, --sourcemap 生成源映射(`-m inline` 为内联映射)
-n, --name <name> UMD 导出的名称
-o, --file <output> 单个输出文件(如果不存在,则打印到 stdout)
-p, --plugin <plugin> 使用指定的插件(可重复)
-v, --version 显示版本号
-w, --watch 监视产物文件并在更改时重新构建
--amd.autoId 基于块名称生成 AMD ID
--amd.basePath <prefix> 要预先添加到自动生成的 AMD ID 的路径
--amd.define <name> 在 `define` 位置使用的函数
--amd.forceJsExtensionForImports 在 AMD 导入中使用 `.js` 扩展名
--amd.id <id> AMD 模块的 ID(默认为匿名)
--assetFileNames <pattern> 发布资源的名称模式
--banner <text> 在产物顶部插入的代码(位于包装器之外)
--chunkFileNames <pattern> 发布次要块的名称模式
--compact 缩小包装器代码
--context <variable> 指定顶级 `this` 值
--no-dynamicImportInCjs 将外部动态 CommonJS 导入编写为 require
--entryFileNames <pattern> 发布入口块的名称模式
--environment <values> 传递给配置文件的设置(请参阅示例)
--no-esModule 不添加 __esModule 属性
--exports <mode> 指定导出模式(auto、default、named、none)
--extend 扩展由 --name 定义的全局变量
--no-externalImportAssertions 在 "es" 输出中省略导入断言
--no-externalLiveBindings 不生成支持实时绑定的代码
--failAfterWarnings 如果生成的构建产生警告,则退出并显示错误
--filterLogs <filter> 过滤日志信息
--footer <text> 在产物底部插入的代码(位于包装器之外)
--no-freeze 不冻结命名空间对象
--generatedCode <preset> 使用哪些代码特性(es5/es2015)
--generatedCode.arrowFunctions 在生成的代码中使用箭头函数
--generatedCode.constBindings 在生成的代码中使用 "const"
--generatedCode.objectShorthand 在生成的代码中使用简写属性
--no-generatedCode.reservedNamesAsProps 始终引用保留名称作为 props
--generatedCode.symbols 在生成的代码中使用符号
--no-hoistTransitiveImports 不将中转导入提升到入口块中
--no-indent 不缩进结果
--inlineDynamicImports 使用动态导入时创建单次打包
--no-interop 不包括交互操作块
--intro <text> 在产物顶部插入的代码(位于包装器内部)
--logLevel <level> 要显示哪种类型的日志
--no-makeAbsoluteExternalsRelative 不规范化外部导入
--maxParallelFileOps <value> 并行读取的文件数
--minifyInternalExports 强制或禁用内部导出的缩小
--noConflict 为 UMD 全局生成 noConflict 方法
--outro <text> 在产物底部插入的代码(位于包装器内部)
--perf 显示性能计时
--no-preserveEntrySignatures 避免入口点的门面块
--preserveModules 保留模块结构
--preserveModulesRoot 将保留的模块放置在根路径下的此路径下
--preserveSymlinks 解析文件时不要跟随符号链接
--no-sanitizeFileName 不要替换文件名中的无效字符
--shimMissingExports 为丢失的导出创建卡扣变量
--silent 不打印警告
--sourcemapBaseUrl <url> 使用给定的基本 URL 发出绝对源映射 URL
--sourcemapExcludeSources 在源映射中不包括源代码
--sourcemapFile <file> 指定源映射的包位置
--sourcemapFileNames <pattern> 编译后 sourcemap 的命名模式
--stdin=ext 指定用于标准输入的文件扩展名
--no-stdin 不要从 stdin 读取 "-"
--no-strict 不在生成的模块中发出 `"use strict";`
--strictDeprecations 抛出有关不推荐使用的功能的错误
--no-systemNullSetters 不要将空的 SystemJS setter 替换为 `null`
--no-treeshake 禁用除屑优化
--no-treeshake.annotations 忽略纯调用注释
--treeshake.correctVarValueBeforeDeclaration 在声明之前将变量取消优化
--treeshake.manualPureFunctions <names> 手动将函数声明为纯函数
--no-treeshake.moduleSideEffects 假设模块没有副作用
--no-treeshake.propertyReadSideEffects 忽略属性访问副作用
--no-treeshake.tryCatchDeoptimization 不要关闭 try-catch-tree-shaking
--no-treeshake.unknownGlobalSideEffects 假设未知的全局变量不会抛出异常
--validate 验证输出
--waitForBundleInput 等待打包输入文件
--watch.buildDelay <number> 节流观察重建
--no-watch.clearScreen 重建时不要清除屏幕
--watch.exclude <files> 排除要观察的文件
--watch.include <files> 限制观察到指定文件
--watch.onBundleEnd <cmd> 在 "BUNDLE_END" 事件上运行的 Shell 命令
--watch.onBundleStart <cmd> 在 "BUNDLE_START" 事件上运行的 Shell 命令
--watch.onEnd <cmd> 在 "END" 事件上运行的 Shell 命令
--watch.onError <cmd> 在 "ERROR" 事件上运行的 Shell 命令
--watch.onStart <cmd> 在 "START" 事件上运行的 Shell 命令
--watch.skipWrite 在监视时不要将文件写入磁盘
以下标志仅通过命令行界面可用。所有其他标志都对应并覆盖其配置文件等效项,请参阅选项大列表获取详细信息。
--bundleConfigAsCjs
此选项将强制将你的配置转译为 CommonJS。
这允许你在配置中使用 CommonJS 常用的变量/方法,例如 __dirname
或 require.resolve
,即使配置本身是作为 ES 模块编写的。
--configPlugin <plugin>
允许指定 Rollup 插件来转译或控制解析配置文件。主要好处是可以使用非 JavaScript 的配置文件。例如,如果你安装了 @rollup/plugin-typescript
,则以下内容将允许你使用 TypeScript 编写配置文件:
rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript
对于 TypeScript,请确保在 tsconfig.json
的 include
路径中包含 Rollup 配置文件。例如:
"include": ["src/**/*", "rollup.config.ts"],
此选项支持与 --plugin
选项相同的语法,即你可以多次指定该选项,可以省略 @rollup/plugin-
前缀,只需编写 typescript
,并可以通过 ={...}
指定插件选项。
使用此选项将使 Rollup 首先将你的配置文件转译为 ES 模块,然后再执行它。如果要转译为 CommonJS,请还传递 --bundleConfigAsCjs
选项。
--environment <values>
通过 process.ENV
传递其他设置到配置文件。
rollup -c --environment INCLUDE_DEPS,BUILD:production
将设置 process.env.INCLUDE_DEPS === 'true'
和 process.env.BUILD === 'production'
。你可以多次使用此选项。在这种情况下,后续设置的变量将覆盖先前的定义。这使你可以覆盖 package.json
脚本中的环境变量:
{
"scripts": {
"build": "rollup -c --environment INCLUDE_DEPS,BUILD:production"
}
}
如果通过以下方式调用此脚本:
npm run build -- --environment BUILD:development
则配置文件将接收到 process.env.INCLUDE_DEPS === 'true'
和 process.env.BUILD === 'development'
。
--failAfterWarnings
一旦构建完成,如果出现任何警告,则以错误退出构建。
--filterLogs <filter>
根据自定义的过滤器可以仅展示特定的日志。一个过滤器最基本的形式是一个 key:value
键值对,其中键是日志对象的属性,而值是允许的值。例如:
rollup -c --filterLogs code:EVAL
仅会展示 log.code === 'EVAL'
的日志消息。可以通过使用逗号分隔它们或多次使用该选项来指定多个过滤器:
rollup -c --filterLogs "code:FOO,message:This is the message" --filterLogs code:BAR
这将展示所有 code
为 "FOO"
或 "BAR"
,或者 message
为 "This is the message"
的日志。
对于无法添加额外命令行参数的情况,还可以使用 ROLLUP_FILTER_LOGS
环境变量。该变量的值将被处理为与在命令行上指定 --filterLogs
相同,并支持逗号分隔的过滤器列表。
还有一些高级语法可用于更复杂的过滤器。
!
对过滤器进行取反操作:shellrollup -c --filterLogs "!code:CIRCULAR_DEPENDENCY"
将展示 CIRCULAR_DEPENDENCY (循环依赖) 警告外的其他日志。
*
在过滤器值中可以匹配任何子字符串:shellrollup -c --filterLogs "code:*_ERROR,message:*error*"
只会展示
code
以_ERROR
结尾或者message
包含字符串error
的日志。&
多个过滤器取交集:shellrollup -c --filterLogs "code:CIRCULAR_DEPENDENCY&ids:*/main.js*"
只会展示
code
为"CIRCULAR_DEPENDENCY"
并且ids
包含/main.js
的日志。这利用了另一个特性:如果值是一个对象,在应用过滤器之前,将通过
JSON.stringify
将其转换为字符串。其他非字符串值将直接转换为字符串。支持嵌套属性:
shellrollup -c --filterLogs "foo.bar:value"
只会展示属性
log.foo.bar
的值为"value"
的日志。
--forceExit
执行完毕后强制退出进程。在某些情况下,插件或其依赖可能无法正确清理并阻止 CLI 进程退出。根本原因可能很难诊断,而此标志提供了一个逃生口,直到找到并解决该问题。
请注意,这可能会破坏某些工作流程,并且不一定始终正常工作。
-h
/--help
打印帮助文档。
-p <plugin>
,--plugin <plugin>
使用指定的插件。在此处指定插件的方式有多种:
通过相对路径:
rollup -i input.js -f es -p ./my-plugin.js
文件应该导出一个返回插件对象的函数。
通过在本地或全局的
node_modules
文件夹中安装的插件的名称:rollup -i input.js -f es -p @rollup/plugin-node-resolve
如果插件名称不以
rollup-plugin-
或@rollup/plugin-
开头,Rollup 将自动尝试添加这些前缀:rollup -i input.js -f es -p node-resolve
通过一个内联实现:
rollup -i input.js -f es -p '{transform: (c, i) => `/* ${JSON.stringify(i)} */\n${c}`}'
如果你想加载多个插件,可以重复使用该选项或提供逗号分隔的名称列表:
rollup -i input.js -f es -p node-resolve -p commonjs,json
默认情况下,插件函数将不带参数调用以创建插件。但是,你也可以传递自定义参数:
rollup -i input.js -f es -p 'terser={output: {beautify: true, indent_level: 2}}'
--silent
不要将警告打印到控制台。如果你的配置文件包含 onLog
或 onwarn
处理程序,则仍将调用此处理程序。对于具有 onLog
钩子的插件也是如此。为了防止这种情况,另外使用 logLevel
选项或传递 --logLevel silent
。
--stdin=ext
在从 stdin 读取内容时指定虚拟文件扩展名。默认情况下,Rollup 将使用虚拟文件名 -
,没有扩展名,用于从 stdin 读取的内容。但是,一些插件依赖于文件扩展名来确定是否处理文件。另请参见从 stdin 读取文件。
--no-stdin
不要从 stdin
读取文件。设置此标志将防止将内容传输到 Rollup 并确保 Rollup 将 -
和 -.[ext]
解释为常规文件名,而不是将其解释为 stdin
的名称。另请参见从 stdin 读取文件。
-v
/--version
打印已安装的版本号。
--waitForBundleInput
如果入口点文件中有一个文件不可用,这不会引发错误。相反,在开始构建之前,它将等待所有文件都存在。这在监视模式下特别有用,当 Rollup 正在使用另一个进程的输出时。
-w
/--watch
当其源文件在磁盘上发生更改时重新打包。
注意:在观察模式下,Rollup 的命令行界面将设置 ROLLUP_WATCH
环境变量为 "true"
,其他进程可以进行检查。插件应该检查 this.meta.watchMode
,它独立于命令行界面。
--watch.onStart <cmd>
,--watch.onBundleStart <cmd>
,--watch.onBundleEnd <cmd>
,--watch.onEnd <cmd>
,--watch.onError <cmd>
在监视模式下,为监视事件代码运行一个 shell 命令 <cmd>
。另请参见 rollup.watch。
rollup -c --watch --watch.onEnd="node ./afterBuildScript.js"
从标准输入读取文件
当使用命令行界面时,Rollup 也可以从标准输入中读取内容:
echo "export const foo = 42;" | rollup --format cjs --file out.js
当该文件包含导入时,Rollup 将尝试相对于当前工作目录解析它们。当使用配置文件时,只有当入口点的文件名为 -
时,Rollup 才会使用 stdin
作为入口点。要从 stdin 读取非入口点文件,只需将其命名为 -
,这是用于引用 stdin
的内部文件名。例如:
import foo from '-';
在任何文件中,都可以提示 Rollup 尝试从 stdin
读取导入的文件,并将默认导出分配给 foo
。你可以向 Rollup 传递 --no-stdin
CLI 标志,将 -
视为常规文件名。
由于某些插件依赖于文件扩展名来处理文件,你可以通过 --stdin=ext
指定 stdin 的文件扩展名,其中 ext
是所需的扩展名。在这种情况下,虚拟文件名将为 -.ext
:
echo '{"foo": 42, "bar": "ok"}' | rollup --stdin=json -p json
JavaScript API 总是将 -
和 -.ext
视为常规文件名。