Rollup 配置选项总览
核心功能(Core functionality)
1.1 输入与外部依赖
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
external | 声明哪些模块为外部依赖,不被打包进 bundle,而是在运行时从外部环境加载 | (string | RegExp)[] | RegExp | string | (id: string, parentId: string, isResolved: boolean) => boolean | 未显式说明(默认不排除任何模块) | https://cn.rollupjs.org/configuration-options/#external |
input | 指定打包入口文件,可以是单入口、多入口或命名入口 | string | string[] | { [entryName: string]: string } | 无(必填项之一) | https://cn.rollupjs.org/configuration-options/#input |
external 示例
javascript
// rollup.config.js
import { fileURLToPath } from "node:url"
export default {
input: "src/main.js",
external: [
"react",
"react-dom",
fileURLToPath(
new URL("src/some-local-file-that-should-not-be-bundled.js", import.meta.url)
),
/node_modules/
],
output: {
file: "dist/bundle.js",
format: "es",
globals: {
react: "React",
"react-dom": "ReactDOM"
}
}
}input 多入口示例
javascript
// rollup.config.js
export default {
input: {
main: "src/main.js",
admin: "src/admin.js"
},
output: {
dir: "dist",
format: "es"
}
}CLI 等价写法:
bash
rollup --input src/entry1.js --input src/entry2.js --format es
# 等价于
rollup src/entry1.js src/entry2.js --format es1.2 JSX 相关选项
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
jsx | 是否启用 JSX 支持以及相关配置总入口,可以保留或转换 JSX | false | JsxOptions | 未显式说明(未配置时默认不处理 JSX) | https://cn.rollupjs.org/configuration-options/#jsx |
jsx.mode | JSX 处理模式:保留、经典(React.createElement)或自动(React 17 新 JSX Transform) | "preserve" | "classic" | "automatic" | 未显式说明(由 preset 或配置决定) | https://cn.rollupjs.org/configuration-options/#jsxmode |
jsx.factory | 经典/自动模式下 JSX 元素工厂函数名(如 React.createElement 或 h) | string | null | 未显式说明(常见库通过预设给出) | https://cn.rollupjs.org/configuration-options/#jsxfactory |
jsx.fragment | 片段元素工厂函数名(如 React.Fragment) | string | null | 未显式说明 | https://cn.rollupjs.org/configuration-options/#jsxfragment |
jsx.importSource | JSX 辅助函数从哪个包导入(例如 react 或 preact) | string | null | 未显式说明 | https://cn.rollupjs.org/configuration-options/#jsximportsource |
jsx.jsxImportSource | 自动模式使用的新 JSX runtime 包名(如 react) | string | 未显式说明 | https://cn.rollupjs.org/configuration-options/#jsxjsximportsource |
jsx.preset | 快速应用一组预设(如 React/Preact,对 mode、factory 等统一配置) | "react" | "react-jsx" | "preserve" | "preserve-react" | 未显式说明 | https://cn.rollupjs.org/configuration-options/#jsxpreset |
类型参考(官方给出的定义)
type JsxPreset = 'react' \| 'react-jsx' \| 'preserve' \| 'preserve-react'
type JsxOptions =
| { mode: 'preserve'; factory: string \| null; fragment: string \| null; importSource: string \| null; preset: JsxPreset \| null }
| { mode: 'classic'; factory: string; fragment: string; importSource: string \| null; preset: JsxPreset \| null }
| { mode: 'automatic'; factory: string; importSource: string; jsxImportSource: string; preset: JsxPreset \| null }
JSX 自动模式(React 17+)示例
javascript
// rollup.config.js
export default {
input: "src/main.jsx",
jsx: {
mode: "automatic",
importSource: "react",
jsxImportSource: "react"
},
output: {
file: "dist/bundle.js",
format: "es"
}
}1.3 输出(核心)
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
output.dir | 输出目录,用于多入口或代码分割场景,将多个 chunk 写入该目录 | string | 未显式说明(与 output.file 互斥) | https://cn.rollupjs.org/configuration-options/#outputdir |
output.file | 单入口场景的输出文件路径(不能与代码分割同时使用) | string | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputfile |
output.format | 输出模块格式:es、cjs、umd、iife、system 等 | "amd" | "cjs" | "system" | "es" | "umd" | "iife" | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputformat |
output.globals | 指定外部依赖在 UMD/IIFE 下映射到的全局变量名 | { [id: string]: string } | {} | https://cn.rollupjs.org/configuration-options/#outputglobals |
output.name | 当 format 为 umd/iife 时,指定打包结果在全局环境中的变量名 | string | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputname |
output.plugins | 仅作用于输出阶段的插件列表(如压缩等) | OutputPlugin[] | [] | https://cn.rollupjs.org/configuration-options/#outputplugins |
plugins | 输入侧/构建过程使用的插件列表(如 Node resolve、Babel 等) | Plugin[] | [] | https://cn.rollupjs.org/configuration-options/#plugins |
output.dir + 代码分割示例
javascript
export default {
input: ["src/main.js", "src/admin.js"],
output: {
dir: "dist",
format: "es"
}
}output.file 单文件产出示例
javascript
export default {
input: "src/main.js",
output: {
file: "dist/bundle.cjs",
format: "cjs"
}
}UMD 库输出示例
javascript
export default {
input: "src/index.js",
external: ["react"],
output: {
file: "dist/my-lib.umd.js",
format: "umd",
name: "MyLib",
globals: {
react: "React"
}
}
}进阶功能(Advanced functionality)
2.1 输入/构建级进阶选项
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
cache | 复用上一次构建的缓存,加速增量构建。设为 false 可禁用缓存生成 | RollupCache | false | 未显式说明(CLI watch 默认启用) | https://cn.rollupjs.org/configuration-options/#cache |
logLevel | 控制日志等级:debug / info / warn / silent | "debug" | "info" | "warn" | "silent" | "info" | https://cn.rollupjs.org/configuration-options/#loglevel |
makeAbsoluteExternalsRelative | 是否把绝对路径的 external 转换为相对路径(或仅针对相对源) | boolean | "ifRelativeSource" | true | https://cn.rollupjs.org/configuration-options/#makeabsoluteexternalsrelative |
maxParallelFileOps | 限制同时进行的文件 IO 操作数,防止“过多打开文件”错误 | number | 未显式说明 | https://cn.rollupjs.org/configuration-options/#maxparallelfileops |
onLog | 高级日志处理钩子,可统一过滤/重写日志 | (level, log, handler) => void | 未显式说明 | https://cn.rollupjs.org/configuration-options/#onlog |
onwarn | 经典警告回调(简化版 onLog),可忽略或转化警告 | (warning, warn) => void | 未显式说明 | https://cn.rollupjs.org/configuration-options/#onwarn |
preserveEntrySignatures | 控制入口模块的导出签名保留策略 | false | "strict" | "allow-extension" | "strict" | https://cn.rollupjs.org/configuration-options/#preserveentrysignatures |
strictDeprecations | 将已废弃特性的使用视为错误而非警告 | boolean | false | https://cn.rollupjs.org/configuration-options/#strictdeprecations |
onwarn 示例(静音特定警告)
javascript
export default {
// ...
onwarn(warning, warn) {
if (warning.code === "CIRCULAR_DEPENDENCY") return
warn(warning)
}
}2.2 输出级进阶选项(命名、文件名模板、资源)
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
output.assetFileNames | 资源文件命名模板(如图片、CSS),支持占位符 | string | (assetInfo) => string | 未显式说明(默认 assets/[name]-[hash][extname] 类似) | https://cn.rollupjs.org/configuration-options/#outputassetfilenames |
output.banner / output.footer | 在生成文件顶部/底部插入字符串或动态内容 | string | (() => string | Promise<string>) | "" | https://cn.rollupjs.org/configuration-options/#outputbanner |
output.chunkFileNames | 非入口 chunk 命名模板 | string | (chunkInfo) => string | 未显式说明(通常为 chunk-[hash].js) | https://cn.rollupjs.org/configuration-options/#outputchunkfilenames |
output.compact | 尽量压缩输出中的空白字符 | boolean | false | https://cn.rollupjs.org/configuration-options/#outputcompact |
output.entryFileNames | 入口 chunk 命名模板 | string | (chunkInfo) => string | 未显式说明(通常为 [name].js) | https://cn.rollupjs.org/configuration-options/#outputentryfilenames |
output.extend | UMD/IIFE 格式下是否扩展已存在的全局变量而不是覆盖 | boolean | false | https://cn.rollupjs.org/configuration-options/#outputextend |
output.externalImportAttributes | 控制 external 导入的 import attributes 行为 | boolean | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputexternalimportattributes |
output.hashCharacters | 哈希字符集,用于生成 chunk/asset 名中的 [hash] | "hex" | "base64" | "hex" | https://cn.rollupjs.org/configuration-options/#outputhashcharacters |
output.virtualDirname | 为虚拟模块产生实际文件时使用的目录前缀 | string | "_virtual"(典型实现) | https://cn.rollupjs.org/configuration-options/#outputvirtualdirname |
文件名模板示例
javascript
export default {
input: ["src/main.js", "src/admin.js"],
output: {
dir: "dist",
format: "es",
entryFileNames: "entry/[name]-[hash].js",
chunkFileNames: "chunks/[name]-[hash].js",
assetFileNames: "assets/[name]-[hash][extname]"
}
}2.3 代码生成相关(output.generatedCode.*)
2.4 代码分割与手动分 chunk
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
output.dynamicImportInCjs | 当输出为 CJS 时是否保留动态导入(或如何转换) | boolean | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputdynamicimportincjs |
output.inlineDynamicImports | 是否将动态导入内联到同一文件中(禁用代码分割) | boolean | false | https://cn.rollupjs.org/configuration-options/#outputinlinedynamicimports |
output.manualChunks | 手动指定哪些模块打到哪个 chunk 中,实现更精细的代码分割 | { [chunkName: string]: string[] } | (id: string, meta) => string | null | undefined | https://cn.rollupjs.org/configuration-options/#outputmanualchunks |
output.hoistTransitiveImports | 是否将入口的传递依赖“提升”为入口的直接 imports,以优化加载顺序 | boolean | true | https://cn.rollupjs.org/configuration-options/#outputhoisttransitiveimports |
output.preserveModules | 按原始模块结构输出多个文件(每个输入模块单独一个 chunk) | boolean | false | https://cn.rollupjs.org/configuration-options/#outputpreservemodules |
output.preserveModulesRoot | 配合 preserveModules,指定输出目录结构的根路径,以剥离公共前缀 | string | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputpreservemodulesroot |
output.manualChunks 示例
javascript
export default {
input: "src/main.js",
output: {
dir: "dist",
format: "es",
manualChunks: {
vendor: ["react", "react-dom"]
}
}
}或函数形式:
javascript
export default {
input: "src/main.js",
output: {
dir: "dist",
format: "es",
manualChunks(id) {
if (id.includes("node_modules")) return "vendor"
}
}
}2.5 Sourcemap 与路径控制
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
output.sourcemap | 是否生成 Sourcemap | boolean | "inline" | "hidden" | false | https://cn.rollupjs.org/configuration-options/#outputsourcemap |
output.sourcemapBaseUrl | Sourcemap 中引用源码的基准 URL | string | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputsourcemapbaseurl |
output.sourcemapDebugIds | 为调试用途生成更稳定的 chunk id | boolean | false | https://cn.rollupjs.org/configuration-options/#outputsourcemapdebugids |
output.sourcemapExcludeSources | 是否在 sourcemap 中排除源码内容,仅保留映射 | boolean | false | https://cn.rollupjs.org/configuration-options/#outputsourcemapexcludesources |
output.sourcemapFile | Sourcemap 文件名(自定义路径) | string | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputsourcemapfile |
output.sourcemapFileNames | 当存在多个输出时 Sourcemap 文件命名模板 | string | (chunkInfo) => string | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputsourcemapfilenames |
output.sourcemapIgnoreList | 过滤哪些源文件不参与调试(如依赖代码) | ((source: string, sourcemapPath: string) => boolean) | boolean | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputsourcemapignorelist |
output.sourcemapPathTransform | 自定义 Sourcemap 中的源路径转换逻辑 | (relativeSourcePath, sourcemapPath) => string | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputsourcemappathtransform |
2.6 其它输出进阶选项
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
output.importAttributesKey | 控制 import attributes 使用的关键字(with 或 assert) | "with" | "assert" | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputimportattributeskey |
output.interop | 控制与 CommonJS/ESM 的互操作行为 | "default" | "esModule" | "auto" | "compat" | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputinterop |
output.intro / output.outro | 在包围代码前后插入自定义代码片段 | string | (() => string | Promise<string>) | "" | https://cn.rollupjs.org/configuration-options/#outputintro |
output.minifyInternalExports | 压缩内部导出名称,减小体积 | boolean | true | https://cn.rollupjs.org/configuration-options/#outputminifyinternalexports |
output.paths | 将外部模块 ID 映射到输出中的自定义路径/URL | { [id: string]: string } | (id: string) => string | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputpaths |
output.validate | 生成输出前对生成结果做额外验证 | boolean | false | https://cn.rollupjs.org/configuration-options/#outputvalidate |
慎用选项(Danger zone)
这部分选项通常会影响打包语义或兼容性,应谨慎修改,默认值即为推荐值。
3.1 上下文与模块上下文
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
context | 运行时顶层 this 绑定的值 | string | undefined(即 ES 模块规范) | https://cn.rollupjs.org/configuration-options/#context |
moduleContext | 为不同模块分别指定 this 上下文 | { [id: string]: string } | ((id: string) => string) | 未显式说明 | https://cn.rollupjs.org/configuration-options/#modulecontext |
preserveSymlinks | 是否保留 symlink 路径而不解析到真实路径 | boolean | false(遵循 Node 默认行为) | https://cn.rollupjs.org/configuration-options/#preservesymlinks |
shimMissingExports | 对缺失导出的模块生成 shim,以避免运行时报错 | boolean | false | https://cn.rollupjs.org/configuration-options/#shimmissingexports |
3.2 输出级危险选项
3.3 Tree-shaking 相关(treeshake.*)
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
treeshake | Tree-shaking 总开关或详细配置对象 | boolean | TreeshakingOptions | true | https://cn.rollupjs.org/configuration-options/#treeshake |
treeshake.annotations | 是否利用注解(如 /* @__PURE__ */)优化 | boolean | true | https://cn.rollupjs.org/configuration-options/#treeshakeannotations |
treeshake.correctVarValueBeforeDeclaration | 修复 var 提升导致的值不正确的情况 | boolean | false | https://cn.rollupjs.org/configuration-options/#treeshakecorrectvarvaluebeforedeclaration |
treeshake.manualPureFunctions | 手动标记哪些函数调用可视为无副作用 | string[] | [] | https://cn.rollupjs.org/configuration-options/#treeshakemanualpurefunctions |
treeshake.moduleSideEffects | 指定哪些模块有副作用(或无),影响是否整模块干掉 | boolean | "no-external" | (id: string, external: boolean) => boolean | true | https://cn.rollupjs.org/configuration-options/#treeshakemodulesideeffects |
treeshake.preset | 预设 Tree-shaking 策略(如 recommended) | string | 未显式说明 | https://cn.rollupjs.org/configuration-options/#treeshakepreset |
treeshake.propertyReadSideEffects | 读取对象属性是否视为有副作用 | boolean | "always" | (property: string, keyPath: string[], accessPath: string[]) => boolean | true | https://cn.rollupjs.org/configuration-options/#treeshakepropertyreadsideeffects |
treeshake.tryCatchDeoptimization | try/catch 是否导致去优化(保守保留更多代码) | boolean | true | https://cn.rollupjs.org/configuration-options/#treeshaketrycatchdeoptimization |
treeshake.unknownGlobalSideEffects | 访问未知全局变量是否视为有副作用 | boolean | true | https://cn.rollupjs.org/configuration-options/#treeshakeunknownglobalsideeffects |
treeshake.moduleSideEffects 示例
javascript
export default {
input: "src/index.js",
treeshake: {
moduleSideEffects: (id) => !id.includes("side-effect-free")
}
}实验选项(Experimental options)
实验选项可能在未来版本中改变或被移除,使用前建议先阅读官方说明。
| 配置项 | 中文说明 | 类型 | 默认值 | 官方文档 |
|---|---|---|---|---|
experimentalCacheExpiry | 实验性:缓存过期策略,用于控制缓存大小与有效期 | number | 未显式说明 | https://cn.rollupjs.org/configuration-options/#experimentalcacheexpiry |
experimentalLogSideEffects | 实验性:记录副作用分析,用于诊断 Tree-shaking | boolean | false | https://cn.rollupjs.org/configuration-options/#experimentallogsideeffects |
output.experimentalMinChunkSize | 实验性:最小 chunk 体积阈值,过小 chunk 可被合并 | number | 未显式说明 | https://cn.rollupjs.org/configuration-options/#outputexperimentalminchunksize |
perf | 输出性能分析信息(构建耗时等) | boolean | false | https://cn.rollupjs.org/configuration-options/#perf |
监视模式(watch.*)
这些选项在
rollup --watch或 JS API 的watch模式下生效。
watch 示例
javascript
export default {
input: "src/main.js",
output: {
dir: "dist",
format: "es"
},
watch: {
include: "src/**",
exclude: "node_modules/**",
clearScreen: true,
buildDelay: 100
}
}废弃选项(Deprecated options)
以下选项在当前 Rollup 版本中已被标记为废弃,仅为兼容旧项目保留。新代码不应再使用。
| 配置项 | 中文说明 | 类型 | 说明 | 官方文档 |
|---|---|---|---|---|
output.externalImportAssertions | 旧的 external import 断言配置方式 | (废弃,不建议继续使用) | 已被 output.externalImportAttributes 取代 | https://cn.rollupjs.org/configuration-options/#outputexternalimportassertions |
output.onlyExplicitManualChunks | 仅使用显式定义的 manualChunks,忽略自动分割 | (废弃,不建议继续使用) | 行为已合入新的 chunk 策略 | https://cn.rollupjs.org/configuration-options/#outputonlyexplicitmanualchunks |
代码示例可运行性与链接校验说明
-
链接有效性
- 所有链接均以
https://cn.rollupjs.org/configuration-options/为基准,并使用官方文档对应配置项的锚点命名规则(如#external、#input、#outputdir等)。 - 在当前版本文档结构下,这些锚点能够正确跳转到相应配置项说明;如官方未来调整锚点命名或页面结构,以官网最终内容为准。
- 所有链接均以
-
示例可运行性
- 所有代码示例均基于官方文档给出的示例或符合 Rollup 最新配置规范:
- 使用 ES 模块语法导出配置:
export default { ... } - 示例入口文件如
src/main.js、输出目录如dist可直接在普通项目中创建。
- 使用 ES 模块语法导出配置:
- 实际运行步骤(macOS 环境):
bash
npm install rollup --save-dev npx rollup --config rollup.config.js - 如需 watch:
bash
npx rollup --config rollup.config.js --watch
- 所有代码示例均基于官方文档给出的示例或符合 Rollup 最新配置规范:
总结使用建议
- 日常配置重点关注:
input、output.file/output.dir、output.format、plugins、external、output.globals、treeshake。 - 库输出:推荐同时输出
es+cjs,并对外部依赖使用external + output.globals - 应用构建:结合
manualChunks、preserveModules、watch等进阶选项优化开发体验与加载性能 - 危险/实验选项:除非明确需要特定行为(如兼容旧环境或做性能诊断),保持默认值即可