命令行接口

Rollup 通常应该从命令行使用。你可以提供一个可选的 Rollup 配置文件，以简化命令行使用并启用高级 Rollup 功能。

配置文件

Rollup 配置文件是可选的，但它们非常强大和方便，因此推荐使用。配置文件是一个 ES 模块，它导出一个默认对象，其中包含所需的选项：

/** @type {import('rollup').RollupOptions} */
// ---cut---
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

// 可以是数组（即多个输入源）
// ---cut-start---
/** @type {import('rollup').RollupOptions} */
// ---cut-end---
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,
		hashCharacters,
		hoistTransitiveImports,
		importAttributesKey,
		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)

// ---cut-start---
/** @type {import('rollup').RollupOptions[]} */
// ---cut-end---
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';

// ---cut-start---
/** @type {import('rollup').RollupOptionsFunction} */
// ---cut-end---
export default commandLineArgs => {
	if (commandLineArgs.configDebug === true) {
		return debugConfig;
	}
	return defaultConfig;
};

如果你现在运行 rollup --config --configDebug，将使用调试配置。

默认情况下，命令行参数将始终覆盖从配置文件中导出的相应值。如果你想更改这种行为，可以通过从 commandLineArgs 对象中删除它们来让 Rollup 忽略命令行参数：

// rollup.config.js
// ---cut-start---
/** @type {import('rollup').RollupOptionsFunction} */
// ---cut-end---
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+，你可以使用导入断言

  import 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

  import { createRequire } from 'node:module';
  const require = createRequire(import.meta.url);
  const pkg = require('./package.json');
  
  // ...

• 或者直接从磁盘读取并解析其内容

  // 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-externalImportAttributes 在 "es" 格式输出中省略导入属性
--no-externalLiveBindings   不生成支持实时绑定的代码
--failAfterWarnings         如果生成的构建产生警告，则退出并显示错误
--filterLogs <filter>       过滤日志信息
--footer <text>             在产物底部插入的代码（位于包装器之外）
--forceExit                 当任务完成后，强制结束进程
--no-freeze                 不冻结命名空间对象
--generatedCode <preset>    使用哪些代码特性（es5/es2015）
--generatedCode.arrowFunctions 在生成的代码中使用箭头函数
--generatedCode.constBindings 在生成的代码中使用 "const"
--generatedCode.objectShorthand 在生成的代码中使用简写属性
--no-generatedCode.reservedNamesAsProps 始终引用保留名称作为 props
--generatedCode.symbols     在生成的代码中使用符号
--hashCharacters <name>     使用指定的字符集来生成文件的哈希值
--no-hoistTransitiveImports 不将中转导入提升到入口块中
--importAttributesKey <name> 使用特定的关键词作为导入属性
--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-reexportProtoFromExternal 在使用重新导出星号（'*'）时，忽略 __proto__
--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 相同，并支持逗号分隔的过滤器列表。

还有一些高级语法可用于更复杂的过滤器。

• ! 对过滤器进行取反操作：

  rollup -c --filterLogs "!code:CIRCULAR_DEPENDENCY"

  将展示 CIRCULAR_DEPENDENCY (循环依赖) 警告外的其他日志。

• * 在过滤器值中可以匹配任何子字符串：

  rollup -c --filterLogs "code:*_ERROR,message:*error*"

  只会展示 code 以 _ERROR 结尾或者 message 包含字符串 error 的日志。

• & 多个过滤器取交集：

  rollup -c --filterLogs "code:CIRCULAR_DEPENDENCY&ids:*/main.js*"

  只会展示 code 为 "CIRCULAR_DEPENDENCY" 并且 ids 包含 /main.js 的日志。这利用了另一个特性：

• 如果值是一个对象，在应用过滤器之前，将通过 JSON.stringify 将其转换为字符串。其他非字符串值将直接转换为字符串。

• 支持嵌套属性：

  rollup -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 视为常规文件名。