Rolldown 中文网

Appearance

output ​

输出包的配置选项。这些选项控制 Rolldown 如何生成最终的打包文件。

¥Configuration options for the output bundle. These options control how Rolldown generates the final bundled files.

dir ​

  • 类型：string

    ¥Type: string

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.dir

    ¥Path: output.dir

输出文件的写入目录。使用多个入口点时必须使用。

¥The directory where output files will be written. Required when using multiple entry points.

示例 ​

¥Examples

js
export default {
  input: {
    main: 'src/index.js',
    admin: 'src/admin.js',
  },
  output: {
    dir: 'dist',
  },
};

file ​

  • 类型：string

    ¥Type: string

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.file

    ¥Path: output.file

输出包的文件路径。用于单条目构建。

¥The file path for the output bundle. Used for single entry builds.

示例 ​

¥Examples

js
export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
  },
};

深入探讨 ​

¥In-depth

单入口构建使用 file，多入口构建使用 dir。

¥Use file for single-entry builds and dir for multi-entry builds.

exports ​

  • 类型：'auto' | 'named' | 'default' | 'none'

    ¥Type: 'auto' | 'named' | 'default' | 'none'

  • 默认值：'auto'

    ¥Default: 'auto'

  • 路径：output.exports

    ¥Path: output.exports

指定打包使用的导出模式。

¥Specifies what export mode to use for the bundle.

示例 ​

¥Examples

js
export default {
  output: {
    format: 'cjs',
    exports: 'named',
  },
};

深入探讨 ​

¥In-depth

可用的模式：

¥The available modes:

  • 'auto'：根据入口模块的导出自动确定导出模式（推荐）

    ¥'auto': Automatically determines the export mode based on the entry module's exports (recommended)

  • 'named'：导出将作为命名导出公开

    ¥'named': Exports are exposed as named exports

  • 'default'：入口模块的默认导出用作主导出。

    ¥'default': The entry module's default export is used as the main export

  • 'none'：无导出（适用于仅产生副作用的 bundles）

    ¥'none': No exports (useful for side-effect-only bundles)

hashCharacters ​

  • 类型：'base64' | 'base36' | 'hex'

    ¥Type: 'base64' | 'base36' | 'hex'

  • 默认值：'base64'

    ¥Default: 'base64'

  • 路径：output.hashCharacters

    ¥Path: output.hashCharacters

文件名中内容哈希值使用的字符集。

¥The character set to use for content hashes in file names.

示例 ​

¥Examples

js
export default {
  output: {
    hashCharacters: 'hex',
    entryFileNames: '[name]-[hash].js',
  },
};

深入探讨 ​

¥In-depth

可用的字符集：

¥The available character sets:

  • 'base64'：使用 base64 字符（最短哈希值）

    ¥'base64': Uses base64 characters (shortest hashes)

  • 'base36'：使用字母数字字符（0-9、a-z）

    ¥'base36': Uses alphanumeric characters (0-9, a-z)

  • 'hex'：使用十六进制字符（0-9、a-f）

    ¥'hex': Uses hexadecimal characters (0-9, a-f)

format ​

  • 类型：'es' | 'cjs' | 'esm' | 'module' | 'commonjs' | 'iife' | 'umd'

    ¥Type: 'es' | 'cjs' | 'esm' | 'module' | 'commonjs' | 'iife' | 'umd'

  • 默认值：'esm'

    ¥Default: 'esm'

  • 路径：output.format

    ¥Path: output.format

生成代码的预期格式。

¥Expected format of generated code.

示例 ​

¥Examples

js
export default {
  output: {
    format: 'esm',
  },
};

深入探讨 ​

¥In-depth

可用的格式：

¥The available formats:

  • 'es', 'esm', 'module':ES 模块格式（使用 import 和 export）

    ¥'es', 'esm', 'module': ES module format (uses import and export)

  • 'cjs', 'commonjs':CommonJS 格式（使用 require() 和 module.exports）

    ¥'cjs', 'commonjs': CommonJS format (uses require() and module.exports)

  • 'iife'：立即调用函数表达式（需要 name 选项）

    ¥'iife': Immediately Invoked Function Expression (requires name option)

  • 'umd'：通用模块定义（需要 name 选项）

    ¥'umd': Universal Module Definition (requires name option)

sourcemap ​

  • 类型：boolean | 'inline' | 'hidden'

    ¥Type: boolean | 'inline' | 'hidden'

  • 默认值：false

    ¥Default: false

  • 路径：output.sourcemap

    ¥Path: output.sourcemap

