esbuild

Bun 的打包器 API 深受 esbuild 启发。本页面对这两个 API 进行了并列比较。有一些行为有所不同：

默认进行打包。 与 esbuild 不同，Bun 默认会进行打包；无需使用 --bundle 标志。若要分别转译每个文件，请使用 Bun.Transpiler。

仅限打包器。 与 esbuild 不同，Bun 的打包器没有内置开发服务器。将其与 Bun.serve 及其他运行时 API 结合使用，即可实现相同的效果。esbuild 的 HTTP 选项不适用。

性能

Bun 的打包器在 esbuild 的 three.js 基准测试中比 esbuild 快 1.75 倍。

从零开始打包 10 份 three.js，启用源码映射和压缩

CLI API

terminal

# esbuild
esbuild <entrypoint> --outdir=out --bundle

# bun
bun build <entrypoint> --outdir=out

在 Bun 的 CLI 中，像 --minify 这样的布尔标志不接受参数。像 --outdir <path> 这样需要一个参数的标志，可以写成 --outdir out 或 --outdir=out。某些标志（如 --define）可以重复使用：--define foo=bar --define bar=baz。

esbuild	bun build	备注
`--bundle`	不适用	Bun 始终进行打包；使用 `--no-bundle` 可禁用打包。
`--define:K=V`	`--define K=V`	语法略有不同；没有冒号。 `esbuild --define:foo=bar` `bun build --define foo=bar`
`--external:<pkg>`	`--external <pkg>`	语法略有不同；没有冒号。 `esbuild --external:react` `bun build --external react`
`--format`	`--format`	Bun 支持 `"esm"`、`"cjs"` 和 `"iife"`。esbuild 默认为 `"iife"`。
`--loader:.ext=loader`	`--loader .ext:loader`	Bun 支持的内置加载器集合与 esbuild 不同；请参阅加载器。esbuild 的加载器 `dataurl`、`binary`、`base64`、`copy` 和 `empty` 尚未实现。 `--loader` 的语法有所不同。 `esbuild app.ts --bundle --loader:.svg=text` `bun build app.ts --loader .svg:text`
`--minify`	`--minify`	无差异
`--outdir`	`--outdir`	无差异
`--outfile`	`--outfile`	无差异
`--packages`	`--packages`	无差异
`--platform`	`--target`	为与 tsconfig 保持一致而重命名为 `--target`。不支持 `neutral`。
`--serve`	不适用	不适用
`--sourcemap`	`--sourcemap`	无差异
`--splitting`	`--splitting`	无差异
`--target`	不适用	不支持。Bun 的打包器不会执行语法降级。
`--watch`	`--watch`	无差异
`--allow-overwrite`	不适用	始终不允许覆盖
`--analyze`	不适用	不支持
`--asset-names`	`--asset-naming`	为与 JS API 中的命名保持一致而重命名
`--banner`	`--banner`	仅适用于 JS bundle
`--footer`	`--footer`	仅适用于 JS bundle
`--certfile`	不适用	不适用
`--charset=utf8`	不适用	不支持
`--chunk-names`	`--chunk-naming`	为与 JS API 中的命名保持一致而重命名
`--color`	不适用	始终启用
`--drop`	`--drop`
不适用	`--feature`	Bun 特有。通过 `import { feature } from "bun:bundle"` 启用编译时死代码消除的功能标志
`--entry-names`	`--entry-naming`	为与 JS API 中的命名保持一致而重命名
`--global-name`	不适用	不支持
`--ignore-annotations`	`--ignore-dce-annotations`
`--inject`	不适用	不支持
`--jsx`	`--jsx-runtime <runtime>`	支持 `"automatic"`（使用 JSX 转换）和 `"classic"`（使用 `React.createElement`）
`--jsx-dev`	不适用	Bun 从 `tsconfig.json` 中读取 `compilerOptions.jsx` 来确定默认值。如果 `compilerOptions.jsx` 为 `"react-jsx"`，或者 `NODE_ENV=production`，Bun 将使用 JSX 转换。否则将使用 `jsxDEV`。打包器不支持 `preserve`。
`--jsx-factory`	`--jsx-factory`
`--jsx-fragment`	`--jsx-fragment`
`--jsx-import-source`	`--jsx-import-source`
`--jsx-side-effects`	不适用	始终假定 JSX 没有副作用
`--keep-names`	`--keep-names`
`--keyfile`	不适用	不适用
`--legal-comments`	不适用	不支持
`--log-level`	不适用	不支持。可以在 `bunfig.toml` 中将其设置为 `logLevel`。
`--log-limit`	不适用	不支持
`--log-override:X=Y`	不适用	不支持
`--main-fields`	不适用	不支持
`--mangle-cache`	不适用	不支持
`--mangle-props`	不适用	不支持
`--mangle-quoted`	不适用	不支持
`--metafile`	`--metafile`
`--minify-whitespace`	`--minify-whitespace`
`--minify-identifiers`	`--minify-identifiers`
`--minify-syntax`	`--minify-syntax`
`--out-extension`	不适用	不支持
`--outbase`	`--root`
`--preserve-symlinks`	不适用	不支持
`--public-path`	`--public-path`
`--pure`	不适用	不支持
`--reserve-props`	不适用	不支持
`--resolve-extensions`	不适用	不支持
`--servedir`	不适用	不适用
`--source-root`	不适用	不支持
`--sourcefile`	不适用	不支持。Bun 不支持标准输入。
`--sourcemap`	`--sourcemap`	无差异
`--sources-content`	不适用	不支持
`--supported`	不适用	不支持
`--tree-shaking`	不适用	始终为 true
`--tsconfig`	`--tsconfig-override`
`--version`	不适用	运行 `bun --version` 查看 Bun 的版本。

