打包器 - Bun

使用 Bun 的原生打包器，通过 bun build CLI 命令或 Bun.build() JavaScript API。

一览

JS API：await Bun.build({ entrypoints, outdir })
CLI：bun build <entry> --outdir ./out
监视模式：--watch 用于增量重新构建
目标：--target browser|bun|node
格式：--format esm|cjs|iife（cjs/iife 为实验性）

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './build',
});

terminal

bun build ./index.tsx --outdir ./build

它很快。以下数据来自 esbuild 的 three.js 基准测试。

为什么要打包？

打包器解决了几个问题：

减少 HTTP 请求。 node_modules 中的单个包可能包含数百个文件，大型应用可能有几十个这样的依赖。用单独的 HTTP 请求加载每个文件是不可行的，因此打包器将你的应用源代码转换为数量更少的自包含”包”，可以通过单个请求加载。
代码转换。 现代应用通常使用 TypeScript、JSX 和 CSS 模块等语言或工具构建，所有这些在浏览器消费之前必须转换为普通 JavaScript 和 CSS。打包器是配置这些转换的自然位置。
框架功能。 框架依赖打包器插件和代码转换来实现常见模式，如文件系统路由、客户端-服务器代码共置（比如 getServerSideProps 或 Remix loader）以及服务器组件。
全栈应用。 Bun 的打包器可以在单个命令中处理服务器和客户端代码，实现优化后的生产构建和单文件可执行文件。通过构建时的 HTML 导入，你可以将整个应用程序（前端资源和后端服务器）打包到一个可部署的单元中。

Bun 打包器不打算替代 tsc 进行类型检查或生成类型声明。

基本示例

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

import * as ReactDOM from "react-dom/client";
import { Component } from "./Component";

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

export function Component(props: { message: string }) {
  return <h1>{props.message}</h1>;
}

这里，index.tsx 是应用的”入口点”：打包器开始的文件。通常这是一个执行某些副作用的脚本，比如启动服务器，或者在本例中初始化 React 根节点。因为这些文件使用了 TypeScript 和 JSX，代码必须先打包才能发送到浏览器。要创建包：

await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
});

bun build ./index.tsx --outdir ./out

对于 entrypoints 中指定的每个文件，Bun 生成一个新的包并将其写入 ./out 目录（从当前工作目录解析）。运行构建后，文件系统看起来像这样：

file system

.
├── index.tsx
├── Component.tsx
└── out
    └── index.js

out/index.js 的内容看起来像这样：

out/index.js

// out/index.js
// ...
// 约 20k 行代码
// 包含 `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,
  ),
);

监视模式

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

terminal

bun build ./index.tsx --outdir ./out --watch

内容类型

与 Bun 运行时一样，打包器默认支持一系列文件类型。下表列出了打包器的标准”加载器”。请参见加载器。

扩展名	详情
`.js` `.jsx` `.cjs` `.mjs` `.mts` `.cts` `.ts` `.tsx`	使用 Bun 的内置转译器解析文件并将 TypeScript/JSX 语法转译为普通 JavaScript。打包器执行一组默认转换，包括死代码消除和 tree shaking。Bun 不会向下转换语法；如果你使用最新的 ECMAScript 语法，它会在打包代码中原样出现。
`.json`	JSON 文件被解析并内联到打包产物中作为 JavaScript 对象。 `js<br/>import pkg from "./package.json";<br/>pkg.name; // => "my-package"<br/>`
`.jsonc`	带注释的 JSON。文件被解析并内联到打包产物中作为 JavaScript 对象。 `js<br/>import config from "./config.jsonc";<br/>config.name; // => "my-config"<br/>`
`.toml`	TOML 文件被解析并内联到打包产物中作为 JavaScript 对象。 `js<br/>import config from "./bunfig.toml";<br/>config.logLevel; // => "debug"<br/>`
`.yaml` `.yml`	YAML 文件被解析并内联到打包产物中作为 JavaScript 对象。 `js<br/>import config from "./config.yaml";<br/>config.name; // => "my-app"<br/>`
`.txt`	文本文件的内容被读取并内联到打包产物中作为字符串。 `js<br/>import contents from "./file.txt";<br/>console.log(contents); // => "Hello, world!"<br/>`
`.html`	HTML 文件被处理，引用的资源（脚本、样式表、图片）被打包。
`.css`	CSS 文件被打包到一起，生成输出目录中的单个 `.css` 文件。
`.node` `.wasm`	这些文件由 Bun 运行时支持，但在打包期间它们被视为资源。

