入门指南

¥Getting Started

🚧 测试版软件

Rolldown 目前处于测试阶段。虽然它已经可以处理大多数生产用例，但仍可能存在错误和不完善之处。最值得注意的是，内置的压缩功能仍处于早期开发阶段。

¥Rolldown is currently in beta status. While it can already handle most production use cases, there may still be bugs and rough edges. Most notably, the built-in minification feature is still in early work-in-progress status.

安装

¥Installation

npmpnpmyarnbun

$ npm install -D rolldown

$ pnpm add -D rolldown

$ yarn add -D rolldown

$ bun add -D rolldown

使用次要平台（CPU 架构、操作系统）？

预构建的二进制文件分发至以下平台（按 Node.js v22 平台支持层分组）：

¥Prebuilt binaries are distributed for the following platforms (grouped by Node.js v22 platform support tier):

Tier 1
- Linux x64 glibc (x86_64-unknown-linux-gnu)
- Linux arm64 glibc (aarch64-unknown-linux-gnu)
- Linux armv7 (armv7-unknown-linux-gnueabihf)
- Windows x64 (x86_64-pc-windows-msvc)
- Windows x86 (i686-pc-windows-msvc)
- Apple x64 (x86_64-apple-darwin)
- Apple arm64 (aarch64-apple-darwin)
Tier 2
- Windows arm64 (aarch64-pc-windows-msvc)
实验性
¥Experimental
- Linux x64 musl (x86_64-unknown-linux-musl)
- FreeBSD x64 (x86_64-unknown-freebsd)
- OpenHarmony arm64 (aarch64-unknown-linux-ohos)
其他
¥Other
- Linux arm64 musl (aarch64-unknown-linux-musl)
- Android arm64 (aarch64-linux-android)
- Wasm + Wasi (wasm32-wasip1-threads)

如果你使用的平台未分发预构建的二进制文件，你有以下选择：

¥If you are using a platform that a prebuilt binary is not distributed, you have the following options:

使用 Wasm 构建
¥Use the Wasm build
1. 下载 Wasm 构建。
  ¥Download the Wasm build.
  - 对于 npm，你可以运行 npm install --cpu wasm32 --os wasip1-threads。
    ¥For npm, you can run npm install --cpu wasm32 --os wasip1-threads.
  - 对于 Yarn 或 pnpm，你需要将以下内容添加到你的 .yarnrc.yaml 或 pnpm-workspace.yaml 中：
    ¥For yarn or pnpm, you need to add the following content to your .yarnrc.yaml or pnpm-workspace.yaml:
    yaml
```
supportedArchitectures:
  os:
    - wasip1-threads
  cpu:
    - wasm32
```
2. 让 Rolldown 加载 Wasm 构建。
  ¥Make Rolldown load the Wasm build.
  - 如果预构建的二进制文件不可用，Rolldown 将自动回退到 Wasm 二进制文件。
    ¥If the prebuilt binary is not available, Rolldown will fallback to the Wasm binary automatically.
  - 如果你需要强制 Rolldown 使用 Wasm 构建，可以设置 NAPI_RS_FORCE_WASI=error 环境变量。
    ¥In case you need to force Rolldown to use the Wasm build, you can set NAPI_RS_FORCE_WASI=error environment variable.
构建自源码
¥Build from source
1. 克隆代码库。
  ¥Clone the repository.
2. 按照设置说明设置项目。
  ¥Setup the project by following the setup instructions.
3. 按照构建说明构建项目。
  ¥Build the project by following the build instructions.
4. 将 NAPI_RS_NATIVE_LIBRARY_PATH 环境变量设置为克隆仓库中 packages/rolldown 的路径。
  ¥Set the NAPI_RS_NATIVE_LIBRARY_PATH environment variable to the path of packages/rolldown in the cloned repository.

发布渠道

¥Release Channels

latest：当前为 1.0.0-beta.*。
¥latest: currently 1.0.0-beta.*.
pkg.pr.new：从 main 分支持续发布。使用 npm i https://pkg.pr.new/rolldown@sha 安装，其中 sha 是 pkg.pr.new 上列出的成功构建。
¥pkg.pr.new: continuously released from the main branch. Install with npm i https://pkg.pr.new/rolldown@sha where sha is a successful build listed on pkg.pr.new.

使用 CLI

¥Using the CLI

要验证 Rolldown 是否正确安装，请在安装目录中运行以下命令：

¥To verify Rolldown is installed correctly, run the following in the directory where you installed it:

$ ./node_modules/.bin/rolldown --version

你还可以使用以下命令查看 CLI 选项和示例：

¥You can also check out the CLI options and examples with:

$ ./node_modules/.bin/rolldown --help

你的第一个打包工具

¥Your first bundle

让我们创建两个 JavaScript 源文件：

¥Let's create two source JavaScript files:

src/main.js

import { hello } from './hello.js';

hello();

src/hello.js

export function hello() {
  console.log('Hello Rolldown!');
}

然后在命令行中运行以下命令：

¥Then run the following in the command line:

