> ## Documentation Index
> Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bundler

> Bun 的快速原生打包器，支持 JavaScript、TypeScript、JSX 等多种语言

export const name_0 = undefined

Bun 的快速原生打包器可以通过 `bun build` CLI 命令或 `Bun.build()` JavaScript API 使用。

### 一览

* JS API: `await Bun.build({ entrypoints, outdir })`
* CLI: `bun build <入口文件> --outdir ./out`
* 监视：`--watch` 实现增量重建
* 目标环境：`--target browser|bun|node`
* 格式：`--format esm|cjs|iife`（cjs/iife 为实验性功能）

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './build',
    });
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./build
    ```
  </Tab>
</Tabs>

它非常快。下面数字基于 esbuild 的 [three.js benchmark](https://github.com/oven-sh/bun/tree/main/bench/bundle) 性能测试。

<Frame>
  <img src="https://mintcdn.com/bun-zhcndoc/7hwCkUCcx3ux5DPj/images/bundler-speed.png?fit=max&auto=format&n=7hwCkUCcx3ux5DPj&q=85&s=2aca5668c344ddc14e96e15798a06a63" caption="从零打包 10 份 three.js 副本，带有 sourcemaps 和代码压缩" width="2690" height="1072" data-path="images/bundler-speed.png" />
</Frame>

## 为什么要打包？

打包器是 JavaScript 生态系统中的关键基础设施。简要介绍打包为何如此重要：

* **减少 HTTP 请求。** `node_modules` 中的单个包可能包含数百个文件，大型应用可能有数十个此类依赖。用单独的 HTTP 请求加载每个文件很快就不可行，因此打包器用来将源代码转换成较少数量的自包含“包”，能用一次请求加载。
* **代码转换。** 现代应用常使用 TypeScript、JSX、CSS Modules 等语言和工具，这些都必须转换成纯 JavaScript 和 CSS，浏览器才能识别。打包器是配置这些转换的自然位置。
* **框架特性。** 框架依赖打包器插件和代码转换来实现常见模式，比如文件系统路由、客户端-服务器代码共置（比如 `getServerSideProps` 或 Remix loaders）以及服务器组件。
* **全栈应用。** Bun 的打包器可以同时处理服务端和客户端代码，只需一个命令，支持优化的生产构建和独立可执行文件。通过构建时的 HTML 导入，你可以将整个应用（前端资源和后端服务器）打包成一个可部署单元。

接下来一起看看打包器的 API。

<Note>Bun 打包器不替代 `tsc` 做类型检查或生成类型声明。</Note>

## 基本示例

让我们构建第一个 bundle。你有以下两个文件，它们实现了一个客户端渲染的 React 应用。

<CodeGroup>
  ```tsx index.tsx icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  import * as ReactDOM from "react-dom/client";
  import { Component } from "./Component";

  const root = ReactDOM.createRoot(document.getElementById("root")!);
  root.render(<Component message="Sup!" />);
  ```

  ```tsx Component.tsx icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  export function Component(props: { message: string }) {
    return <h1>{props.message}</h1>;
  }
  ```
</CodeGroup>

在这里，`index.tsx` 是应用的“入口点”。通常它是执行某些副作用的脚本，比如启动服务器，或者像这里这样，初始化 React 根节点。由于使用了 TypeScript 和 JSX，代码需要先打包才能发送给浏览器。

构建 bundle：

<CodeGroup>
  ```ts build.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  await Bun.build({
    entrypoints: ["./index.tsx"],
    outdir: "./out",
  });
  ```

  ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
  bun build ./index.tsx --outdir ./out
  ```
</CodeGroup>

对于 `entrypoints` 数组中指定的每个文件，Bun 都会生成一个新的 bundle。bundle 会写入磁盘的 `./out` 目录（相对于当前工作目录解析）。构建后文件系统如下：

```text title="file system" icon="folder-tree" theme={"theme":{"light":"github-light","dark":"dracula"}}
.
├── index.tsx
├── Component.tsx
└── out
    └── index.js
```

`out/index.js` 内容大致如下：

```js title="out/index.js" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
// out/index.js
// ...
// 约 2 万行代码
// 包含 `react-dom/client` 及所有依赖的内容
// 这里定义了 $jsxDEV 和 $createRoot 函数

// Component.tsx
function Component(props) {
  return $jsxDEV(
    "p",
    {
      children: props.message,
    },
    undefined,
    false,
    undefined,
    this,
  );
}

// index.tsx
var rootNode = document.getElementById("root");
var root = $createRoot(rootNode);
root.render(
  $jsxDEV(
    Component,
    {
      message: "Sup!",
    },
    undefined,
    false,
    undefined,
    this,
  ),
);
```

## 监听模式

和运行时与测试器一样，打包器原生支持监听模式。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build ./index.tsx --outdir ./out --watch
```

## 支持的内容类型

和 Bun 运行时一致，打包器开箱支持多种文件类型。下表介绍了默认的“加载器”。完整文档请参考[打包器 > 文件类型](/bundler/loaders)。

| 扩展名                                                   | 说明                                                                                                                                      |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `.js` `.jsx` `.cjs` `.mjs` `.mts` `.cts` `.ts` `.tsx` | 使用 Bun 内置转译器解析并转译 TypeScript/JSX 语法为普通 JavaScript。执行默认转换，包括无用代码消除和摇树优化。当前 Bun 不对语法做向下转换，使用较新 ECMAScript 语法会反映在打包后的代码中。                  |
| `.json`                                               | 解析 JSON 文件，将其内联到 bundle 中，作为 JavaScript 对象。<br /><br />`js<br/>import pkg from "./package.json";<br/>pkg.name; // => "my-package"<br/>` |
| `.jsonc`                                              | 支持带注释的 JSON。解析后内联成 JavaScript 对象。<br /><br />`js<br/>import config from "./config.jsonc";<br/>config.name; // => "my-config"<br/>`      |
| `.toml`                                               | 解析 TOML 文件，内联成 JavaScript 对象。<br /><br />`js<br/>import config from "./bunfig.toml";<br/>config.logLevel; // => "debug"<br/>`           |
| `.yaml` `.yml`                                        | 解析 YAML 文件，内联成 JavaScript 对象。<br /><br />`js<br/>import config from "./config.yaml";<br/>config.name; // => "my-app"<br/>`              |
| `.txt`                                                | 读取文本文件内容，内联成字符串。<br /><br />`js<br/>import contents from "./file.txt";<br/>console.log(contents); // => "Hello, world!"<br/>`           |
| `.html`                                               | 处理 HTML 文件，打包引用的资源（脚本、样式表、图片等）。                                                                                                         |
| `.css`                                                | 将所有 CSS 文件打包成一个 `.css` 文件输出至目标目录。                                                                                                       |
| `.node` `.wasm`                                       | Bun 运行时支持这些文件，但打包时会作为资源处理。                                                                                                              |