资源

如果打包器遇到无法识别的扩展名的导入，它会将导入的文件视为外部文件。引用的文件被原样复制到 outdir 中，导入被解析为文件的路径。

// 打包入口点
import logo from "./logo.svg";
console.log(logo);

// 打包后的输出
var logo = "./logo-a7305bdef.svg";
console.log(logo);

文件加载器的确切行为还取决于 naming 和 publicPath。

关于文件加载器的更多信息，请参见加载器。

插件

插件可以覆盖或扩展此表中描述的行为。请参见加载器。

API

entrypoints

必需对应应用入口点的路径数组。Bun 为每个入口点生成一个包。

JavaScript
CLI

build.ts

const result = await Bun.build({
  entrypoints: ["./index.ts"],
});
// => { success: boolean, outputs: BuildArtifact[], logs: BuildMessage[] }

terminal

bun build ./index.ts

files

一个文件路径到文件内容的映射，用于内存中打包：打包磁盘上不存在的虚拟文件，或覆盖确实存在的文件内容。此选项仅在 JavaScript API 中可用。文件内容可以作为 string、Blob、TypedArray 或 ArrayBuffer 提供。

完全从内存中打包

你可以在没有任何磁盘文件的情况下打包代码，方法是在 files 中提供所有源代码：

build.ts

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 映射中时，当前工作目录被用作根目录。

覆盖磁盘上的文件

内存中的文件优先于磁盘上的文件，因此你可以在保持代码库其余部分不变的同时覆盖特定文件：

build.ts

// 假设 ./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",
});

混合磁盘和虚拟文件

磁盘上的真实文件可以导入虚拟文件，虚拟文件也可以导入真实文件：

build.ts

// ./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

输出文件写入的目录。

JavaScript
CLI

build.ts

const result = await Bun.build({
  entrypoints: ['./index.ts'],
  outdir: './out'
});
// => { success: boolean, outputs: BuildArtifact[], logs: BuildMessage[] }

terminal

bun build ./index.ts --outdir ./out

如果 JavaScript API 没有传入 outdir，打包后的代码不会写入磁盘。打包后的文件以 BuildArtifact 对象数组的形式返回。这些对象是带有额外属性的 Blob；请参见输出。

build.ts

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

打包产物的预期执行环境。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.ts'],
  outdir: './out',
  target: 'browser', // 默认
})

terminal

bun build ./index.ts --outdir ./out --target browser

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

browser

默认。 适用于在浏览器中运行的包。解析导入时优先考虑 "browser" 导出条件。导入内置模块如 node:events 或 node:path 可以工作，但调用某些函数，如 fs.readFile，则不行。

bun

适用于在 Bun 运行时中运行的包。在许多情况下，没有必要打包服务器端代码；你可以直接执行源代码而无需修改。然而，打包你的服务器代码可以减少启动时间并提高运行性能。将此目标用于具有构建时 HTML 导入的全栈应用，其中服务器和客户端代码被打包在一起。所有以 target: "bun" 生成的包都带有 // @bun 编译指示，这告诉 Bun 运行时在执行前无需重新转译文件。如果任何入口点包含 Bun shebang（#!/usr/bin/env bun），打包器默认使用 target: "bun" 而不是 "browser"。当同时使用 target: "bun" 和 format: "cjs" 时，会添加 // @bun @bun-cjs 编译指示，并且 CommonJS 包装函数与 Node.js 不兼容。

node

适用于在 Node.js 中运行的包。解析导入时优先考虑 "node" 导出条件。Bun 不会 polyfill Bun 全局变量或内置的 bun:* 模块。

format

指定生成打包产物的模块格式。 Bun 默认使用 "esm"，并提供了对 "cjs" 和 "iife" 的实验性支持。

format: “esm” - ES Module

默认格式。支持 ES Module 语法，包括顶层 await 和 import.meta。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  format: "esm",
})

terminal

bun build ./index.tsx --outdir ./out --format esm

要在浏览器中使用 ES Module 语法，将 format 设置为 "esm"，并使用 <script type="module"> 标签加载包。

format: “cjs” - CommonJS