控制源码映射的生成和配置。有关嵌套选项的详细信息，请参阅 output.sourcemap。

¥Controls source map generation and configuration. See output.sourcemap for detailed nested options.

示例 ​

¥Examples

js
export default {
  output: {
    sourcemap: true,
  },
};

  • 类型：string | ((chunk: RenderedChunk) => string | Promise<string>)

    ¥Type: string | ((chunk: RenderedChunk) => string | Promise<string>)

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.banner

    ¥Path: output.banner

添加到每个输出块开头的代码。

¥Code to prepend to the beginning of each output chunk.

示例 ​

¥Examples

js
export default {
  output: {
    banner: '/* My Library v1.0.0 | MIT License */',
  },
};

  • 类型：string | ((chunk: RenderedChunk) => string | Promise<string>)

    ¥Type: string | ((chunk: RenderedChunk) => string | Promise<string>)

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.footer

    ¥Path: output.footer

附加到每个输出代码块末尾的代码。

¥Code to append to the end of each output chunk.

示例 ​

¥Examples

js
export default {
  output: {
    footer: '/* End of bundle */',
  },
};

intro ​

  • 类型：string | ((chunk: RenderedChunk) => string | Promise<string>)

    ¥Type: string | ((chunk: RenderedChunk) => string | Promise<string>)

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.intro

    ¥Path: output.intro

附加到封装函数内部的代码（在横幅之后，实际代码之前）。

¥Code to prepend inside the wrapper function (after banner, before actual code).

示例 ​

¥Examples

js
export default {
  output: {
    format: 'iife',
    intro: 'const ENVIRONMENT = "production";',
  },
};

outro ​

  • 类型：string | ((chunk: RenderedChunk) => string | Promise<string>)

    ¥Type: string | ((chunk: RenderedChunk) => string | Promise<string>)

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.outro

    ¥Path: output.outro

附加到封装函数内部的代码（在实际代码之后，页脚之前）。

¥Code to append inside the wrapper function (after actual code, before footer).

示例 ​

¥Examples

js
export default {
  output: {
    format: 'iife',
    outro: 'console.log("Bundle loaded");',
  },
};

extend ​

  • 类型：boolean

    ¥Type: boolean

  • 默认值：false

    ¥Default: false

  • 路径：output.extend

    ¥Path: output.extend

当 true 设置为 name 时，会扩展 name 选项定义的全局变量，而不是覆盖它。仅适用于 iife 和 umd 格式。

¥When true, extends the global variable defined by the name option rather than overwriting it. Only applies to iife and umd formats.

示例 ​

¥Examples

js
export default {
  output: {
    format: 'umd',
    name: 'MyLib',
    extend: true,
  },
};

esModule ​

  • 类型：boolean | 'if-default-prop'

    ¥Type: boolean | 'if-default-prop'

  • 默认值：'if-default-prop'

    ¥Default: 'if-default-prop'

  • 路径：output.esModule

    ¥Path: output.esModule

控制在生成 CJS 输出时是否添加 __esModule: true 属性。

¥Controls whether to add a __esModule: true property when generating CJS output.

示例 ​

¥Examples

js
export default {
  output: {
    format: 'cjs',
    esModule: true,
  },
};

深入探讨 ​

¥In-depth

可用的选项：

¥The available options:

  • false：从不添加 __esModule 属性

    ¥false: Never add __esModule property

  • true：始终添加 __esModule: true 属性

    ¥true: Always add __esModule: true property

  • 'if-default-prop'：仅在存在默认导出时添加

    ¥'if-default-prop': Only add if there's a default export

assetFileNames ​

  • 类型：string | ((chunkInfo: PreRenderedAsset) => string)

    ¥Type: string | ((chunkInfo: PreRenderedAsset) => string)

  • 默认值：'assets/[name]-[hash][extname]'

    ¥Default: 'assets/[name]-[hash][extname]'

  • 路径：output.assetFileNames

    ¥Path: output.assetFileNames

用于命名资源文件（非 JavaScript 文件）的模式。

¥Pattern for naming asset files (non-JavaScript files).

占位符：[name], [hash], [extname]

¥Placeholders: [name], [hash], [extname]

示例 ​

¥Examples

js
export default {
  output: {
    assetFileNames: 'assets/[name].[hash][extname]',
  },
};

entryFileNames ​

  • 类型：string | ((chunkInfo: PreRenderedChunk) => string)

    ¥Type: string | ((chunkInfo: PreRenderedChunk) => string)

  • 默认值：'[name].js'

    ¥Default: '[name].js'

  • 路径：output.entryFileNames

    ¥Path: output.entryFileNames