### 资源文件

遇到无法识别的文件后缀时，打包器会将该文件视为外部资源。会将引用文件原封不动复制到 `outdir` 目录，同时导入被替换为文件路径。

<CodeGroup>
  ```ts Input icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  // bundle入口文件
  import logo from "./logo.svg";
  console.log(logo);
  ```

  ```ts Output icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
  // 打包输出
  var logo = "./logo-a7305bdef.svg";
  console.log(logo);
  ```
</CodeGroup>

文件加载器的具体行为也受 [`naming`](#naming) 和 [`publicPath`](#publicpath) 影响。

<Info>详情请参考[打包器 > 加载器](/bundler/loaders)页面。</Info>

### 插件

上表中的行为可以通过插件覆盖或扩展。请查阅[打包器 > 加载器](/bundler/loaders)页面完整说明。

## API

### entrypoints

<Badge>必填</Badge>

应用入口点文件路径数组。为每个入口生成一个 bundle。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    const result = await Bun.build({
      entrypoints: ["./index.ts"],
    });
    // => { success: boolean, outputs: BuildArtifact[], logs: BuildMessage[] }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.ts
    ```
  </Tab>
</Tabs>

### files

文件路径到内容的映射，用于内存中打包。允许对不存在磁盘上的虚拟文件进行打包，或覆盖已有文件内容。此选项仅在 JavaScript API 中可用。

文件内容可以是 `string`、`Blob`、`TypedArray` 或 `ArrayBuffer`。

#### 完全内存打包

可通过 `files` 在内存中打包所有代码，无需磁盘文件：

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
const result = await Bun.build({
  entrypoints: ["/app/index.ts"],
  files: {
    "/app/index.ts": `
      import { greet } from "./greet.ts";
      console.log(greet("World"));
    `,
    "/app/greet.ts": `
      export function greet(name: string) {
        return "Hello, " + name + "!";
      }
    `,
  },
});

const output = await result.outputs[0].text();
console.log(output);
```

当所有入口都在 `files` 中时，当前工作目录被用作根目录。

#### 覆盖磁盘文件

内存中指定的文件优先级高于磁盘。可覆盖特定文件，保持其他代码不变：

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
// 假设 ./src/config.ts 磁盘文件存在，含开发配置
await Bun.build({
  entrypoints: ["./src/index.ts"],
  files: {
    // 用生产配置覆盖 config.ts
    "./src/config.ts": `
      export const API_URL = "https://api.production.com";
      export const DEBUG = false;
    `,
  },
  outdir: "./dist",
});
```

#### 混合磁盘与虚拟文件

磁盘文件可导入虚拟文件，虚拟文件也可导入磁盘文件：

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
// ./src/index.ts 磁盘存在，导入 "./generated.ts"
await Bun.build({
  entrypoints: ["./src/index.ts"],
  files: {
    // 提供 index.ts 导入的虚拟文件
    "./src/generated.ts": `
      export const BUILD_ID = "${crypto.randomUUID()}";
      export const BUILD_TIME = ${Date.now()};
    `,
  },
  outdir: "./dist",
});
```

常用于代码生成、注入构建时常量或测试模拟模块。

### outdir

输出文件目录。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    const result = await Bun.build({
      entrypoints: ['./index.ts'],
      outdir: './out'
    });
    // => { success: boolean, outputs: BuildArtifact[], logs: BuildMessage[] }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.ts --outdir ./out
    ```
  </Tab>
</Tabs>

未传 `outdir` 时，打包后的代码不会写入磁盘。文件内容以 `BuildArtifact` 对象数组形式返回。`BuildArtifact` 是带附加属性的 Blob；详见[输出](#outputs)。

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
const result = await Bun.build({
  entrypoints: ["./index.ts"],
});

for (const res of result.outputs) {
  // 可作为 Blob 处理
  await res.text();

  // Bun 会自动设置 Content-Type 和 Etag 头
  new Response(res);

  // 也可手动写入，但此时推荐使用 `outdir` 选项。
  Bun.write(path.join("out", res.path), res);
}
```

设置了 `outdir` 时，`BuildArtifact` 的 `path` 是文件写入的绝对路径。

### target

指定目标执行环境。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.ts'],
      outdir: './out',
      target: 'browser', // 默认
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.ts --outdir ./out --target browser
    ```
  </Tab>
</Tabs>

不同目标环境，Bun 会应用不同的模块解析规则和优化。

<Card title="browser" icon="globe">
  **默认。** 生成面向浏览器的 bundle。解析导入时优先使用 `"browser"` export 条件。导入内建模块（如 `node:events` 或
  `node:path`）可行，但调用部分函数（如 `fs.readFile`）无效。
</Card>

<Card title="bun" icon="server">
  生成面向 Bun 运行时的 bundle。通常不强制要求将服务端代码打包，可直接执行源代码。但打包服务端代码有助于减少启动时间并提升运行性能。使用构建时 HTML 导入创建全栈应用时，应使用此目标，将客户端和服务端代码共享打包。

  所有带 `target: "bun"` 的 bundle 都会带有特殊的 `// @bun` 编译指令，告知 Bun 运行时无需重转译即可执行。

  若入口文件含 Bun shebang（`#!/usr/bin/env bun`），打包器默认改用 `target: "bun"`。

  结合使用 `target: "bun"` 和 `format: "cjs"` 时，会添加 `// @bun @bun-cjs` 编译指令，且 CommonJS 包装函数不兼容 Node.js。
</Card>

<Card title="node" icon="node">
  生成面向 Node.js 的 bundle。解析导入时优先使用 `"node"` export 条件，输出 `.mjs` 文件。未来将自动为 Bun 全局对象以及
  `bun:*` 内建模块提供 polyfill（尚未实现）。
</Card>

### format

指定生成 bundle 的模块格式。

Bun 默认为 `"esm"`，并提供 `"cjs"` 和 `"iife"` 实验性支持。

#### 格式: "esm" - ES 模块

默认格式，支持 ES 模块语法，包括顶层 await、`import.meta` 等。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      format: "esm",
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --format esm
    ```
  </Tab>
</Tabs>

浏览器中使用 ES 模块时，需确保 `<script>` 标签带有 `type="module"`，并设置 `format` 为 `"esm"`。

#### 格式: "cjs" - CommonJS

设置为 `"cjs"` 以构建 CommonJS 模块。此时默认 `target` 会从 `"browser"` (esm) 自动切换为 `"node"` (cjs)。使用 `format: "cjs"`，`target: "node"` 转译的 CommonJS 模块，在 Bun 和 Node.js 都可执行（前提是 API 受支持）。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      format: "cjs",
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --format cjs
    ```
  </Tab>
</Tabs>

#### 格式: "iife" - IIFE

待完善文档，支持 globalNames 后发布。

### `jsx`

配置 JSX 转换行为，精细控制 JSX 编译方式。

**Classic 运行时示例**（使用 `factory` 和 `fragment`）：

<CodeGroup>
  ```ts index.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  await Bun.build({
    entrypoints: ["./app.tsx"],
    outdir: "./out",
    jsx: {
      factory: "h",
      fragment: "Fragment",
      runtime: "classic",
    },
  });
  ```

  ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
  # JSX 配置可通过 bunfig.toml 或 tsconfig.json 管理
  bun build ./app.tsx --outdir ./out
  ```
</CodeGroup>

**自动运行时示例**（使用 `importSource`）：

<CodeGroup>
  ```ts index.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  await Bun.build({
    entrypoints: ["./app.tsx"],
    outdir: "./out",
    jsx: {
      importSource: "preact",
      runtime: "automatic",
    },
  });
  ```

  ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
  # JSX 配置可通过 bunfig.toml 或 tsconfig.json 管理
  bun build ./app.tsx --outdir ./out
  ```
</CodeGroup>

### splitting

是否启用代码拆分。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      splitting: false, // 默认关闭
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --splitting
    ```
  </Tab>
</Tabs>

启用后，多个入口若共享同一文件、模块或模块集合，打包器会将共享代码拆分为独立 bundle，称为 chunk。示例文件如：

<CodeGroup>
  ```ts entry-a.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  import { shared } from "./shared.ts";
  ```

  ```ts entry-b.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  import { shared } from "./shared.ts";
  ```

  ```ts shared.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  export const shared = "shared";
  ```
</CodeGroup>

启用拆分打包：

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./entry-a.ts', './entry-b.ts'],
      outdir: './out',
      splitting: true,
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./entry-a.ts ./entry-b.ts --outdir ./out --splitting
    ```
  </Tab>
</Tabs>

打包结果文件结构：

```text title="file system" icon="folder-tree" theme={"theme":{"light":"github-light","dark":"dracula"}}
.
├── entry-a.tsx
├── entry-b.tsx
├── shared.tsx
└── out
    ├── entry-a.js
    ├── entry-b.js
    └── chunk-2fce6291bf86559d.js
```

`chunk-2fce6291bf86559d.js` 为共享代码 chunk，默认文件名包含 hash 防止冲突，可通过 [`naming`](#naming) 自定义。

### plugins

打包时应用的插件列表。

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
  plugins: [
    /* ... */
  ],
});
```

Bun 实现了统一的插件系统，适用于运行时和打包器。详见[插件文档](/bundler/plugins)。

### env

控制打包时环境变量的处理方式。内部使用 `define` 注入环境变量，简化指定注入内容。

#### env: "inline"

将 `process.env.FOO` 替换为包含环境变量实际值的字符串字面量，内联进 bundle。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      env: "inline",
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --env inline
    ```
  </Tab>