要构建 CommonJS 模块，将 format 设置为 "cjs"。选择 "cjs" 时，默认目标从 "browser"（esm）变为 "node"（cjs）。使用 format: "cjs"、target: "node" 转译的 CommonJS 模块在 Bun 和 Node.js 中都运行（假设使用的 API 两者都支持）。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  format: "cjs",
})

terminal

bun build ./index.tsx --outdir ./out --format cjs

format: “iife” - IIFE

TODO：在支持 globalNames 后记录 IIFE。

`jsx`

配置 JSX 的编译方式。 经典运行时示例（使用 factory 和 fragment）：

await Bun.build({
  entrypoints: ["./app.tsx"],
  outdir: "./out",
  jsx: {
    factory: "h",
    fragment: "Fragment",
    runtime: "classic",
  },
});

# JSX 配置通过 bunfig.toml 或 tsconfig.json 处理
bun build ./app.tsx --outdir ./out

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

await Bun.build({
  entrypoints: ["./app.tsx"],
  outdir: "./out",
  jsx: {
    importSource: "preact",
    runtime: "automatic",
  },
});

# JSX 配置通过 bunfig.toml 或 tsconfig.json 处理
bun build ./app.tsx --outdir ./out

splitting

是否启用代码分割。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  splitting: false, // 默认
})

terminal

bun build ./index.tsx --outdir ./out --splitting

当为 true 时，打包器启用代码分割。当多个入口点导入相同的文件或模块时，打包器可以将共享代码分割为单独的包，称为块。考虑以下文件：

import { shared } from "./shared.ts";

import { shared } from "./shared.ts";

export const shared = "shared";

要打包启用了代码分割的 entry-a.ts 和 entry-b.ts：

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./entry-a.ts', './entry-b.ts'],
  outdir: './out',
  splitting: true,
})

terminal

bun build ./entry-a.ts ./entry-b.ts --outdir ./out --splitting

运行此构建会生成以下文件：

file system

.
├── entry-a.tsx
├── entry-b.tsx
├── shared.tsx
└── out
    ├── entry-a.js
    ├── entry-b.js
    └── chunk-2fce6291bf86559d.js

生成的 chunk-2fce6291bf86559d.js 文件包含共享代码。为避免冲突，文件名默认包含内容哈希。使用 naming 自定义。

plugins

在打包期间使用的插件列表。

build.ts

await Bun.build({
  entrypoints: ["./index.tsx"],
  outdir: "./out",
  plugins: [
    /* ... */
  ],
});

Bun 的插件系统由运行时和打包器共享。请参见插件。

env

控制打包期间环境变量的处理方式。内部使用 define 将环境变量注入打包产物；env 是指定哪些变量的简写。

env: “inline”

通过将 process.env.FOO 引用转换为包含实际环境变量值的字符串字面量，将环境变量注入打包输出。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  env: "inline",
})

terminal

bun build ./index.tsx --outdir ./out --env inline

对于以下输入：

input.js

// input.js
console.log(process.env.FOO);
console.log(process.env.BAZ);

生成的包包含以下代码：

output.js

// output.js
console.log("bar");
console.log("123");

env: “PUBLIC_*“（前缀）

内联匹配给定前缀（* 字符之前的部分）的环境变量，将 process.env.FOO 替换为实际的环境变量值。使用前缀可只内联公共值，如面向外部的 URL 或客户端令牌，而无需将私有凭据注入输出包中。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  
  // 内联所有以 "ACME_PUBLIC_" 开头的环境变量
  env: "ACME_PUBLIC_*",
})

terminal

bun build ./index.tsx --outdir ./out --env ACME_PUBLIC_*

例如，给定以下环境变量：

terminal

FOO=bar BAZ=123 ACME_PUBLIC_URL=https://acme.com

以及源代码：

index.tsx

console.log(process.env.FOO);
console.log(process.env.ACME_PUBLIC_URL);
console.log(process.env.BAZ);

生成的包包含以下代码：

output.js

console.log(process.env.FOO);
console.log("https://acme.com");
console.log(process.env.BAZ);

env: “disable”

完全禁用环境变量注入。

sourcemap

指定生成的 sourcemap 类型。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  sourcemap: 'linked', // 默认 'none'
})

terminal

bun build ./index.tsx --outdir ./out --sourcemap linked