入口块文件的命名模式。

¥Pattern for naming entry chunk files.

占位符：[name], [hash], [ext]

¥Placeholders: [name], [hash], [ext]

示例 ​

¥Examples

js
export default {
  output: {
    entryFileNames: '[name]-[hash].js',
  },
};

chunkFileNames ​

  • 类型：string | ((chunkInfo: PreRenderedChunk) => string)

    ¥Type: string | ((chunkInfo: PreRenderedChunk) => string)

  • 默认值：'[name]-[hash].js'

    ¥Default: '[name]-[hash].js'

  • 路径：output.chunkFileNames

    ¥Path: output.chunkFileNames

非入口块文件（代码拆分块）的命名模式。

¥Pattern for naming non-entry chunk files (code-split chunks).

占位符：[name], [hash], [ext]

¥Placeholders: [name], [hash], [ext]

示例 ​

¥Examples

js
export default {
  output: {
    chunkFileNames: 'chunks/[name].[hash].js',
  },
};

cssEntryFileNames ​

  • 类型：string | ((chunkInfo: PreRenderedChunk) => string)

    ¥Type: string | ((chunkInfo: PreRenderedChunk) => string)

  • 默认值：'[name].css'

    ¥Default: '[name].css'

  • 路径：output.cssEntryFileNames

    ¥Path: output.cssEntryFileNames

用于命名 CSS 入口文件的模式。

¥Pattern for naming CSS entry files.

占位符：[name], [hash]

¥Placeholders: [name], [hash]

示例 ​

¥Examples

js
export default {
  output: {
    cssEntryFileNames: 'styles/[name]-[hash].css',
  },
};

cssChunkFileNames ​

  • 类型：string | ((chunkInfo: PreRenderedChunk) => string)

    ¥Type: string | ((chunkInfo: PreRenderedChunk) => string)

  • 默认值：'[name]-[hash].css'

    ¥Default: '[name]-[hash].css'

  • 路径：output.cssChunkFileNames

    ¥Path: output.cssChunkFileNames

用于命名 CSS 块文件（非入口 CSS 文件）的模式。

¥Pattern for naming CSS chunk files (non-entry CSS files).

占位符：[name], [hash]

¥Placeholders: [name], [hash]

示例 ​

¥Examples

js
export default {
  output: {
    cssChunkFileNames: 'styles/chunks/[name].[hash].css',
  },
};

sanitizeFileName ​

  • 类型：boolean | ((name: string) => string)

    ¥Type: boolean | ((name: string) => string)

  • 默认值：true

    ¥Default: true

  • 路径：output.sanitizeFileName

    ¥Path: output.sanitizeFileName

控制文件名的过滤，以确保它们在不同文件系统中有效。

¥Controls sanitization of file names to ensure they're valid across different file systems.

示例 ​

¥Examples

js
export default {
  output: {
    sanitizeFileName: (name) => {
      return name.replace(/[^a-zA-Z0-9.-]/g, '_');
    },
  },
};

深入探讨 ​

¥In-depth

可用的选项：

¥The available options:

  • false：禁用清理

    ¥false: Disable sanitization

  • true：启用默认清理

    ¥true: Enable default sanitization

  • 功能：自定义清理逻辑

    ¥Function: Custom sanitization logic

minify ​

  • 类型：boolean | 'dce-only' | MinifyOptions

    ¥Type: boolean | 'dce-only' | MinifyOptions

  • 默认值：false

    ¥Default: false

  • 路径：output.minify

    ¥Path: output.minify

控制代码压缩。

¥Control code minification.

示例 ​

¥Examples

js
export default {
  output: {
    minify: true,
  },
};

深入探讨 ​

¥In-depth

可用的选项：

¥The available options:

  • false：禁用压缩

    ¥false: Disable minification

  • true：启用完全压缩

    ¥true: Enable full minification

  • 'dce-only'：仅消除死代码

    ¥'dce-only': Only dead code elimination

  • 对象：细粒度压缩设置

    ¥Object: Fine-grained minification settings

name ​

  • 类型：string

    ¥Type: string

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.name

    ¥Path: output.name

bundle 的全局变量名称。使用 iife 或 umd 格式时必须使用。

¥The global variable name for the bundle. Required when using iife or umd format.

示例 ​

¥Examples

js
export default {
  output: {
    format: 'iife',
    name: 'MyLibrary',
  },
};

