命令行界面

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

配置文件

Rolldown 配置文件是可选的，但它们功能强大且方便，因此推荐使用。 配置文件是一个 ES 模块，它导出一个包含所需选项的默认对象。 通常，它被命名为 rolldown.config.js，并位于项目的根目录中。 你也可以在 CJS 文件中使用 CJS 语法，此时使用 module.exports 而不是 export default。 Rolldown 也原生支持 TypeScript 配置文件。

请参阅 参考 以获取可包含在配置文件中的完整选项列表。

rolldown.config.js

export default {
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
    format: 'cjs',
  },
};

要在 Rolldown 中使用配置文件，请传入 -c（或 --config）标志：

rolldown -c                 # 使用 rolldown.config.{js,mjs,cjs,ts,mts,cts}
rolldown --config           # 同上
rolldown -c my.config.js    # 使用自定义配置文件

如果你不传入文件名，Rolldown 将尝试在工作目录中加载 rolldown.config.{js,mjs,cjs,ts,mts,cts}。 如果未找到配置文件，Rolldown 将显示错误。

你也可以从配置文件中导出一个函数。该函数会使用命令行参数调用，因此你可以动态调整配置：

rolldown.config.js

import { defineConfig } from 'rolldown';

export default defineConfig((commandLineArgs) => {
  if (commandLineArgs.watch) {
    // 仅用于 watch 的配置
  }
  return {
    input: 'src/main.js',
  };
});

配置智能提示

由于 Rolldown 附带 TypeScript 类型定义，你可以利用 IDE 的 JSDoc 类型提示获得智能提示：

rolldown.config.js

/** @type {import('rolldown').RolldownOptions} */
export default {
  // ...
};

或者，你也可以使用 defineConfig 辅助函数，它无需 JSDoc 注解即可提供智能提示：

rolldown.config.js

import { defineConfig } from 'rolldown';

export default defineConfig({
  // ...
});

配置数组

要从不同输入构建不同的 bundle，你可以提供一个配置对象数组：

rolldown.config.js

import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    input: 'src/main.js',
    output: { format: 'esm', entryFileNames: 'bundle.esm.js' },
  },
  {
    input: 'src/main.js',
    output: { format: 'cjs', entryFileNames: 'bundle.cjs.js' },
  },
]);

相同输入的不同输出

你也可以为 output 选项提供一个数组，以便从相同输入生成多个输出：

rolldown.config.js

import { defineConfig } from 'rolldown';

export default defineConfig({
  input: 'src/main.js',
  output: [
    { format: 'esm', entryFileNames: 'bundle.esm.js' },
    { format: 'cjs', entryFileNames: 'bundle.cjs.js' },
  ],
});

命令行标志

标志可以通过 --foo、--foo <value> 或 --foo=<value> 传入。像 --minify 这样的布尔标志不需要值，而像 --transform.define 这样的键值选项使用逗号分隔语法：--transform.define key:value,key2:value2。许多标志都有简写别名（例如，-m 对应 --minify，-f 对应 --format）。

集成到其他工具中

请注意，在 Rolldown 看到参数之前，你的 shell 会先对它们进行解释——引号和通配符的行为可能会出乎意料。对于高级构建流程或集成到其他工具中，建议改用 JavaScript API。从配置文件切换到 API 时的关键区别：

• 配置必须是对象（不能是 Promise 或函数）
• 对每一组 inputOptions 分别运行 rolldown.rolldown（不支持配置数组）
• 使用 bundle.generate(outputOptions) 或 bundle.write(outputOptions) 来替代 output 选项

许多选项都有对应的命令行标志。 有关这些标志的详细信息，请参阅 参考。 在这些情况下，如果你使用了配置文件，这里传入的任何参数都会覆盖配置文件中的设置。 下面是所有受支持标志的列表：

Fast JavaScript/TypeScript bundler in Rust with Rollup-compatible API. (rolldown v1.0.0-rc.17)

USAGE rolldown -c <config> or rolldown <input> <options>