值	描述
`"none"`	默认。不生成 sourcemap。
`"linked"`	在每个 `.js` 包旁创建一个单独的 `.js.map` 文件，使用 `//# sourceMappingURL` 注释将两者关联。需要设置 `--outdir`。其基础 URL 可以通过 `--public-path` 自定义。 `js<br/>// <打包后的代码><br/><br/>//# sourceMappingURL=bundle.js.map<br/>`
`"external"`	在每个 `.js` 包旁创建一个单独的 `.js.map` 文件，但不插入 `//# sourceMappingURL` 注释。生成的包包含一个调试 ID，可用于将包与其对应的 sourcemap 关联起来。此 `debugId` 作为注释添加到文件底部。 `js<br/>// <生成的包代码><br/><br/>//# debugId=<DEBUG ID><br/>`
`"inline"`	生成 sourcemap 并作为 base64 载荷附加到生成的包末尾。 `js<br/>// <打包后的代码><br/><br/>//# sourceMappingURL=data:application/json;base64,<编码后的 sourcemap><br/>`

相关的 *.js.map sourcemap 是一个 JSON 文件，包含等效的 debugId 属性。

minify

是否启用压缩。默认为 false。要启用所有压缩选项：

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  minify: true, // 默认 false
})

terminal

bun build ./index.tsx --outdir ./out --minify

要精细启用某些压缩：

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  minify: {
    whitespace: true,
    identifiers: true,
    syntax: true,
  },
})

terminal

bun build ./index.tsx --outdir ./out --minify-whitespace --minify-identifiers --minify-syntax

external

要视为外部的导入路径列表。默认为 []。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  external: ["lodash", "react"], // 默认：[]
})

terminal

bun build ./index.tsx --outdir ./out --external lodash --external react

外部导入不会包含在最终包中。相反，导入语句原样保留，在运行时解析。例如，考虑以下入口点文件：

index.tsx

import _ from "lodash";
import { z } from "zod";

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

通常，打包 index.tsx 会生成包含 “zod” 包完整源代码的包。要原样保留导入语句，将其标记为外部：

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  external: ['zod'],
})

terminal

bun build ./index.tsx --outdir ./out --external zod

生成的包看起来像这样：

out/index.js

import { z } from "zod";

// ...
// "lodash" 包的内容
// 包括 `_.upperCase` 函数

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

要将所有导入标记为外部，使用通配符 *：

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  external: ['*'],
})

terminal

bun build ./index.tsx --outdir ./out --external '*'

packages

控制是否在包中包含包依赖项。可能的值：bundle（默认）、external。Bun 将任何路径不以 .、.. 或 / 开头的导入视为包。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.ts'],
  packages: 'external',
})

terminal

bun build ./index.ts --packages external

naming

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

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  naming: "[dir]/[name].[ext]", // 默认
})

terminal

bun build ./index.tsx --outdir ./out --entry-naming "[dir]/[name].[ext]"

默认情况下，生成的包名称基于关联入口点的名称。

file system

.
├── index.tsx
└── out
    └── index.js

对于多个入口点，生成的文件层次结构反映入口点的目录结构。

file system

.
├── 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"`

组合这些令牌以创建模板字符串。例如，在生成的包名称中包含哈希：

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  naming: 'files/[dir]/[name]-[hash].[ext]',
})

terminal

bun build ./index.tsx --outdir ./out --entry-naming 'files/[dir]/[name]-[hash].[ext]'

此构建将产生以下文件结构：

file system

.
├── index.tsx
└── out
    └── files
        └── index-a1b2c3d4.js

当为 naming 字段提供字符串时，仅用于对应入口点的包。块和复制资源的名称不受影响。在 JavaScript API 中，你可以为每种类型的生成文件指定单独的模板字符串。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  naming: {
    // 默认值
    entry: '[dir]/[name].[ext]',
    chunk: '[name]-[hash].[ext]',
    asset: '[name]-[hash].[ext]',
  },
})

terminal

bun build ./index.tsx --outdir ./out \
  --entry-naming '[dir]/[name].[ext]' \
  --chunk-naming '[name]-[hash].[ext]' \
  --asset-naming '[name]-[hash].[ext]'

root

项目的根目录。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./pages/a.tsx', './pages/b.tsx'],
  outdir: './out',
  root: '.',
})

terminal

bun build ./pages/a.tsx ./pages/b.tsx --outdir ./out --root .

如果未指定，它会计算为所有入口点文件的第一个公共祖先。考虑以下文件结构：

file system

.
└── pages
  └── index.tsx
  └── settings.tsx