</Tabs>

示例输入：

```js title="input.js" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
// input.js
console.log(process.env.FOO);
console.log(process.env.BAZ);
```

输出变为：

```js title="output.js" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
// output.js
console.log("bar");
console.log("123");
```

#### env: "PUBLIC\_\*"（前缀）

内联所有匹配给定前缀的环境变量（即 `*` 之前的部分），替换对应的 `process.env`。适合选择性注入公共 URL 或客户端 token，避免私密信息泄漏。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',

      // 内联所有以 "ACME_PUBLIC_" 开头的环境变量
      env: "ACME_PUBLIC_*",
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --env ACME_PUBLIC_*
    ```
  </Tab>
</Tabs>

设环境变量如下：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
FOO=bar BAZ=123 ACME_PUBLIC_URL=https://acme.com
```

源码：

```tsx index.tsx icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
console.log(process.env.FOO);
console.log(process.env.ACME_PUBLIC_URL);
console.log(process.env.BAZ);
```

输出：

```js title="output.js" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
console.log(process.env.FOO);
console.log("https://acme.com");
console.log(process.env.BAZ);
```

#### env: "disable"

完全禁用环境变量注入。

### sourcemap

指定生成哪种类型的 sourcemap。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      sourcemap: 'linked', // 默认 'none'
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --sourcemap linked
    ```
  </Tab>
</Tabs>

| 值            | 说明                                                                                                                                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"none"`     | 默认。不生成 sourcemap。                                                                                                                                                                                                         |
| `"linked"`   | 生成独立的 `*.js.map` 文件，与每个 `*.js` bundle 同目录。bundle 中插入 `//# sourceMappingURL` 注释关联两者。需确保设置了 `--outdir`。可通过 `--public-path` 自定义基础路径。<br /><br />示例：<br />`js<br/>// <打包代码><br/><br/>//# sourceMappingURL=bundle.js.map<br/>` |
| `"external"` | 生成独立的 `*.js.map` 文件，不插入 `//# sourceMappingURL` 注释。bundle 包含调试 id（debugId），可用于关联 map 文件，该 id 作为注释添加至 bundle 底部。<br /><br />示例：<br />`js<br/>// <打包代码><br/><br/>//# debugId=<DEBUG ID><br/>`                                |
| `"inline"`   | 生成 sourcemap 并以 base64 编码数据嵌入到 bundle 末尾。<br /><br />示例：<br />`js<br/>// <打包代码><br/><br/>//# sourceMappingURL=data:application/json;base64,<编码数据><br/>`                                                                   |