JavaScript API

esbuild.build()	Bun.build()	备注
`absWorkingDir`	不适用	始终设置为 `process.cwd()`
`alias`	不适用	不支持
`allowOverwrite`	不适用	始终为 false
`assetNames`	`naming.asset`	使用与 esbuild 相同的模板语法，但必须显式包含 `[ext]`。 `ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> asset: "[name].[ext]",<br/> },<br/>});<br/>`
`banner`	`banner`	仅适用于 js bundle
`bundle`	不适用	始终为 true。使用 `Bun.Transpiler` 在不打包的情况下进行转译。
`charset`	不适用	不支持
`chunkNames`	`naming.chunk`	使用与 esbuild 相同的模板语法，但必须显式包含 `[ext]`。 `ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>`
`color`	不适用	Bun 将日志返回在构建结果的 `logs` 属性中。
`conditions`	`conditions`	无差异
`define`	`define`
`drop`	`drop`
`entryNames`	`naming` 或 `naming.entry`	Bun 支持 `naming` 键，该键可以是字符串或对象。使用与 esbuild 相同的模板语法，但必须显式包含 `[ext]`。 `ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> // 当为字符串时，这等价于 entryNames<br/> naming: "[name].[ext]",<br/><br/> // 细粒度的命名选项<br/> naming: {<br/> entry: "[name].[ext]",<br/> asset: "[name].[ext]",<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>`
`entryPoints`	`entrypoints`	大小写差异
`external`	`external`	无差异
`footer`	`footer`	仅适用于 js bundle
`format`	`format`	支持 `"esm"`、`"cjs"` 和 `"iife"`。
`globalName`	不适用	不支持
`ignoreAnnotations`	`ignoreDCEAnnotations`
`inject`	不适用	不支持
`jsx`	`jsx.runtime`	支持 `"automatic"` 和 `"classic"`
`jsxDev`	`jsx.development`
`jsxFactory`	`jsx.factory`
`jsxFragment`	`jsx.fragment`
`jsxImportSource`	`jsx.importSource`
`jsxSideEffects`	`jsx.sideEffects`
`keepNames`	`minify.keepNames`
`legalComments`	不适用	不支持
`loader`	`loader`	Bun 支持的内置 loader 集合与 esbuild 不同；请参阅加载器。esbuild 的 loader `dataurl`、`binary`、`base64`、`copy` 和 `empty` 尚未实现。
`logLevel`	不适用	不支持
`logLimit`	不适用	不支持
`logOverride`	不适用	不支持
`mainFields`	不适用	不支持
`mangleCache`	不适用	不支持
`mangleProps`	不适用	不支持
`mangleQuoted`	不适用	不支持
`metafile`	`metafile`
`minify`	`minify`	在 Bun 中，`minify` 可以是布尔值或对象。 `ts<br/>await Bun.build({<br/> entrypoints: ['./index.tsx'],<br/> // 启用所有压缩选项<br/> minify: true<br/><br/> // 细粒度选项<br/> minify: {<br/> identifiers: true,<br/> syntax: true,<br/> whitespace: true<br/> }<br/>})<br/>`
`minifyIdentifiers`	`minify.identifiers`	请参阅 `minify`
`minifySyntax`	`minify.syntax`	请参阅 `minify`
`minifyWhitespace`	`minify.whitespace`	请参阅 `minify`
`nodePaths`	不适用	不支持
`outExtension`	不适用	不支持
`outbase`	`root`	名称不同
`outdir`	`outdir`	无差异
`outfile`	`outfile`	无差异
`packages`	`packages`	无差异
`platform`	`target`	支持 `"bun"`、`"node"` 和 `"browser"`（默认值）。不支持 `"neutral"`。
`plugins`	`plugins`	Bun 的插件 API 是 esbuild 的子集。部分 esbuild 插件无需修改即可与 Bun 配合使用。
`preserveSymlinks`	不适用	不支持
`publicPath`	`publicPath`	无差异
`pure`	不适用	不支持
`reserveProps`	不适用	不支持
`resolveExtensions`	不适用	不支持
`sourceRoot`	不适用	不支持
`sourcemap`	`sourcemap`	支持 `"none"`、`"linked"`、`"inline"` 和 `"external"`
`sourcesContent`	不适用	不支持
`splitting`	`splitting`	无差异
`stdin`	不适用	不支持
`supported`	不适用	不支持
`target`	不适用	不支持语法降级
`treeShaking`	`treeShaking`	默认为 `true`
`tsconfig`	`tsconfig`
`write`	不适用	设置了 `outdir`/`outfile` 时设为 true，否则设为 false