OPTIONS

  --config -c, <filename>     Path to the config file (default: `rolldown.config.js`).
  --dir -d, <dir>             Output directory, defaults to `dist` if `file` is not set.
  --external -e, <external>   Comma-separated list of module ids to exclude from the bundle `<module-id>,...`.
  --format -f, <format>       Output format of the generated bundle (supports esm, cjs, and iife).
  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: `key:value`).
  --help -h,                  Show help.
  --minify -m,                Minify the bundled file.
  --name -n, <name>           Name for UMD / IIFE format outputs.
  --file -o, <file>           Single output file.
  --platform -p, <platform>   Platform for which the code should be generated (node, browser, neutral).
  --sourcemap -s, <sourcemap> Generate sourcemap (`-s inline` for inline, or `-s` for `.map` file).
  --version -v,               Show version number.
  --watch -w,                 Watch files in bundle and rebuild on changes.
  --advanced-chunks.min-share-count <advanced-chunks.min-share-count>Minimum share count of the chunk.
  --advanced-chunks.min-size <advanced-chunks.min-size>Minimum size of the chunk.
  --asset-file-names <name>   Name pattern for asset files.
  --banner <banner>           Code to insert the top of the bundled file (outside the wrapper function).
  --checks.cannot-call-namespace Whether to emit warnings when a namespace is called as a function.
  --checks.circular-dependency Whether to emit warnings when detecting circular dependency.
  --checks.common-js-variable-in-esm Whether to emit warnings when a CommonJS variable is used in an ES module.
  --checks.configuration-field-conflict Whether to emit warnings when a config value is overridden by another config value with a higher priority.
  --checks.could-not-clean-directory Whether to emit warnings when Rolldown could not clean the output directory.
  --checks.duplicate-shebang  Whether to emit warnings when both the code and postBanner contain shebang.
  --checks.empty-import-meta  Whether to emit warnings when `import.meta` is not supported with the output format and is replaced with an empty object (`{}`).
  --checks.eval               Whether to emit warnings when detecting uses of direct `eval`s.
  --checks.filename-conflict  Whether to emit warnings when files generated have the same name with different contents.
  --checks.import-is-undefined Whether to emit warnings when an imported variable is not exported.
  --checks.ineffective-dynamic-import Whether to emit warnings when a module is dynamically imported but also statically imported, making the dynamic import ineffective for code splitting.
  --checks.missing-global-name Whether to emit warnings when the `output.globals` option is missing when needed.
  --checks.missing-name-option-for-iife-export Whether to emit warnings when the `output.name` option is missing when needed.
  --checks.mixed-exports      Whether to emit warnings when the way to export values is ambiguous.
  --checks.plugin-timings     Whether to emit warnings when plugins take significant time during the build process.
  --checks.prefer-builtin-feature Whether to emit warnings when a plugin that is covered by a built-in feature is used.
  --checks.tolerated-transform Whether to emit warnings when detecting tolerated transform.
  --checks.unresolved-entry   Whether to emit warnings when an entrypoint cannot be resolved.
  --checks.unresolved-import  Whether to emit warnings when an import cannot be resolved.
  --checks.unsupported-tsconfig-option Whether to emit warnings when a tsconfig option or combination of options is not supported.
  --chunk-file-names <name>   Name pattern for emitted secondary chunks.
  --clean-dir                 Clean output directory before emitting output.
  --code-splitting <code-splitting>Code splitting options (true, false, or object).
  --comments <comments>       Control comments in the output.
  --context <context>         The entity top-level `this` represents.
  --cwd <cwd>                 Current working directory.
  --devtools.session-id <devtools.session-id>Used to name the build.
  --dynamic-import-in-cjs     Dynamic import in CJS output.
  --entry-file-names <name>   Name pattern for emitted entry chunks.
  --environment <environment> Pass additional settings to the config file via process.ENV.
  --es-module                 Always generate `__esModule` marks in non-ESM formats, defaults to `if-default-prop` (use `--no-esModule` to always disable).
  --exports <exports>         Specify a export mode (auto, named, default, none).
  --extend                    Extend global variable defined by name in IIFE / UMD formats.
  --footer <footer>           Code to insert the bottom of the bundled file (outside the wrapper function).
  --generated-code.preset <generated-code.preset>.
  --generated-code.profiler-names Whether to add readable names to internal variables for profiling purposes.
  --generated-code.symbols    Whether to use Symbol.toStringTag for namespace objects.
  --hash-characters <hash-characters>Use the specified character set for file hashes.
  --inline-dynamic-imports    Inline dynamic imports.
  --input <input>             Entry file.
  --intro <intro>             Code to insert the top of the bundled file (inside the wrapper function).
  --keep-names                Keep function and class names after bundling.
  --legal-comments <legal-comments>Control legal comments in the output.
  --log-level <log-level>     Log level (silent, info, debug, warn).
  --make-absolute-externals-relative Prevent normalization of external imports.
  --minify-internal-exports   Minify internal exports.
  --module-types <types>      Module types for customized extensions.
  --no-external-live-bindings Disable external live bindings.
  --no-preserve-entry-signatures Avoid facade chunks for entry points.
  --no-treeshake              Disable treeshaking.
  --optimization.inline-const <optimization.inline-const>Enable crossmodule constant inlining.
  --optimization.pife-for-module-wrappers Use PIFE pattern for module wrappers.
  --outro <outro>             Code to insert the bottom of the bundled file (inside the wrapper function).
  --paths <paths>             Maps external module IDs to paths.
  --polyfill-require          Disable require polyfill injection.
  --post-banner <post-banner> A string to prepend to the top of each chunk. Applied after the `renderChunk` hook and minification.
  --post-footer <post-footer> A string to append to the bottom of each chunk. Applied after the `renderChunk` hook and minification.
  --preserve-modules          Preserve module structure.
  --preserve-modules-root <preserve-modules-root>Put preserved modules under this path at root level.
  --sanitize-file-name        Sanitize file name.
  --shim-missing-exports      Create shim variables for missing exports.
  --sourcemap-base-url <sourcemap-base-url>Base URL used to prefix sourcemap paths.
  --sourcemap-debug-ids       Inject sourcemap debug IDs.
  --sourcemap-exclude-sources Exclude source content from sourcemaps.
  --strict <strict>           Whether to always output `"use strict"` directive in non-ES module outputs.
  --strict-execution-order    Lets modules be executed in the order they are declared.
  --top-level-var             Rewrite top-level declarations to use `var`.
  --transform.assumptions.ignore-function-length .
  --transform.assumptions.no-document-all .
  --transform.assumptions.object-rest-no-symbols .
  --transform.assumptions.pure-getters .
  --transform.assumptions.set-public-class-fields .
  --transform.decorator.emit-decorator-metadata .
  --transform.decorator.legacy .
  --transform.define <transform.define>Define global variables (syntax: key:value,key2:value2).
  --transform.drop-labels <transform.drop-labels>Remove labeled statements with these label names.
  --transform.helpers.mode <transform.helpers.mode>.
  --transform.inject <transform.inject>Inject import statements on demand.
  --transform.jsx <transform.jsx>.
  --transform.plugins.styled-components <transform.plugins.styled-components>.
  --transform.plugins.tagged-template-escape .
  --transform.target <transform.target>The JavaScript target environment.
  --transform.typescript.allow-declare-fields .
  --transform.typescript.allow-namespaces .
  --transform.typescript.declaration.sourcemap .
  --transform.typescript.declaration.strip-internal .
  --transform.typescript.jsx-pragma <transform.typescript.jsx-pragma>.
  --transform.typescript.jsx-pragma-frag <transform.typescript.jsx-pragma-frag>.
  --transform.typescript.only-remove-type-imports .
  --transform.typescript.optimize-const-enums .
  --transform.typescript.optimize-enums .
  --transform.typescript.remove-class-fields-without-initializer .
  --transform.typescript.rewrite-import-extensions <transform.typescript.rewrite-import-extensions>.
  --tsconfig <tsconfig>       Path to the tsconfig.json file.
  --virtual-dirname <virtual-dirname>.