构建 pages 目录中的两个入口点：

JavaScript
CLI

await Bun.build({
  entrypoints: ['./pages/index.tsx', './pages/settings.tsx'],
  outdir: './out',
})

bun build ./pages/index.tsx ./pages/settings.tsx --outdir ./out

这将产生如下文件结构：

file system

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

由于 pages 目录是入口点文件的第一个公共祖先，它被视为项目根目录，因此生成的包位于 out 目录的顶层；没有 out/pages 目录。通过指定 root 选项覆盖此行为：

JavaScript
CLI

await Bun.build({
  entrypoints: ['./pages/index.tsx', './pages/settings.tsx'],
  outdir: './out',
  root: '.',
})

bun build ./pages/index.tsx ./pages/settings.tsx --outdir ./out --root .

以 . 为 root，生成的文件结构如下：

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

publicPath

添加到打包代码中任何导入路径的前缀。在许多情况下，生成的包不包含导入语句；打包的目标是将所有代码合并到一个文件中。然而，在少数情况下，生成的包确实包含导入语句：

资源导入 — 当导入无法识别的文件类型如 *.svg 时，打包器委托文件加载器处理，该加载器将文件原样复制到 outdir 中。导入被转换为变量。
外部模块 — 标记为外部的文件和模块不会包含在包中。相反，导入语句保留在最终包中。
分块。当启用 splitting 时，打包器可能会生成代表多个入口点间共享代码的单独”块”文件。

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

import logo from "./logo.svg";
console.log(logo);

var logo = "./logo-a7305bdef.svg";
console.log(logo);

设置 publicPath 会为所有文件路径添加指定值作为前缀。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  publicPath: 'https://cdn.example.com/', // 默认为 undefined
})

terminal

bun build ./index.tsx --outdir ./out --public-path 'https://cdn.example.com/'

输出文件现在看起来像这样：

out/index.js

var logo = "https://cdn.example.com/logo-a7305bdef.svg";

define

要在构建时替换的全局标识符映射。此对象的键是标识符名称，值是内联的 JSON 字符串。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  define: {
    STRING: JSON.stringify("value"),
    "nested.boolean": "true",
  },
})

terminal

bun build ./index.tsx --outdir ./out --define STRING='"value"' --define nested.boolean=true

loader

文件扩展到内置加载器名称的映射。用于自定义某些文件的加载方式。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  loader: {
    ".png": "dataurl",
    ".txt": "file",
  },
})

terminal

bun build ./index.tsx --outdir ./out --loader .png:dataurl --loader .txt:file

添加到最终包的 banner。可以是像 React 的 "use client" 这样的指令，或像许可证这样的注释块。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  banner: '"use client";'
})

terminal

bun build ./index.tsx --outdir ./out --banner '"use client";'

添加到最终包的 footer。可以是许可证的注释块或有趣的彩蛋。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  footer: '// built with love in SF'
})

terminal

bun build ./index.tsx --outdir ./out --footer '// built with love in SF'

drop

从包中移除函数调用。例如，--drop=console 移除对 console.log 的所有调用。被丢弃调用的参数也会被移除，即使它们有副作用。丢弃 debugger 会移除所有 debugger 语句。

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./index.tsx'],
  outdir: './out',
  drop: ["console", "debugger", "anyIdentifier.or.propertyAccess"],
})

terminal

bun build ./index.tsx --outdir ./out --drop console --drop debugger

features

为死代码消除启用编译时特性标志：使用 import { feature } from "bun:bundle" 在打包时有条件地包含或排除代码路径。

app.ts

import { feature } from "bun:bundle";

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

if (feature("DEBUG")) {
  // 仅在启用 DEBUG 标志时包含
  console.log("Debug 模式");
}

JavaScript
CLI

build.ts

await Bun.build({
  entrypoints: ['./app.ts'],
  outdir: './out',
  features: ["PREMIUM"],  // PREMIUM=true, DEBUG=false
})

terminal

bun build ./app.ts --outdir ./out --feature PREMIUM

feature() 函数在打包时被替换为 true 或 false。结合压缩，不可达代码被消除：

输入

import { feature } from "bun:bundle";
const mode = feature("PREMIUM") ? "premium" : "free";

输出（带 --feature PREMIUM --minify）

var mode = "premium";

输出（不带 --feature PREMIUM，带 --minify）

var mode = "free";

关键行为：

