{T}

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 es

1.2 JSX 相关选项

配置项中文说明类型默认值官方文档
jsx是否启用 JSX 支持以及相关配置总入口,可以保留或转换 JSXfalse | JsxOptions未显式说明(未配置时默认不处理 JSX)https://cn.rollupjs.org/configuration-options/#jsx
jsx.modeJSX 处理模式:保留、经典(React.createElement)或自动(React 17 新 JSX Transform)"preserve" | "classic" | "automatic"未显式说明(由 preset 或配置决定)https://cn.rollupjs.org/configuration-options/#jsxmode
jsx.factory经典/自动模式下 JSX 元素工厂函数名(如 React.createElementhstring | null未显式说明(常见库通过预设给出)https://cn.rollupjs.org/configuration-options/#jsxfactory
jsx.fragment片段元素工厂函数名(如 React.Fragmentstring | null未显式说明https://cn.rollupjs.org/configuration-options/#jsxfragment
jsx.importSourceJSX 辅助函数从哪个包导入(例如 reactpreactstring | null未显式说明https://cn.rollupjs.org/configuration-options/#jsximportsource
jsx.jsxImportSource自动模式使用的新 JSX runtime 包名(如 reactstring未显式说明https://cn.rollupjs.org/configuration-options/#jsxjsximportsource
jsx.preset快速应用一组预设(如 React/Preact,对 modefactory 等统一配置)"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输出模块格式:escjsumdiifesystem"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.nameformatumd/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"truehttps://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将已废弃特性的使用视为错误而非警告booleanfalsehttps://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].jshttps://cn.rollupjs.org/configuration-options/#outputchunkfilenames
output.compact尽量压缩输出中的空白字符booleanfalsehttps://cn.rollupjs.org/configuration-options/#outputcompact
output.entryFileNames入口 chunk 命名模板string | (chunkInfo) => string未显式说明(通常为 [name].jshttps://cn.rollupjs.org/configuration-options/#outputentryfilenames
output.extendUMD/IIFE 格式下是否扩展已存在的全局变量而不是覆盖booleanfalsehttps://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.*

配置项中文说明类型默认值官方文档
output.generatedCode代码生成策略总开关,可整体预设或单项控制GeneratedCodeOptions | "es5" | "es2015" | "es2017" 等预设未显式说明https://cn.rollupjs.org/configuration-options/#outputgeneratedcode
output.generatedCode.arrowFunctions是否使用箭头函数(false 则降级为普通函数)booleantrue(与预设相关)https://cn.rollupjs.org/configuration-options/#outputgeneratedcodearrowfunctions
output.generatedCode.constBindings是否使用 const 绑定(否则使用 varbooleantruehttps://cn.rollupjs.org/configuration-options/#outputgeneratedcodeconstbindings
output.generatedCode.objectShorthand是否使用对象属性简写({ foo }booleantruehttps://cn.rollupjs.org/configuration-options/#outputgeneratedcodeobjectshorthand
output.generatedCode.preset快捷选择生成代码预设(如 es5 等)string未显式说明https://cn.rollupjs.org/configuration-options/#outputgeneratedcodepreset
output.generatedCode.reservedNamesAsProps保留某些名字作为属性而非变量,以避免压缩冲突boolean未显式说明https://cn.rollupjs.org/configuration-options/#outputgeneratedcodereservednamesasprops
output.generatedCode.symbols是否使用 Symbol 等高级特性boolean未显式说明https://cn.rollupjs.org/configuration-options/#outputgeneratedcodesymbols

2.4 代码分割与手动分 chunk

配置项中文说明类型默认值官方文档
output.dynamicImportInCjs当输出为 CJS 时是否保留动态导入(或如何转换)boolean未显式说明https://cn.rollupjs.org/configuration-options/#outputdynamicimportincjs
output.inlineDynamicImports是否将动态导入内联到同一文件中(禁用代码分割)booleanfalsehttps://cn.rollupjs.org/configuration-options/#outputinlinedynamicimports
output.manualChunks手动指定哪些模块打到哪个 chunk 中,实现更精细的代码分割{ [chunkName: string]: string[] } | (id: string, meta) => string | nullundefinedhttps://cn.rollupjs.org/configuration-options/#outputmanualchunks
output.hoistTransitiveImports是否将入口的传递依赖“提升”为入口的直接 imports,以优化加载顺序booleantruehttps://cn.rollupjs.org/configuration-options/#outputhoisttransitiveimports
output.preserveModules按原始模块结构输出多个文件(每个输入模块单独一个 chunk)booleanfalsehttps://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是否生成 Sourcemapboolean | "inline" | "hidden"falsehttps://cn.rollupjs.org/configuration-options/#outputsourcemap
output.sourcemapBaseUrlSourcemap 中引用源码的基准 URLstring未显式说明https://cn.rollupjs.org/configuration-options/#outputsourcemapbaseurl
output.sourcemapDebugIds为调试用途生成更稳定的 chunk idbooleanfalsehttps://cn.rollupjs.org/configuration-options/#outputsourcemapdebugids
output.sourcemapExcludeSources是否在 sourcemap 中排除源码内容,仅保留映射booleanfalsehttps://cn.rollupjs.org/configuration-options/#outputsourcemapexcludesources
output.sourcemapFileSourcemap 文件名(自定义路径)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 使用的关键字(withassert"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压缩内部导出名称,减小体积booleantruehttps://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生成输出前对生成结果做额外验证booleanfalsehttps://cn.rollupjs.org/configuration-options/#outputvalidate

慎用选项(Danger zone)

这部分选项通常会影响打包语义或兼容性,应谨慎修改,默认值即为推荐值。

3.1 上下文与模块上下文

配置项中文说明类型默认值官方文档
context运行时顶层 this 绑定的值stringundefined(即 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 路径而不解析到真实路径booleanfalse(遵循 Node 默认行为)https://cn.rollupjs.org/configuration-options/#preservesymlinks
shimMissingExports对缺失导出的模块生成 shim,以避免运行时报错booleanfalsehttps://cn.rollupjs.org/configuration-options/#shimmissingexports

3.2 输出级危险选项

配置项中文说明类型默认值官方文档
output.amdAMD 输出的额外配置AmdOptions未显式说明https://cn.rollupjs.org/configuration-options/#outputamd
output.amd.idAMD 模块 IDstring未显式说明https://cn.rollupjs.org/configuration-options/#outputamdid
output.amd.autoId是否自动生成 AMD IDbooleanfalsehttps://cn.rollupjs.org/configuration-options/#outputamdautoid
output.amd.basePathAMD 输出时基础路径前缀string""https://cn.rollupjs.org/configuration-options/#outputamdbasepath
output.amd.define自定义 define 函数名string"define"https://cn.rollupjs.org/configuration-options/#outputamddefine
output.amd.forceJsExtensionForImportsAMD 输出的 import 是否强制 .js 后缀booleanfalsehttps://cn.rollupjs.org/configuration-options/#outputamdforcejsextensionforimports
output.esModule是否在 CJS/UMD 中添加 __esModule 标记booleantruehttps://cn.rollupjs.org/configuration-options/#outputesmodule
output.exports指定 CJS 导出类型 (default/named/auto/none)"default" | "named" | "auto" | "none""auto"https://cn.rollupjs.org/configuration-options/#outputexports
output.externalLiveBindings是否为 external 保持 live binding 语义booleantruehttps://cn.rollupjs.org/configuration-options/#outputexternallivebindings
output.freeze是否冻结导出的对象(Object.freeze)booleantruehttps://cn.rollupjs.org/configuration-options/#outputfreeze
output.indent输出缩进风格boolean | stringtrue(启用默认缩进)https://cn.rollupjs.org/configuration-options/#outputindent
output.noConflictUMD 模式下是否使用 noConflict 模式避免覆盖全局变量booleanfalsehttps://cn.rollupjs.org/configuration-options/#outputnoconflict
output.reexportProtoFromExternal是否从 external 中再导出原型(极少用)booleanfalsehttps://cn.rollupjs.org/configuration-options/#outputreexportprotofromexternal
output.sanitizeFileName对输出文件名进行清洗,避免非法字符boolean | (fileName: string) => stringtruehttps://cn.rollupjs.org/configuration-options/#outputsanitizefilename
output.strict是否在 bundle 中启用 "use strict";booleantruehttps://cn.rollupjs.org/configuration-options/#outputstrict
output.systemNullSettersSystemJS 输出中是否为空导入生成 setterbooleantruehttps://cn.rollupjs.org/configuration-options/#outputsystemnullsetters

3.3 Tree-shaking 相关(treeshake.*

配置项中文说明类型默认值官方文档
treeshakeTree-shaking 总开关或详细配置对象boolean | TreeshakingOptionstruehttps://cn.rollupjs.org/configuration-options/#treeshake
treeshake.annotations是否利用注解(如 /* @__PURE__ */)优化booleantruehttps://cn.rollupjs.org/configuration-options/#treeshakeannotations
treeshake.correctVarValueBeforeDeclaration修复 var 提升导致的值不正确的情况booleanfalsehttps://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) => booleantruehttps://cn.rollupjs.org/configuration-options/#treeshakemodulesideeffects
treeshake.preset预设 Tree-shaking 策略(如 recommendedstring未显式说明https://cn.rollupjs.org/configuration-options/#treeshakepreset
treeshake.propertyReadSideEffects读取对象属性是否视为有副作用boolean | "always" | (property: string, keyPath: string[], accessPath: string[]) => booleantruehttps://cn.rollupjs.org/configuration-options/#treeshakepropertyreadsideeffects
treeshake.tryCatchDeoptimizationtry/catch 是否导致去优化(保守保留更多代码)booleantruehttps://cn.rollupjs.org/configuration-options/#treeshaketrycatchdeoptimization
treeshake.unknownGlobalSideEffects访问未知全局变量是否视为有副作用booleantruehttps://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-shakingbooleanfalsehttps://cn.rollupjs.org/configuration-options/#experimentallogsideeffects
output.experimentalMinChunkSize实验性:最小 chunk 体积阈值,过小 chunk 可被合并number未显式说明https://cn.rollupjs.org/configuration-options/#outputexperimentalminchunksize
perf输出性能分析信息(构建耗时等)booleanfalsehttps://cn.rollupjs.org/configuration-options/#perf

监视模式(watch.*

这些选项在 rollup --watch 或 JS API 的 watch 模式下生效。

配置项中文说明类型默认值官方文档
watchwatch 模式的整体配置对象WatchOptions未显式说明https://cn.rollupjs.org/configuration-options/#watch
watch.allowInputInsideOutputPath是否允许输入文件位于输出目录中(一般不推荐)booleanfalsehttps://cn.rollupjs.org/configuration-options/#watchallowinputinsideoutputpath
watch.buildDelay侦测到文件变更后延迟多少毫秒再触发构建number未显式说明https://cn.rollupjs.org/configuration-options/#watchbuilddelay
watch.chokidar使用 chokidar 的额外选项(启用高级文件监视)boolean | objectfalse 或未显式说明https://cn.rollupjs.org/configuration-options/#watchchokidar
watch.clearScreen每次重构建时是否清空终端输出booleantruehttps://cn.rollupjs.org/configuration-options/#watchclearscreen
watch.exclude排除不需要 watch 的文件(glob 模式)string | string[]["node_modules/**"](典型默认)https://cn.rollupjs.org/configuration-options/#watchexclude
watch.include仅包含需要 watch 的文件(glob 模式)string | string[]未显式说明https://cn.rollupjs.org/configuration-options/#watchinclude
watch.skipWrite只构建但不写入文件,常用于调试插件booleanfalsehttps://cn.rollupjs.org/configuration-options/#watchskipwrite
watch.onInvalidate每次无效化(重新构建前)调用的钩子,可清理资源(filename: string) => void未显式说明https://cn.rollupjs.org/configuration-options/#watchoninvalidate

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 可直接在普通项目中创建。
    • 实际运行步骤(macOS 环境):
      bash
      npm install rollup --save-dev
      npx rollup --config rollup.config.js
    • 如需 watch:
      bash
      npx rollup --config rollup.config.js --watch

总结使用建议

  • 日常配置重点关注inputoutput.file / output.diroutput.formatpluginsexternaloutput.globalstreeshake
  • 库输出:推荐同时输出 es + cjs,并对外部依赖使用 external + output.globals
  • 应用构建:结合 manualChunkspreserveModuleswatch 等进阶选项优化开发体验与加载性能
  • 危险/实验选项:除非明确需要特定行为(如兼容旧环境或做性能诊断),保持默认值即可