对应的 `*.js.map` 文件是 JSON 格式，包含同样的 `debugId` 字段。

### minify

是否启用代码压缩，默认 `false`。

<Note>若目标为 `bun`，默认会压缩标识符。</Note>

启用所有压缩选项：

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      minify: true, // 默认 false
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --minify
    ```
  </Tab>
</Tabs>

细粒度开启压缩：

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      minify: {
        whitespace: true,
        identifiers: true,
        syntax: true,
      },
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --minify-whitespace --minify-identifiers --minify-syntax
    ```
  </Tab>
</Tabs>

### external

外部依赖列表，默认空数组 `[]`。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      external: ["lodash", "react"], // 默认 []
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --external lodash --external react
    ```
  </Tab>
</Tabs>

外部导入不会打包进最终文件，导入语句保留，运行时解析。

示例入口：

```tsx index.tsx icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
import _ from "lodash";
import { z } from "zod";

const value = z.string().parse("Hello world!");
console.log(_.upperCase(value));
```

默认打包会将整个 "zod" 包源码包含进 bundle。如果想保留导入不打包，可标记为外部：

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      external: ['zod'],
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --external zod
    ```
  </Tab>
</Tabs>

生成的 bundle 可能如下：

```js title="out/index.js" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
import { z } from "zod";

// ...
// lodash 源码
// 包括 `_.upperCase` 函数

var value = z.string().parse("Hello world!");
console.log(_.upperCase(value));
```

可使用通配符 `*` 标记所有导入为外部：

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      external: ['*'],
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --external '*'
    ```
  </Tab>
</Tabs>

### packages

控制是否将包依赖（非相对或绝对路径）打包。可选值：`bundle`（默认）或 `external`。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.ts'],
      packages: 'external',
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.ts --packages external
    ```
  </Tab>
</Tabs>

### naming

自定义生成文件名。默认 `'./[dir]/[name].[ext]'`。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      naming: "[dir]/[name].[ext]", // 默认
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --entry-naming "[dir]/[name].[ext]"
    ```
  </Tab>
</Tabs>

默认情况下，生成文件名基于入口文件名。

```text title="file system" icon="folder-tree" theme={"theme":{"light":"github-light","dark":"dracula"}}
.
├── index.tsx
└── out
    └── index.js
```

多入口项目，生成文件层级反映入口目录结构：

```text title="file system" icon="folder-tree" theme={"theme":{"light":"github-light","dark":"dracula"}}
.
├── index.tsx
└── nested
    └── index.tsx
└── out
    ├── index.js
    └── nested
        └── index.js
```

用 `naming` 自定义名称，支持以下变量：

* `[name]` - 入口文件名（无扩展名）
* `[ext]` - 生成文件扩展名
* `[hash]` - 文件内容哈希值
* `[dir]` - 项目根目录相对路径到源文件父目录

举例：

| 示例文件                | `[name]` | `[ext]` | `[hash]`   | `[dir]`    |
| ------------------- | -------- | ------- | ---------- | ---------- |
| `./index.tsx`       | `index`  | `js`    | `a1b2c3d4` | `""`（空字符串） |
| `./nested/entry.ts` | `entry`  | `js`    | `c3d4e5f6` | `"nested"` |

示例设置让文件名包含 hash：

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      naming: 'files/[dir]/[name]-[hash].[ext]',
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --entry-naming 'files/[dir]/[name]-[hash].[ext]'
    ```
  </Tab>
</Tabs>

示例输出结构：

```text title="file system" icon="folder-tree" theme={"theme":{"light":"github-light","dark":"dracula"}}
.
├── index.tsx
└── out
    └── files
        └── index-a1b2c3d4.js
```

若只传字符串到 `naming`，仅作用于入口对应的 bundle，chunk 和资源文件名不受影响。JS API 允许分别为入口、chunk 和资源指定模板字符串。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      naming: {
        // 默认值
        entry: '[dir]/[name].[ext]',
        chunk: '[name]-[hash].[ext]',
        asset: '[name]-[hash].[ext]',
      },
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out \
      --entry-naming '[dir]/[name].[ext]' \
      --chunk-naming '[name]-[hash].[ext]' \
      --asset-naming '[name]-[hash].[ext]'
    ```
  </Tab>
</Tabs>

### root

项目根目录。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./pages/a.tsx', './pages/b.tsx'],
      outdir: './out',
      root: '.',
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./pages/a.tsx ./pages/b.tsx --outdir ./out --root .
    ```
  </Tab>
</Tabs>

默认为所有入口文件的第一个公共祖先目录。示例文件结构：

```text title="file system" icon="folder-tree" theme={"theme":{"light":"github-light","dark":"dracula"}}
.
└── pages
  └── index.tsx
  └── settings.tsx
```

构建两个入口：

<Tabs>
  <Tab title="JavaScript">
    ```js theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./pages/index.tsx', './pages/settings.tsx'],
      outdir: './out',
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./pages/index.tsx ./pages/settings.tsx --outdir ./out
    ```
  </Tab>
</Tabs>

结果：

```text title="file system" icon="folder-tree" theme={"theme":{"light":"github-light","dark":"dracula"}}
.
└── pages
  └── index.tsx
  └── settings.tsx
└── out
  └── index.js
  └── settings.js
```

由于 `pages` 是入口文件第一个公共祖先，视为项目根，生成 bundle 放在 `out` 顶层，而非 `out/pages`。

可通过 `root` 参数覆写：

<Tabs>
  <Tab title="JavaScript">
    ```js theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./pages/index.tsx', './pages/settings.tsx'],
      outdir: './out',
      root: '.',
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./pages/index.tsx ./pages/settings.tsx --outdir ./out --root .
    ```
  </Tab>
</Tabs>

此时文件结构变为：

```
.
└── pages
  └── index.tsx
  └── settings.tsx
└── out
  └── pages
    └── index.js
    └── settings.js
```

### publicPath

打包后代码中所有导入路径的前缀。

通常打包会合并代码，不留导入语句，但以下情况例外：

* **资源导入** — 导入类似 `*.svg` 这类非代码资源时，文件复制到 `outdir`，导入变变量引用
* **外部模块** — 标记为外部的模块，导入语句保留
* **代码拆分 chunk** — 当启用拆分时，共享代码会抽成多个文件，导入路径不能相对。