EXAMPLES

  1. Bundle with a config file `rolldown.config.mjs`:
    rolldown -c rolldown.config.mjs

  2. Bundle the `src/main.ts` to `dist` with `cjs` format:
    rolldown src/main.ts -d dist -f cjs

  3. Bundle the `src/main.ts` and handle the `.png` assets to Data URL:
    rolldown src/main.ts -d dist --moduleTypes .png=dataurl

  4. Bundle the `src/main.tsx` and minify the output with sourcemap:
    rolldown src/main.tsx -d dist -m -s

  5. Create self-executing IIFE using external jQuery as `$` and `_`:
    rolldown src/main.ts -d dist -n bundle -f iife -e jQuery,window._ -g jQuery=$

NOTES

  * CLI options will override the configuration file.
  * For more information, please visit https://rolldown.rs/.

下面列出的标志仅可通过命令行界面使用。

-c, --config <filename>

使用指定的配置文件。如果使用了该参数但未指定文件名，Rolldown 将查找默认配置文件。有关更多详细信息，请参阅 配置文件。

-h / --help

显示帮助信息。

-v / --version

显示已安装的版本号。

-w / --watch

当源文件在磁盘上发生变化时重新构建 bundle。

ROLLDOWN_WATCH 环境变量

在 watch 模式下，Rolldown 的命令行界面会将 ROLLDOWN_WATCH 和 ROLLUP_WATCH 环境变量设置为 true，并且可以被其他进程检查。插件应改为检查 this.meta.watchMode，它不依赖于命令行界面。

--environment <values>

通过 process.env 向配置文件传递额外设置。 值是以逗号分隔的键值对，其中值为 true 时可以省略。

例如：

rolldown -c --environment INCLUDE_DEPS,BUILD:production

这会设置 process.env.INCLUDE_DEPS = 'true' 和 process.env.BUILD = 'production'。

你可以多次使用此选项。 在这种情况下，后续设置的变量将覆盖先前的定义。

覆盖这些值

如果你有 package.json 脚本：

{
  "scripts": {
    "build": "rolldown -c --environment BUILD:production"
  }
}

你可以通过 npm run build -- --environment BUILD:development 来调用此脚本，以设置 process.env.BUILD="development"。