$ ./node_modules/.bin/rolldown src/main.js --file bundle.js

你应该看到写入当前目录中 bundle.js 文件的内容。让我们运行它来验证它是否正常工作：

¥You should see the content written to bundle.js in your current directory. Let's run it to verify it's working:

$ node bundle.js

你应该看到打印出的 Hello Rolldown! 文件。

¥You should see Hello Rolldown! printed.

在 npm scripts 中使用 CLI

¥Using the CLI in npm scripts

为了避免输入冗长的命令，我们可以将其移到 npm 脚本中：

¥To avoid typing the long command, we can move it inside an npm script:

package.json

json

{
  "name": "my-rolldown-project",
  "type": "module",
  "scripts": {
    "build": "rolldown src/main.js --file bundle.js"
  },
  "devDependencies": {
    "rolldown": "^1.0.0-beta.1"
  }
}

现在我们只需使用以下命令即可运行构建：

¥Now we can run the build with just:

$ npm run build

使用配置文件

¥Using the Config File

当需要更多选项时，建议使用配置文件以获得更大的灵活性。配置文件可以采用 .js、.cjs、.mjs、.ts、.mts 或 .cts 格式编写。让我们创建以下配置文件：

¥When more options are needed, it is recommended to use a config file for more flexibility. A config file can be written in .js, .cjs, .mjs, .ts, .mts, or .cts formats. Let's create the following config file:

rolldown.config.js

import { defineConfig } from 'rolldown';

export default defineConfig({
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
  },
});

Rolldown 支持大部分 Rollup 配置选项功能，以及部分值得注意的附加功能功能。

¥Rolldown supports most of the Rollup config options, with some notable additional features.

虽然导出普通对象也可以，但建议使用 defineConfig 辅助方法来获取选项智能感知和自动补齐功能。此辅助程序仅用于类型，并按原样返回选项。

¥While exporting a plain object also works, it is recommended to utilize the defineConfig helper method to get options intellisense and auto-completion. This helper is provided purely for the types and returns the options as-is.

接下来，在 npm 脚本中，我们可以指示 Rolldown 使用带有 --config CLI 选项（简称 -c）的配置文件：

¥Next, in the npm script, we can instruct Rolldown to use the config file with the --config CLI option (-c for short):

package.json

json

{
  "name": "my-rolldown-project",
  "type": "module",
  "scripts": {
    "build": "rolldown -c"
  },
  "devDependencies": {
    "rolldown": "^1.0.0-beta.1"
  }
}

同一配置中的多个构建

¥Multiple builds in the same config

你还可以将多个配置指定为数组，Rolldown 将并行打包它们。

¥You can also specify multiple configurations as an array, and Rolldown will bundle them in parallel.

rolldown.config.js

import { defineConfig } from 'rolldown';

export default defineConfig([
  {
    input: 'src/main.js',
    output: {
      format: 'esm',
    },
  },
  {
    input: 'src/worker.js',
    output: {
      format: 'iife',
      dir: 'dist/worker',
    },
  },
]);

使用插件

¥Using Plugins

Rolldown 的插件 API 与 Rollup 的 API 完全相同，因此你在使用 Rolldown 时可以复用大多数现有的 Rollup 插件。也就是说，Rolldown 提供了许多内置功能功能，使得使用插件变得没有必要。

¥Rolldown's plugin API is identical to that of Rollup's, so you can reuse most of the existing Rollup plugins when using Rolldown. That said, Rolldown provides many built-in features that make it unnecessary to use plugins.

使用 API

¥Using the API

Rolldown 提供了与 Rollup 的兼容的 JavaScript API，从而将 input 和 output 选项区分开来：

¥Rolldown provides a JavaScript API that is compatible with Rollup's, which separates input and output options:

import { rolldown } from 'rolldown';

const bundle = await rolldown({
  // input options
  input: 'src/main.js',
});

// generate bundles in memory with different output options
await bundle.generate({
  // output options
  format: 'esm',
});
await bundle.generate({
  // output options
  format: 'cjs',
});

// or directly write to disk
await bundle.write({
  file: 'bundle.js',
});

或者，你也可以使用更简洁的 build API，它接受与配置文件导出完全相同的选项：

¥Alternatively, you can also use the more concise build API, which accepts the exact same options as the config file export:

import { build } from 'rolldown';

// build writes to disk by default
await build({
  input: 'src/main.js',
  output: {
    file: 'bundle.js',
  },
});

使用 Watcher

¥Using the Watcher

rolldown 监视器 API 与 rollup watch 兼容。

¥The rolldown watcher api is compatible with rollup watch.

import { watch } from 'rolldown';

const watcher = watch({
  /* option */
}); // or watch([/* multiply option */] )

watcher.on('event', () => {});

await watcher.close(); // Here is different with rollup, the rolldown returned the promise at here.

入门指南 ​

安装 ​

发布渠道 ​

使用 CLI ​

你的第一个打包工具 ​

在 npm scripts 中使用 CLI ​

使用配置文件 ​

同一配置中的多个构建 ​

使用插件 ​

使用 API ​

使用 Watcher ​