globals ​

  • 类型：Record<string, string> | ((name: string) => string)

    ¥Type: Record<string, string> | ((name: string) => string)

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.globals

    ¥Path: output.globals

将外部模块 ID 映射到 iife 和 umd 格式的全局变量名。

¥Maps external module IDs to global variable names for iife and umd formats.

示例 ​

¥Examples

js
export default {
  external: ['react', 'react-dom'],
  output: {
    format: 'iife',
    name: 'MyApp',
    globals: {
      'react': 'React',
      'react-dom': 'ReactDOM',
    },
  },
};

paths ​

  • 类型：Record<string, string> | ((id: string) => string)

    ¥Type: Record<string, string> | ((id: string) => string)

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.paths

    ¥Path: output.paths

将外部模块 ID 映射到路径。用于从 CDN 加载依赖。

¥Maps external module IDs to paths. Useful for loading dependencies from CDNs.

示例 ​

¥Examples

js
export default {
  external: ['d3', 'lodash'],
  output: {
    paths: {
      'd3': 'https://cdn.jsdelivr.net/npm/d3@7',
      'lodash': 'https://cdn.jsdelivr.net/npm/lodash@4',
    },
  },
};

generatedCode ​

  • 类型：Partial<GeneratedCodeOptions>

    ¥Type: Partial<GeneratedCodeOptions>

  • 默认值：{}

    ¥Default: {}

  • 路径：output.generatedCode

    ¥Path: output.generatedCode

生成的代码输出的配置。有关嵌套选项的详细信息，请参阅 output.generatedCode。

¥Configuration for the generated code output. See output.generatedCode for nested options.

externalLiveBindings ​

  • 类型：boolean

    ¥Type: boolean

  • 默认值：true

    ¥Default: true

  • 路径：output.externalLiveBindings

    ¥Path: output.externalLiveBindings

当 true 设置为 true 时，会生成支持外部导入实时绑定的代码。

¥When true, generates code that supports live bindings for external imports.

示例 ​

¥Examples

js
export default {
  output: {
    externalLiveBindings: false,
  },
};

inlineDynamicImports ​

  • 类型：boolean

    ¥Type: boolean

  • 默认值：true 表示 'iife' 和 'umd' 格式，否则为 false

    ¥Default: true for 'iife' and 'umd' formats, false otherwise

  • 路径：output.inlineDynamicImports

    ¥Path: output.inlineDynamicImports

当 true 设置为 true 时，动态导入会内联到主 bundle 中，而不是拆分成单独的代码块。

¥When true, dynamic imports are inlined into the main bundle instead of being split into separate chunks.

示例 ​

¥Examples

js
export default {
  output: {
    inlineDynamicImports: true,
  },
};

manualChunks ​

  • 类型：(moduleId: string, meta: { getModuleInfo: (moduleId: string) => ModuleInfo | null }) => string | NullValue

    ¥Type: (moduleId: string, meta: { getModuleInfo: (moduleId: string) => ModuleInfo | null }) => string | NullValue

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.manualChunks

    ¥Path: output.manualChunks

已弃用

此选项已弃用。请使用 output.advancedChunks 代替。

¥This option is deprecated. Please use output.advancedChunks instead.

允许手动控制分块的创建。

¥Allows manual control over chunk creation.

advancedChunks ​

  • 类型：object

    ¥Type: object

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.advancedChunks

    ¥Path: output.advancedChunks

高级分块配置。有关嵌套选项的详细信息，请参阅 output.advancedChunks。

¥Advanced chunking configuration. See output.advancedChunks for nested options.

legalComments ​

  • 类型：'none' | 'inline'

    ¥Type: 'none' | 'inline'

  • 默认值：'inline'

    ¥Default: 'inline'

  • 路径：output.legalComments

    ¥Path: output.legalComments

控制输出中的注释。

¥Control comments in the output.

示例 ​

¥Examples

js
export default {
  output: {
    legalComments: 'inline',
  },
};

深入探讨 ​

¥In-depth

可用的选项：

¥The available options:

  • 'none'：删除所有注释

    ¥'none': Remove all comments

  • 'inline'：保留包含 @license、@preserve 或以 //! 或 /*! 开头的注释

    ¥'inline': Preserve comments containing @license, @preserve, or starting with //! or /*!

polyfillRequire ​

  • 类型：boolean

    ¥Type: boolean

  • 默认值：true

    ¥Default: true

  • 路径：output.polyfillRequire

    ¥Path: output.polyfillRequire

当 true 启用时，为非 CommonJS 格式的 require() 函数添加 polyfill。