在任何这些情况下，最终 bundle 可能包含对其他文件的路径。默认这些导入是相对的。下面是一个资源导入的示例：

<CodeGroup>
  ```ts Input icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  import logo from "./logo.svg";
  console.log(logo);
  ```

  ```ts Output icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
  var logo = "./logo-a7305bdef.svg";
  console.log(logo);
  ```
</CodeGroup>

设置 `publicPath` 后，所有路径被加前缀：

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      publicPath: 'https://cdn.example.com/', // 默认为 undefined
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --public-path 'https://cdn.example.com/'
    ```
  </Tab>
</Tabs>

生成文件示例：

```js title="out/index.js" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
var logo = "https://cdn.example.com/logo-a7305bdef.svg";
```

### define

构建时全局标识符替换映射。键为标识符名，值是 JSON 字符串字面量，内联替代。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      define: {
        STRING: JSON.stringify("value"),
        "nested.boolean": "true",
      },
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --define STRING='"value"' --define nested.boolean=true
    ```
  </Tab>
</Tabs>

### loader

将文件扩展名映射到内置 loader 名称的表。使用它自定义某些文件的加载方式。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      loader: {
        ".png": "dataurl",
        ".txt": "file",
      },
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --loader .png:dataurl --loader .txt:file
    ```
  </Tab>
</Tabs>

### banner

在最终 bundle 顶部添加 banner，比如 React 的 `"use client"` 指令或版权声明注释。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      banner: '"use client";'
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --banner '"use client";'
    ```
  </Tab>
</Tabs>

### footer

要添加到最终 bundle 末尾的 footer。这可以是许可证注释块或有趣的彩蛋。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      footer: '// built with love in SF'
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --footer '// built with love in SF'
    ```
  </Tab>
</Tabs>

### drop

从 bundle 中移除函数调用。例如，`--drop=console` 会移除所有 `console.log` 调用，参数也会被移除（无论参数是否有副作用）。移除 `debugger` 时，会删除所有 `debugger` 语句。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./index.tsx'],
      outdir: './out',
      drop: ["console", "debugger", "anyIdentifier.or.propertyAccess"],
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./index.tsx --outdir ./out --drop console --drop debugger
    ```
  </Tab>
</Tabs>

### features

编译时启用特性标记以实现死代码删除。通过 `import { feature } from "bun:bundle"` 条件包含代码。