插件 API

Bun 的插件 API 旨在兼容 esbuild。Bun 不支持 esbuild 的完整插件 API，但已实现核心功能，并且许多第三方 esbuild 插件无需修改即可与 Bun 一起使用。

从长远来看，我们的目标是实现与 esbuild API 的功能对等。如果某些功能无法正常工作，请提交 issue，帮助我们确定优先级。

Bun 和 esbuild 中的插件均通过构造一个 builder 对象定义。

myPlugin.ts

import type { BunPlugin } from "bun";

const myPlugin: BunPlugin = {
  name: "my-plugin",
  setup(builder) {
    // 定义插件
  },
};

builder 对象的方法会钩入打包过程的各个部分。Bun 实现了 onStart、onEnd、onResolve 和 onLoad；但未实现 esbuild 的 onDispose 和 resolve 钩子。initialOptions 已部分实现：它是只读的，并且仅暴露 esbuild 选项的子集。请改用 config（即 Bun 的 BuildConfig 格式中的同一配置）。

myPlugin.ts

import type { BunPlugin } from "bun";
const myPlugin: BunPlugin = {
  name: "my-plugin",
  setup(builder) {
    builder.onStart(() => {
      /* 当打包开始时调用 */
    });
    builder.onResolve(
      {
        /* onResolve 选项 */
      },
      args => {
        return {
          /* onResolve 返回值 */
        };
      },
    );
    builder.onLoad(
      {
        /* onLoad 选项 */
      },
      args => {
        return {
          /* onLoad 返回值 */
        };
      },
    );
    builder.onEnd(result => {
      /* 当打包完成时调用 */
    });
  },
};

onResolve

选项
参数
返回值

🟢 filter
🟢 namespace

🟢 path
🟢 importer
🟢 namespace
🟢 resolveDir
🟢 kind
🔴 pluginData

🟢 namespace
🟢 path
🔴 errors
🟢 external
🔴 pluginData
🔴 pluginName
🔴 sideEffects
🔴 suffix
🔴 warnings
🔴 watchDirs
🔴 watchFiles

onLoad

选项
参数
返回值

🟢 filter
🟢 namespace

🟢 path
🟢 namespace
🔴 suffix
🔴 pluginData

🟢 contents
🟢 loader
🔴 errors
🔴 pluginData
🔴 pluginName
🔴 resolveDir
🔴 warnings
🔴 watchDirs
🔴 watchFiles

核心

开发服务器

资源处理

可执行文件

扩展

优化

迁移

性能

CLI API

JavaScript API

插件 API

onResolve

onLoad

​性能

​CLI API

​JavaScript API

​插件 API

​onResolve

​onLoad

性能

CLI API

JavaScript API

插件 API

onResolve

onLoad