feature() 需要字符串字面量参数——不支持动态值
bun:bundle 导入完全从输出中移除
适用于 bun build、bun run 和 bun test
多个标志可以同时启用：--feature FLAG_A --feature FLAG_B
对于类型安全，扩展 Registry 接口以将 feature() 限制为已知标志

用例：

平台特定代码（feature("SERVER") vs feature("CLIENT")）
基于环境的功能（feature("DEVELOPMENT")）
渐进式功能发布
A/B 测试变体
付费层级功能

类型安全： 默认情况下，feature() 接受任何字符串。要获得自动补全并在编译时捕获拼写错误，创建一个 env.d.ts 文件（或添加到现有的 .d.ts）并扩展 Registry 接口：

env.d.ts

declare module "bun:bundle" {
  interface Registry {
    features: "DEBUG" | "PREMIUM" | "BETA_FEATURES";
  }
}

确保该文件包含在你的 tsconfig.json 中（例如，"include": ["src", "env.d.ts"]）。现在 feature() 只接受这些标志，像 feature("TYPO") 这样的无效字符串会变成类型错误。

optimizeImports

跳过对 barrel 文件（重新导出的索引文件）中未使用子模块的解析。当你从大型库中只导入少量命名导出时，通常打包器会解析 barrel 重新导出的每个文件。使用 optimizeImports，只解析你使用的子模块。

build.ts

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 子模块。这适用于纯 barrel 文件——每个命名导出都是重新导出的文件（export { X } from './x'）。如果 barrel 文件有任何本地导出（export const foo = ...），或者任何导入者使用 import *，所有子模块都会被加载。 export * 重新导出总是被加载（从不延迟）以避免循环解析问题。只有不被任何导入者使用的命名重新导出（export { X } from './x'）会被延迟。 自动模式： 在 package.json 中带有 "sideEffects": false 的包会自动获得 barrel 优化——无需配置 optimizeImports。对于没有此字段的包，使用 optimizeImports。 插件： Resolve 和 load 插件与 barrel 优化一起工作。延迟的子模块在最终加载时会经过插件流水线。

metafile

以结构化格式生成关于构建的元数据。元数据描述每个输入和输出文件：大小、导入和导出。用于：

包分析：了解哪些内容对包体积有贡献
可视化：输入到 esbuild 的包分析器等工具
依赖跟踪：查看应用程序的完整导入图
CI 集成：跟踪包体积随时间的变化

JavaScript
CLI

build.ts

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));
}

terminal

bun build ./src/index.ts --outdir ./dist --metafile ./dist/meta.json

Markdown 元数据文件

使用 --metafile-md 生成 markdown 格式的元数据文件，对 LLM 友好，终端可读：

terminal

bun build ./src/index.ts --outdir ./dist --metafile-md ./dist/meta.md

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

terminal

bun build ./src/index.ts --outdir ./dist --metafile ./dist/meta.json --metafile-md ./dist/meta.md

`metafile` 选项格式

在 JavaScript API 中，metafile 接受多种形式：

build.ts

// 布尔值 —— 在结果对象中包含 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",
  },
});

元数据结构包含：

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>，定义如下：

build.ts

interface BuildOutput {
  outputs: BuildArtifact[];
  success: boolean;
  logs: Array<object>; // 详情请见文档
  metafile?: BuildMetafile; // 仅在 metafile: true 时可用
}

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

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