¥When true, adds a polyfill for require() function in non-CommonJS formats.

示例 ​

¥Examples

js
export default {
  output: {
    format: 'esm',
    polyfillRequire: true,
  },
};

hoistTransitiveImports ​

  • 类型：boolean

    ¥Type: boolean

  • 默认值：true

    ¥Default: true

  • 路径：output.hoistTransitiveImports

    ¥Path: output.hoistTransitiveImports

当 false 设置为 false 时，会阻止将传递导入提升到入口代码块。

¥When false, prevents hoisting transitive imports to entry chunks.

示例 ​

¥Examples

js
export default {
  output: {
    hoistTransitiveImports: false,
  },
};

preserveModules ​

  • 类型：boolean

    ¥Type: boolean

  • 默认值：false

    ¥Default: false

  • 路径：output.preserveModules

    ¥Path: output.preserveModules

当 true 设置为 true 时，会保留模块结构，而不是创建单个 bundle。

¥When true, preserves the module structure instead of creating a single bundle.

示例 ​

¥Examples

js
export default {
  input: 'src/index.js',
  output: {
    dir: 'dist',
    preserveModules: true,
  },
};

virtualDirname ​

  • 类型：string

    ¥Type: string

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.virtualDirname

    ¥Path: output.virtualDirname

用于解析输出中 __dirname 和 __filename 的虚拟目录名称。

¥Virtual directory name for resolving __dirname and __filename in the output.

示例 ​

¥Examples

js
export default {
  output: {
    virtualDirname: '/virtual',
  },
};

preserveModulesRoot ​

  • 类型：string

    ¥Type: string

  • 可选：是 ✅

    ¥Optional: Yes ✅

  • 路径：output.preserveModulesRoot

    ¥Path: output.preserveModulesRoot

保存模块时使用的基准路径。所有保留的模块将相对于此路径放置。

¥Base path to use when preserving modules. All preserved modules will be placed relative to this path.

示例 ​

¥Examples

js
export default {
  output: {
    dir: 'dist',
    preserveModules: true,
    preserveModulesRoot: 'src',
  },
};

topLevelVar ​

  • 类型：boolean

    ¥Type: boolean

  • 默认值：false

    ¥Default: false

  • 路径：output.topLevelVar

    ¥Path: output.topLevelVar

当 true 设置为 var 时，会在顶层使用 var 声明，而不是函数表达式。

¥When true, uses var declarations at the top level instead of function expressions.

示例 ​

¥Examples

js
export default {
  output: {
    topLevelVar: true,
  },
};

cleanDir ​

  • 类型：boolean

    ¥Type: boolean

  • 默认值：false

    ¥Default: false

  • 路径：output.cleanDir

    ¥Path: output.cleanDir

在触发输出之前清理输出目录 (output.dir)。

¥Clean the output directory (output.dir) before emitting output.

此功能会在调用 writeBundle 钩子之前清理输出目录。如果你有高级用例，例如同一个 output.dir 有多个输出，我们建议你自行运行 rm。

¥This feature cleans the output directory before writeBundle hooks are called. If you have advanced use cases like having multiple outputs with the same output.dir, we suggest you to run rm by yourself.

示例 ​

¥Examples

js
export default {
  output: {
    cleanDir: true,
  },
};

minifyInternalExports ​

  • 类型：boolean

    ¥Type: boolean

  • 默认值：false

    ¥Default: false

  • 路径：output.minifyInternalExports

    ¥Path: output.minifyInternalExports

是否最小化内部导出（其他代码块未使用的导出）。

¥Whether to minify internal exports (exports not used by other chunks).

示例 ​

¥Examples

js
export default {
  output: {
    minifyInternalExports: true,
  },
};

keepNames ​

  • 类型：boolean

    ¥Type: boolean

  • 默认值：false

    ¥Default: false

  • 路径：output.keepNames

    ¥Path: output.keepNames

在打包过程中保留函数名和类名。

¥Preserve function and class names during bundling.

示例 ​

¥Examples

js
export default {
  output: {
    keepNames: true,
  },
};

深入探讨 ​

¥In-depth

启用后，打包器将在输出中保留函数和类的原始名称，这在以下情况下很有用：

¥When enabled, the bundler will preserve the original names of functions and classes in the output, which is useful for:

  • 调试和错误堆栈跟踪

    ¥Debugging and error stack traces

  • 依赖 Function.prototype.name 的代码

    ¥Code that relies on Function.prototype.name

  • 依赖于构造函数名称的序列化

    ¥Serialization that depends on constructor names