```ts title="app.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
import { feature } from "bun:bundle";

if (feature("PREMIUM")) {
  // 仅 PREMIUM 标记启用时包含
  initPremiumFeatures();
}

if (feature("DEBUG")) {
  // 仅 DEBUG 标记启用时包含
  console.log("Debug mode");
}
```

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    await Bun.build({
      entrypoints: ['./app.ts'],
      outdir: './out',
      features: ["PREMIUM"],  // PREMIUM=true, DEBUG=false
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./app.ts --outdir ./out --feature PREMIUM
    ```
  </Tab>
</Tabs>

`feature()` 在打包时替换为布尔值，结合压缩，可剔除不可达分支：

```ts title="输入" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
import { feature } from "bun:bundle";
const mode = feature("PREMIUM") ? "premium" : "free";
```

```js title="输出（启用 --feature PREMIUM --minify）" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
var mode = "premium";
```

```js title="输出（不启用 --feature PREMIUM，启用 --minify）" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/javascript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=14ec2cbdf78f597f421d87adcffda9ac" theme={"theme":{"light":"github-light","dark":"dracula"}}
var mode = "free";
```

**主要注意事项：**

* `feature()` 只能接受字符串字面量参数，不支持动态值
* `bun:bundle` 导入会被移除，不会出现在输出代码
* 支持 `bun build`、`bun run` 及 `bun test`
* 可启用多条特性：`--feature FLAG_A --feature FLAG_B`
* 为类型安全，可扩展 `Registry` 接口限制只能使用指定特性（见下）

**应用场景：**

* 平台差异代码（`feature("SERVER")` vs `feature("CLIENT")`）
* 环境变量控制功能（`feature("DEVELOPMENT")`）
* 渐进式功能发布
* A/B 测试
* 付费版功能区分

**类型安全：** 默认 `feature()` 可传任意字符串。想实现自动提示防错，可新建 `env.d.ts` 文件（或补充到已有 `.d.ts`）并声明扩展：

```ts title="env.d.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
declare module "bun:bundle" {
  interface Registry {
    features: "DEBUG" | "PREMIUM" | "BETA_FEATURES";
  }
}
```

确保文件包含在 `tsconfig.json`（如 `"include": ["src", "env.d.ts"]`）内。此后 `feature()` 仅接受这些字符串，使用其他字符串则会提示类型错误。

### optimizeImports

跳过解析未使用的 barrel 文件子模块（重新导出的索引文件）。当你只从一个大型库中导入少量具名导出时，通常打包工具会解析 barrel 文件重新导出的每个文件。使用 `optimizeImports` 后，只有你实际使用的子模块才会被解析。

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
await Bun.build({
  entrypoints: ["./app.ts"],
  outdir: "./out",
  optimizeImports: ["antd", "@mui/material", "lodash-es"],
});
```

例如，`import { Button } from 'antd'` 通常会解析 `antd/index.js` 重新导出的所有约 3000 个模块。使用 `optimizeImports: ['antd']` 时，只会解析 `Button` 子模块。

这适用于**纯桶文件**——即每个具名导出都是重新导出的文件（`export { X } from './x'`）。如果桶文件有任何本地导出（`export const foo = ...`），或者有任何导入者使用了 `import *`，则所有子模块都会被加载。

`export *` 重新导出的模块始终会被加载（不会延迟），以避免循环解析问题。只有未被任何导入者使用的具名重新导出（`export { X } from './x'`）才会被延迟加载。

**自动模式：** 在 `package.json` 中带有 `"sideEffects": false` 的包会自动启用桶优化——无需配置 `optimizeImports`。对于没有该字段的包，可以使用 `optimizeImports`。

**插件：** 解析和加载插件在桶优化下可以正常工作。延迟加载的子模块在最终被加载时会经过插件流程。

### metafile

生成构建的结构化元数据。metafile 包含所有输入文件、输出文件、大小、导入和导出信息。用途包括：

* **包分析**：了解包大小组成
* **可视化**：传入如 [esbuild 的 bundle analyzer](https://esbuild.github.io/analyze/) 或其他工具
* **依赖追踪**：查看完整导入图
* **CI 集成**：追踪包大小变化

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    const result = await Bun.build({
      entrypoints: ['./src/index.ts'],
      outdir: './dist',
      metafile: true,
    });

    if (result.metafile) {
      // 分析输入文件
      for (const [path, meta] of Object.entries(result.metafile.inputs)) {
        console.log(`${path}: ${meta.bytes} 字节`);
      }

      // 分析输出文件
      for (const [path, meta] of Object.entries(result.metafile.outputs)) {
        console.log(`${path}: ${meta.bytes} 字节`);
      }

      // 保存供外部分析工具使用
      await Bun.write('./dist/meta.json', JSON.stringify(result.metafile));
    }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    bun build ./src/index.ts --outdir ./dist --metafile ./dist/meta.json
    ```
  </Tab>
</Tabs>

#### Markdown metafile

使用 `--metafile-md` 生成一个 markdown metafile，它对 LLM 友好，并且在终端中可读：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build ./src/index.ts --outdir ./dist --metafile-md ./dist/meta.md
```

`--metafile` 和 `--metafile-md` 可同时使用：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build ./src/index.ts --outdir ./dist --metafile ./dist/meta.json --metafile-md ./dist/meta.md
```

#### `metafile` 选项格式

在 JavaScript API 中，`metafile` 支持以下几种形式：

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
// 布尔值 - 在结果对象中包含 metafile 字段
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  metafile: true,
});

// 字符串 - 将 JSON metafile 写入指定路径
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  metafile: "./dist/meta.json",
});

// 对象 - 指定 JSON 和 Markdown 输出路径
await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  metafile: {
    json: "./dist/meta.json",
    markdown: "./dist/meta.md",
  },
});
```

metafile 结构包含：

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
interface BuildMetafile {
  inputs: {
    [path: string]: {
      bytes: number;
      imports: Array<{
        path: string;
        kind: ImportKind;
        original?: string; // 解析前的原始导入标识符
        external?: boolean;
      }>;
      format?: "esm" | "cjs" | "json" | "css";
    };
  };
  outputs: {
    [path: string]: {
      bytes: number;
      inputs: {
        [path: string]: { bytesInOutput: number };
      };
      imports: Array<{ path: string; kind: ImportKind }>;
      exports: string[];
      entryPoint?: string;
      cssBundle?: string; // JS 入口点对应的 CSS 文件
    };
  };
}
```

## 输出

`Bun.build` 返回一个 `Promise<BuildOutput>`，定义如下：

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
interface BuildOutput {
  outputs: BuildArtifact[];
  success: boolean;
  logs: Array<object>; // 详见文档
  metafile?: BuildMetafile; // 仅当 metafile: true 时存在
}

interface BuildArtifact extends Blob {
  kind: "entry-point" | "chunk" | "asset" | "sourcemap";
  path: string;
  loader: Loader;
  hash: string | null;
  sourcemap: BuildArtifact | null;
}
```

`outputs` 数组包含构建生成的所有文件，每个 Artifact 实现了 Blob 接口。

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
const build = await Bun.build({
  /* */
});

for (const output of build.outputs) {
  await output.arrayBuffer(); // => ArrayBuffer
  await output.bytes(); // => Uint8Array
  await output.text(); // string
}
```

每个 Artifact 还拥有：

| 属性          | 说明                                          |
| ----------- | ------------------------------------------- |
| `kind`      | 文件类型：入口点、代码拆分块、资源、sourcemap、字节码等            |
| `path`      | 磁盘上的绝对路径                                    |
| `loader`    | 用于加载该文件的加载器，详见[打包器 > 加载器](/bundler/loaders) |
| `hash`      | 文件内容哈希。资源文件必定含有                             |
| `sourcemap` | 该文件对应的 sourcemap 文件，若生成则存在。仅入口点和 chunk 有值。  |

`BuildArtifact` 对象可以直接传给 `new Response()`。

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
const build = await Bun.build({
  /* */
});

const artifact = build.outputs[0];

// 会自动设置 Content-Type 头
return new Response(artifact);
```

Bun 运行时支持对 `BuildArtifact` 对象的漂亮打印，便于调试：

<CodeGroup>
  ```ts build.ts icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
  // build.ts
  const build = await Bun.build({
    /* */
  });

  const artifact = build.outputs[0];
  console.log(artifact);
  ```

  ```bash Shell output theme={"theme":{"light":"github-light","dark":"dracula"}}
  bun run build.ts

  BuildArtifact (entry-point) {
    path: "./index.js",
    loader: "tsx",
    kind: "entry-point",
    hash: "824a039620219640",
    Blob (74756 bytes) {
      type: "text/javascript;charset=utf-8"
    },
    sourcemap: BuildArtifact (sourcemap) {
      path: "./index.js.map",
      loader: "file",
      kind: "sourcemap",
      hash: "e7178cda3e72e301",
      Blob (24765 bytes) {
        type: "application/json;charset=utf-8"
      },
      sourcemap: null
    }
  }
  ```
</CodeGroup>

## 字节码

`bytecode: boolean` 选项用于生成入口的字节码，显著提高大型应用启动速度。仅支持 `"cjs"` 格式，只能与 `target: "bun"` 配合使用，且依赖 Bun 版本匹配。每个入口会生成对应 `.jsc` 文件。

<Tabs>
  <Tab title="JavaScript">
    ```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
    // CommonJS 字节码（生成 .jsc 文件）
    await Bun.build({
      entrypoints: ["./index.tsx"],
      outdir: "./out",
      bytecode: true,
    })

    // ESM 字节码（需要 compile）
    await Bun.build({
      entrypoints: ["./index.tsx"],
      outfile: "./mycli",
      bytecode: true,
      format: "esm",
      compile: true,
    })
    ```
  </Tab>

  <Tab title="CLI">
    ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
    # CommonJS 字节码
    bun build ./index.tsx --outdir ./out --bytecode

    # ESM 字节码（需要 --compile）
    bun build ./index.tsx --outfile ./mycli --bytecode --format=esm --compile
    ```
  </Tab>
</Tabs>

## 可执行文件

Bun 支持将 JavaScript/TypeScript 入口“编译”为独立可执行文件，其中包含 Bun 二进制。

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build ./cli.tsx --outfile mycli --compile
./mycli
```

详见[打包器 > 可执行文件](/bundler/executables)。

## 日志和错误

构建失败时，`Bun.build` 返回一个拒绝的 `AggregateError`，可打印查看列表错误，或用 try/catch 捕获处理。

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
try {
  const result = await Bun.build({
    entrypoints: ["./index.tsx"],
    outdir: "./out",
  });
} catch (e) {
  // TS 不允许在 catch 加类型注解，故用断言
  const error = e as AggregateError;
  console.error("构建失败");

  // 示例：内置格式化打印
  console.error(error);

  // 示例：序列化成 JSON 字符串打印
  console.error(JSON.stringify(error, null, 2));
}
```

大多数情况下，不需要显式的 try/catch，因为 Bun 会整洁地打印未捕获的异常。你可以直接对 `Bun.build` 调用使用顶层 await。

错误列表中每条均为 `BuildMessage` 或 `ResolveMessage` 实例（继承自 `Error`），含详细信息：

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
class BuildMessage {
  name: string;
  position?: Position;
  message: string;
  level: "error" | "warning" | "info" | "debug" | "verbose";
}

class ResolveMessage extends BuildMessage {
  code: string;
  referrer: string;
  specifier: string;
  importKind: ImportKind;
}
```

构建成功时，返回对象有 `logs` 字段，包含打包警告和信息。

```ts title="build.ts" icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" theme={"theme":{"light":"github-light","dark":"dracula"}}
const result = await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
});

if (result.logs.length > 0) {
  console.warn("构建成功但有警告：");
  for (const message of result.logs) {
    // Bun 将美化打印信息
    console.warn(message);
  }
}
```

## 参考

```ts Typescript Definitions icon="https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217" expandable theme={"theme":{"light":"github-light","dark":"dracula"}}
interface Bun {
  build(options: BuildOptions): Promise<BuildOutput>;
}

interface BuildConfig {
  entrypoints: string[]; // 入口文件数组
  outdir?: string; // 输出目录
  target?: Target; // 默认 "browser"
  /**
   * 输出模块格式，顶层 await 仅支持 "esm"
   *
   * 可选:
   * - "esm"
   * - "cjs" (**实验性**)
   * - "iife" (**实验性**)
   *
   * @default "esm"
   */
  format?: "esm" | "cjs" | "iife";
  /**
   * JSX 配置对象，控制 JSX 转换行为
   */
  jsx?: {
    runtime?: "automatic" | "classic";
    importSource?: string;
    factory?: string;
    fragment?: string;
    sideEffects?: boolean;
    development?: boolean;
  };
  naming?:
    | string
    | {
        chunk?: string;
        entry?: string;
        asset?: string;
      };
  root?: string; // 项目根目录
  splitting?: boolean; // 默认 true，启用代码拆分
  plugins?: BunPlugin[];
  external?: string[];
  packages?: "bundle" | "external";
  publicPath?: string;
  define?: Record<string, string>;
  loader?: { [k in string]: Loader };
  sourcemap?: "none" | "linked" | "inline" | "external" | boolean; // 默认 "none"，true 相当于 "inline"
  /**
   * package.json 的 `exports` 条件，用于解析导入
   *
   * 等同于 CLI 中 `--conditions` 参数
   *
   * https://nodejs.org/api/packages.html#exports
   */
  conditions?: Array<string> | string;

  /**
   * 打包时环境变量处理方式
   *
   * 可选:
   * - "inline": 将 `process.env.FOO` 替换为实际值字符串字面量
   * - "disable": 禁用环境变量注入
   * - 以 "*" 结尾的字符串: 内联匹配前缀的环境变量，如 "MY_PUBLIC_*"
   */
  env?: "inline" | "disable" | `${string}*`;
  minify?:
    | boolean
    | {
        whitespace?: boolean;
        syntax?: boolean;
        identifiers?: boolean;
      };
  /**
   * 忽略无用代码消除相关注释和 package.json 中 "sideEffects" 设置，仅作为库注释错误的临时解决方案
   */
  ignoreDCEAnnotations?: boolean;
  /**
   * 即使 minify.whitespace 为 true，也强制保留 @__PURE__ 注释
   */
  emitDCEAnnotations?: boolean;

  /**
   * 生成字节码，可显著减少冷启动时间，但会增加体积和内存占用。
   *
   * 仅支持 CommonJS (`format: "cjs"`)，必须配合 `target: "bun"` 使用
   *
   * @default false
   */
  bytecode?: boolean;
  /**
   * 添加代码顶部 banner，例如 "use client";
   */
  banner?: string;
  /**
   * 添加代码底部内容，如版权注释
   */
  footer?: string;

  /**
   * 移除匹配的函数调用
   */
  drop?: string[];

  /**
   * - true 时构建失败时拒绝并抛出 AggregateError；
   * - false 时返回 `{success: false}` 的 BuildOutput
   *
   * @default true
   */
  throw?: boolean;

  /**
   * 指定自定义 tsconfig.json 路径，用于路径解析
   * 等同于 CLI 的 `--tsconfig-override`
   */
  tsconfig?: string;

  outdir?: string;
}

interface BuildOutput {
  outputs: BuildArtifact[];
  success: boolean;
  logs: Array<BuildMessage | ResolveMessage>;
}

interface BuildArtifact extends Blob {
  path: string;
  loader: Loader;
  hash: string | null;
  kind: "entry-point" | "chunk" | "asset" | "sourcemap" | "bytecode";
  sourcemap: BuildArtifact | null;
}

type Loader =
  | "js"
  | "jsx"
  | "ts"
  | "tsx"
  | "css"
  | "json"
  | "jsonc"
  | "toml"
  | "yaml"
  | "text"
  | "file"
  | "napi"
  | "wasm"
  | "html";

interface BuildOutput {
  outputs: BuildArtifact[];
  success: boolean;
  logs: Array<BuildMessage | ResolveMessage>;
}

declare class ResolveMessage {
  readonly name: "ResolveMessage";
  readonly position: Position | null;
  readonly code: string;
  readonly message: string;
  readonly referrer: string;
  readonly specifier: string;
  readonly importKind:
    | "entry_point"
    | "stmt"
    | "require"
    | "import"
    | "dynamic"
    | "require_resolve"
    | "at"
    | "at_conditional"
    | "url"
    | "internal";
  readonly level: "error" | "warning" | "info" | "debug" | "verbose";

  toString(): string;
}
```

***

## CLI 用法

```bash theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build <入口点>
```

### 通用配置

<ParamField path="--production" type="boolean">
  设置 <code>NODE\_ENV=production</code> 并启用压缩
</ParamField>

<ParamField path="--bytecode" type="boolean">
  编译时使用字节码缓存
</ParamField>

<ParamField path="--target" type="string" default="browser">
  打包的预期执行环境。可选 <code>browser</code>、<code>bun</code> 或 <code>node</code>
</ParamField>

<ParamField path="--conditions" type="string">
  传递自定义解析条件
</ParamField>

<ParamField path="--env" type="string" default="disable">
  将环境变量内联到包中，形式为 <code>process.env.\${name_0}</code>。要内联匹配某个前缀的变量，可以使用类似{" "}
  <code>FOO\_PUBLIC\_\*</code> 的通配符
</ParamField>

### 输出与文件处理

<ParamField path="--outdir" type="string" default="dist">
  输出目录（用于构建多个入口点时）
</ParamField>

<ParamField path="--outfile" type="string">
  输出到指定文件
</ParamField>

<ParamField path="--sourcemap" type="string" default="none">
  生成源码映射。可选 <code>linked</code>、<code>inline</code>、<code>external</code> 或 <code>none</code>
</ParamField>

<ParamField path="--banner" type="string">
  在输出文件前添加标头（例如 React 服务器组件的 <code>"use client"</code>）
</ParamField>

<ParamField path="--footer" type="string">
  在输出文件尾部添加注释（例如 <code>// built with bun!</code>）
</ParamField>

<ParamField path="--format" type="string" default="esm">
  输出包的模块格式。可选 <code>esm</code>、<code>cjs</code> 或 <code>iife</code>。当使用 <code>--bytecode</code>{" "}
  时，默认值为 <code>cjs</code>。
</ParamField>

### 文件命名

<ParamField path="--entry-naming" type="string" default="[dir]/[name].[ext]">
  自定义入口点的文件名格式
</ParamField>

<ParamField path="--chunk-naming" type="string" default="[name]-[hash].[ext]">
  自定义代码块文件名格式
</ParamField>

<ParamField path="--asset-naming" type="string" default="[name]-[hash].[ext]">
  自定义资源文件名格式
</ParamField>

### 打包选项

<ParamField path="--root" type="string">
  打包多个入口点时使用的根目录
</ParamField>

<ParamField path="--splitting" type="boolean">
  启用共享模块的代码分割
</ParamField>

<ParamField path="--public-path" type="string">
  添加到打包代码中导入路径的前缀
</ParamField>

<ParamField path="--external" type="string">
  从包中排除模块（支持通配符）。别名：<code>-e</code>
</ParamField>

<ParamField path="--packages" type="string" default="bundle">
  依赖处理方式：<code>external</code> 或 <code>bundle</code>
</ParamField>

<ParamField path="--no-bundle" type="boolean">
  只进行转译，不打包
</ParamField>

<ParamField path="--css-chunking" type="boolean">
  合并 CSS 文件以减少重复（仅当多个入口点引入 CSS时生效）
</ParamField>

### 压缩与优化

<ParamField path="--emit-dce-annotations" type="boolean" default="true">
  重新输出死代码消除注释。在使用 <code>--minify-whitespace</code> 时禁用
</ParamField>

<ParamField path="--minify" type="boolean">
  启用所有压缩选项
</ParamField>

<ParamField path="--minify-syntax" type="boolean">
  压缩语法并内联常量
</ParamField>

<ParamField path="--minify-whitespace" type="boolean">
  压缩空白字符
</ParamField>

<ParamField path="--minify-identifiers" type="boolean">
  压缩变量和函数标识符
</ParamField>

<ParamField path="--keep-names" type="boolean">
  压缩时保留原始的函数和类名称
</ParamField>

### 开发功能

<ParamField path="--watch" type="boolean">
  文件变化时自动重建
</ParamField>

<ParamField path="--no-clear-screen" type="boolean">
  使用 <code>--watch</code> 时不清屏
</ParamField>

<ParamField path="--react-fast-refresh" type="boolean">
  启用 React 快速刷新转换（用于开发测试）
</ParamField>

<ParamField path="--react-compiler" type="boolean">
  在 `.jsx`/`.tsx` 文件上运行 React 编译器，自动对组件和 hooks 进行记忆化。输出模式由
  <code>--target</code> 决定（<code>browser</code> → client，<code>bun</code>/<code>node</code> → ssr）。实验性功能。
</ParamField>

### 独立可执行文件

<ParamField path="--compile" type="boolean">
  生成包含包的独立 Bun 可执行文件。隐含使用 <code>--production</code>
</ParamField>

<ParamField path="--compile-exec-argv" type="string">
  向独立可执行文件的 <code>execArgv</code> 前置参数
</ParamField>

### Windows 可执行文件详情

<ParamField path="--windows-hide-console" type="boolean">
  运行编译后的 Windows 可执行文件时防止打开控制台窗口
</ParamField>

<ParamField path="--windows-icon" type="string">
  设置 Windows 可执行文件图标
</ParamField>

<ParamField path="--windows-title" type="string">
  设置 Windows 可执行文件产品名称
</ParamField>

<ParamField path="--windows-publisher" type="string">
  设置 Windows 可执行文件公司名称
</ParamField>

<ParamField path="--windows-version" type="string">
  设置 Windows 可执行文件版本（例如 <code>1.2.3.4</code>）
</ParamField>

<ParamField path="--windows-description" type="string">
  设置 Windows 可执行文件描述
</ParamField>

<ParamField path="--windows-copyright" type="string">
  设置 Windows 可执行文件版权声明
</ParamField>

### 实验性功能及应用构建

<ParamField path="--app" type="boolean">
  <b>（实验性）</b> 使用 Bun Bake 构建生产环境的 Web 应用
</ParamField>

<ParamField path="--server-components" type="boolean">
  <b>（实验性）</b> 启用 React 服务器组件
</ParamField>

<ParamField path="--debug-dump-server-files" type="boolean">
  当设置了 <code>--app</code> 时，即使是静态构建也将所有服务器文件导出到磁盘
</ParamField>

<ParamField path="--debug-no-minify" type="boolean">
  当设置了 <code>--app</code> 时，禁用所有压缩
</ParamField>