build.ts

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`	用于解释文件的加载器。有关 Bun 如何将文件扩展名映射到内置加载器的信息，请参见加载器。
`hash`	文件内容的哈希值。对于资源始终定义。
`sourcemap`	与此文件对应的 sourcemap 文件（如果生成）。仅对入口点和块定义。

与 BunFile 类似，BuildArtifact 对象可以直接传递给 new Response()。

build.ts

const build = await Bun.build({
  /* */
});

const artifact = build.outputs[0];

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

Bun 运行时漂亮地打印 BuildArtifact 对象以简化调试。

// build.ts
const build = await Bun.build({
  /* */
});

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

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
  }
}

字节码

bytecode: boolean 选项为任何 JavaScript/TypeScript 入口点生成字节码，这可以大大改善大型应用的启动时间。需要 "target": "bun" 和匹配的 Bun 版本。

CommonJS：可以使用或不使用 compile: true。在每个入口点旁边生成一个 .jsc 文件。
ESM：需要 compile: true。字节码和模块元数据嵌入到独立可执行文件中。

没有显式的 format 时，字节码默认为 CommonJS。

JavaScript
CLI

build.ts

// 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,
})

terminal

# CommonJS 字节码
bun build ./index.tsx --outdir ./out --bytecode

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

可执行文件

Bun 支持将 JavaScript/TypeScript 入口点”编译”为独立可执行文件。此可执行文件包含一份 Bun 二进制文件的副本。

terminal

bun build ./cli.tsx --outfile mycli --compile
./mycli

请参见独立可执行文件。

日志和错误

失败时，Bun.build 返回一个带有 AggregateError 的 rejected promise。将其记录到控制台以漂亮打印错误列表，或使用 try/catch 块以编程方式读取。

build.ts

try {
  const result = await Bun.build({
    entrypoints: ["./index.tsx"],
    outdir: "./out",
  });
} catch (e) {
  // TypeScript 不允许在 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。 error.errors 中的每个项都是 BuildMessage 或 ResolveMessage（Error 的子类）的实例，包含每个错误的详细信息。

build.ts

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 属性，其中包含打包器的警告和信息消息。

build.ts

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);
  }
}

参考

TypeScript 定义

interface Bun {
  build(options: BuildOptions): Promise<BuildOutput>;
}

interface BuildConfig {
  entrypoints: string[]; // 文件路径列表
  outdir?: string; // 输出目录
  target?: Target; // 默认："browser"
  /**
   * 输出模块格式。仅 `"esm"` 支持顶层 await。
   *
   * 可以为：
   * - `"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; // 默认 false，启用代码分割
  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` 条件
   *
   * 等同于 `bun build` 或 `bun run` 中的 `--conditions`。
   *
   * https://nodejs.org/api/packages.html#exports
   */
  conditions?: Array<string> | string;

  /**
   * 控制打包期间环境变量的处理方式。
   *
   * 可以为：
   * - `"inline"`：通过将 `process.env.FOO` 引用转换为包含实际环境变量值的字符串字面量，将环境变量注入打包输出
   * - `"disable"`：完全禁用环境变量注入
   * - 以 `*` 结尾的字符串：内联匹配给定前缀的环境变量。
   *   例如，`"MY_PUBLIC_*"` 只会包含以 "MY_PUBLIC_" 开头的环境变量
   */
  env?: "inline" | "disable" | `${string}*`;
  minify?:
    | boolean
    | {
        whitespace?: boolean;
        syntax?: boolean;
        identifiers?: boolean;
      };
  /**
   * 忽略死代码消除/tree-shaking 注解，如 @__PURE__ 和 package.json
   * "sideEffects" 字段。仅应作为库中不正确注解的临时解决方法使用。
   */
  ignoreDCEAnnotations?: boolean;
  /**
   * 即使 minify.whitespace 为 true，也强制发出 @__PURE__ 注解。
   */
  emitDCEAnnotations?: boolean;

  /**
   * 为输出生成字节码。这可以显著改善冷启动
   * 时间，但会使最终输出更大并略微增加
   * 内存使用。
   *
   * - CommonJS：可以使用或不使用 `compile: true`
   * - ESM：需要 `compile: true`
   *
   * 没有显式的 `format` 时，默认为 CommonJS。
   *
   * 必须为 `target: "bun"`
   * @default false
   */
  bytecode?: boolean;
  /**
   * 向打包代码添加 banner，例如 "use client";
   */
  banner?: string;
  /**
   * 向打包代码添加 footer，例如注释块
   *
   * `// made with bun!`
   */
  footer?: string;

  /**
   * 丢弃匹配属性访问的函数调用。
   */
  drop?: string[];

  /**
   * - 设置为 `true` 时，当构建失败时返回的 promise 会以 AggregateError 拒绝。
   * - 设置为 `false` 时，返回带有 `{success: false}` 的 {@link 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 用法

bun build <entry points>

通用配置

boolean

设置 NODE_ENV=production 并启用压缩

boolean

编译时使用字节码缓存

string

default:"browser"

打包的预期执行环境。可选：browser、bun 或 node

string

传递自定义解析条件

string

default:"disable"

将环境变量内联到打包文件中，作为 process.env.$。要内联匹配前缀的变量，使用类似 FOO_PUBLIC_* 的 glob

输出与文件处理

string

default:"dist"

输出目录（构建多个入口点时使用）

string

将输出写入特定文件

string

default:"none"

生成 source map。可选：linked、inline、external 或 none

string

在输出中添加横幅（例如 React Server Components 的 “use client”）

string

在输出中添加页脚（例如 // built with bun!）

string

default:"esm"

输出包的模块格式。可选：esm、cjs 或 iife。使用 —bytecode 时默认为 cjs

文件命名

string

default:"[dir]/[name].[ext]"

自定义入口点文件名

string

default:"[name]-[hash].[ext]"

自定义代码块文件名

string

default:"[name]-[hash].[ext]"

自定义资源文件名

打包选项

string

打包多个入口点时使用的根目录

boolean

为共享模块启用代码分割

string

添加到打包代码中导入路径的前缀

string

从打包中排除模块（支持通配符）。别名：-e

string

default:"bundle"

如何处理依赖：external 或 bundle

boolean

仅转译——不打包

boolean

将 CSS 文件合并打包以减少重复（仅在多个入口点导入 CSS 时）

压缩与优化

boolean

default:"true"

重新发出死代码消除注解。使用 —minify-whitespace 时禁用

boolean

启用所有压缩选项

boolean

压缩语法和内联常量

boolean

压缩空白

boolean

压缩变量和函数标识符

boolean

压缩时保留原始函数和类名

开发功能

boolean

文件变化时自动重新构建

boolean

使用 —watch 重新构建时不清除终端屏幕

boolean

启用 React Fast Refresh 转换（用于开发测试）

boolean

在 .jsx/.tsx 文件上运行 React Compiler，自动记忆组件和钩子。输出模式由 —target 决定（browser → 客户端，bun/node → ssr）。实验性功能。

独立可执行文件

boolean

生成包含打包文件的独立 Bun 可执行文件

string

将参数预先附加到独立可执行文件的 execArgv

Windows 可执行文件详情

boolean

运行编译后的 Windows 可执行文件时阻止控制台窗口打开

string

设置 Windows 可执行文件的图标

string

设置 Windows 可执行文件的产品名称

string

设置 Windows 可执行文件的公司名称

string

设置 Windows 可执行文件的版本（例如 1.2.3.4）

string

设置 Windows 可执行文件的描述

string

实验性与应用构建

boolean

（实验性）使用 Bun Bake 构建生产版 Web 应用

boolean

（实验性）启用 React Server Components

boolean

当设置了 —app 时，即使在静态构建中也将所有服务端文件转储到磁盘

boolean

当设置了 —app 时，禁用所有压缩

​一览

​为什么要打包？

​基本示例

​监视模式

​内容类型

​资源

​插件

​API

​entrypoints

​files

​完全从内存中打包

​覆盖磁盘上的文件

​混合磁盘和虚拟文件

​outdir

​target

browser

bun

node

​format

​format: “esm” - ES Module

​format: “cjs” - CommonJS

​format: “iife” - IIFE

​jsx

​splitting

​plugins

​env

​env: “inline”

​env: “PUBLIC_*“（前缀）

​env: “disable”

​sourcemap

​minify

​external

​packages

​naming

​root

​publicPath

​define

​loader

​banner

​footer

​drop

​features

​optimizeImports

​metafile

​Markdown 元数据文件

​metafile 选项格式

​输出

​字节码

​可执行文件

​日志和错误

​参考

​CLI 用法

​通用配置

​输出与文件处理

​文件命名

​打包选项

​压缩与优化

​开发功能

​独立可执行文件

​Windows 可执行文件详情

​实验性与应用构建

一览

为什么要打包？

基本示例

监视模式

内容类型

资源

插件

API

entrypoints

files

完全从内存中打包

覆盖磁盘上的文件

混合磁盘和虚拟文件

outdir

target

format

format: “esm” - ES Module

format: “cjs” - CommonJS

format: “iife” - IIFE

`jsx`

splitting

plugins

env

env: “inline”

env: “PUBLIC_*“（前缀）

env: “disable”

sourcemap

minify

external

packages

naming

root

publicPath

define

loader

banner

footer

drop

features

optimizeImports

metafile

Markdown 元数据文件

`metafile` 选项格式

输出

字节码

可执行文件

日志和错误

参考

CLI 用法

通用配置

输出与文件处理

文件命名

打包选项

压缩与优化

开发功能

独立可执行文件

Windows 可执行文件详情

实验性与应用构建