Skip to main content
Bun 的打包器 API 深受 esbuild 的启发。从 esbuild 迁移到 Bun 的打包器应该相对简单。本文档将简要说明为何你可能考虑迁移到 Bun 的打包器，并且为那些已经熟悉 esbuild API 的用户提供并排的 API 对比参考。 这里有一些行为上的差异需要注意。
默认进行打包。 与 esbuild 不同，Bun 默认总是进行打包。这就是为何 Bun 的示例中不需要 --bundle 标志。要对每个文件单独转译，请使用 Bun.Transpiler。
它只是一个打包器。 与 esbuild 不同，Bun 的打包器不包含内置的开发服务器或文件监听器。它只是一个打包器。该打包器旨在与 Bun.serve 及其他运行时 API 结合使用，以实现相同效果。因此，所有与 HTTP/文件监听相关的选项均不适用。

​
性能

凭借性能优先的 API 及经过大量优化的基于 Zig 的 JS/TS 解析器，Bun 的打包器在 esbuild 的 three.js 性能基准上比 esbuild 快 1.75 倍。
从零开始打包 10 份 three.js，启用源码映射和压缩

​
CLI API

Bun 和 esbuild 都提供了命令行接口。
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。
esbuildbun 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--formatBun 当前支持 "esm" 和 "cjs"，更多模块格式计划支持。esbuild 默认 "iife"。
--loader:.ext=loader--loader .ext:loaderBun 支持的内置加载器集合与 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重命名为 --target，以与 tsconfig 保持一致。不支持 neutral。
--serve不适用不适用
--sourcemap--sourcemap无区别
--splitting--splitting无区别
--target不适用不支持。Bun 的打包器目前不支持语法层级降级。
--watch--watch无区别
--allow-overwrite不适用不允许覆盖
--analyze不适用不支持
--asset-names--asset-naming重命名以统一 JS API 命名
--banner--banner仅应用于 js 打包
--footer--footer仅应用于 js 打包
--certfile不适用不适用
--charset=utf8不适用不支持
--chunk-names--chunk-naming重命名以统一 JS API 命名
--color不适用始终启用
--drop--drop
不适用--featureBun 特有。通过 import { feature } from "bun:bundle" 启用编译时死代码消除的特性标志
--entry-names--entry-naming重命名以统一 JS API 命名
--global-name不适用不适用，Bun 目前不支持 iife 输出
--ignore-annotations--ignore-dce-annotations
--inject不适用不支持
--jsx--jsx-runtime <runtime>支持 "automatic"（使用 jsx 转换）和 "classic"（使用 React.createElement）
--jsx-dev不适用Bun 从 tsconfig.json 的 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不适用不支持
--keyfile不适用不适用
--legal-comments不适用不支持
--log-level不适用不支持，可在 bunfig.toml 通过 logLevel 设置
--log-limit不适用不支持
--log-override:X=Y不适用不支持
--main-fields不适用不支持
--mangle-cache不适用不支持
--mangle-props不适用不支持
--mangle-quoted不适用不支持
--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不适用始终开启
--tsconfig--tsconfig-override
--version不适用运行 bun --version 查看 Bun 版本

​
JavaScript API

esbuild.build()Bun.build()说明
absWorkingDir不适用总是设置为 process.cwd()
alias不适用不支持
allowOverwrite不适用总是为 false
assetNamesnaming.asset使用与 esbuild 相同的模板语法，但必须显式包含 [ext]。

ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> asset: "[name].[ext]",<br/> },<br/>});<br/>
banner不适用不支持
bundle不适用总是开启。若不想打包，请使用 Bun.Transpiler 进行转译。
charset不适用不支持
chunkNamesnaming.chunk使用与 esbuild 相同的模板语法，但必须显式包含 [ext]。

ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
color不适用Bun 会在构建结果的 logs 属性中返回日志内容。
conditions不适用不支持。导出条件优先级由 target 决定。
definedefine
drop不适用不支持
entryNamesnaming 或 naming.entryBun 支持 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/>
entryPointsentrypoints大小写差异
externalexternal无区别
footer不适用不支持
formatformat目前仅支持 "esm"。计划支持 "cjs" 和 "iife"。
globalName不适用不支持
ignoreAnnotations不适用不支持
inject不适用不支持
jsxjsxJS API 中不支持，通过 tsconfig.json 配置
jsxDevjsxDevJS API 中不支持，通过 tsconfig.json 配置
jsxFactoryjsxFactoryJS API 中不支持，通过 tsconfig.json 配置
jsxFragmentjsxFragmentJS API 中不支持，通过 tsconfig.json 配置
jsxImportSourcejsxImportSourceJS API 中不支持，通过 tsconfig.json 配置
jsxSideEffectsjsxSideEffectsJS API 中不支持，通过 tsconfig.json 配置
keepNames不适用不支持
legalComments不适用不支持
loaderloaderBun 支持的内置加载器集合与 esbuild 不同；详见打包器 > 加载器完整参考。esbuild 的 dataurl、binary、base64、copy 和 empty 加载器尚未实现。
logLevel不适用不支持
logLimit不适用不支持
logOverride不适用不支持
mainFields不适用不支持
mangleCache不适用不支持
mangleProps不适用不支持
mangleQuoted不适用不支持
metafile不适用不支持
minifyminify在 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/>
minifyIdentifiersminify.identifiers参见 minify
minifySyntaxminify.syntax参见 minify
minifyWhitespaceminify.whitespace参见 minify
nodePaths不适用不支持
outExtension不适用不支持
outbaseroot名称不同
outdiroutdir无区别
outfileoutfile无区别
packages不适用不支持，请使用 external
platformtarget支持 "bun"、"node" 和 "browser"（默认）。不支持 "neutral"。
pluginspluginsBun 的插件 API 是 esbuild 的子集。一些 esbuild 插件可开箱即用地在 Bun 下工作。
preserveSymlinks不适用不支持
publicPathpublicPath无区别
pure不适用不支持
reserveProps不适用不支持
resolveExtensions不适用不支持
sourceRoot不适用不支持
sourcemapsourcemap支持 "inline"、"external" 和 "none"
sourcesContent不适用不支持
splittingsplitting无区别
stdin不适用不支持
supported不适用不支持
target不适用不支持语法层级降级
treeShaking不适用始终开启
tsconfig不适用不支持
write不适用如果设置了 outdir 或 outfile，则为 true，否则 false

​
插件 API

Bun 的插件 API 设计为与 esbuild 兼容。Bun 尚未支持 esbuild 的全部插件 API，但核心功能已经实现。许多第三方 esbuild 插件可开箱即用地在 Bun 中工作。
长远来看，我们目标是实现与 esbuild API 的功能等价，如果遇到任何不兼容，请提 issue 以协助我们确定优先级。
Bun 和 esbuild 中的插件均通过构造一个 builder 对象定义。
https://mintcdn.com/ikxin/42j8wRmGt8kDDLLK/icons/typescript.svg?fit=max&auto=format&n=42j8wRmGt8kDDLLK&q=85&s=a2a397cd68603d207db5c5b5d620260amyPlugin.ts
import type { BunPlugin } from "bun";

const myPlugin: BunPlugin = {
  name: "my-plugin",
  setup(builder) {
    // 定义插件
  },
};
The builder object provides some methods for hooking into parts of the bundling process. Bun implements onStart, onEnd, onResolve, and onLoad. It does not yet implement the esbuild hooks onDispose and resolve. initialOptions is partially implemented, being read-only and only having a subset of esbuild’s options; use config (same thing but with Bun’s BuildConfig format) instead.
https://mintcdn.com/ikxin/42j8wRmGt8kDDLLK/icons/typescript.svg?fit=max&auto=format&n=42j8wRmGt8kDDLLK&q=85&s=a2a397cd68603d207db5c5b5d620260amyPlugin.ts
import type { BunPlugin } from "bun";
const myPlugin: BunPlugin = {
  name: "my-plugin",
  setup(builder) {
    builder.onStart(() => {
      /* called when the bundle starts */
    });
    builder.onResolve(
      {
        /* onResolve.options */
      },
      args => {
        return {
          /* onResolve.results */
        };
      },
    );
    builder.onLoad(
      {
        /* onLoad.options */
      },
      args => {
        return {
          /* onLoad.results */
        };
      },
    );
    builder.onEnd(result => {
      /* called when the bundle is complete */
    });
  },
};

​
onResolve

  • 🟢 filter
  • 🟢 namespace

​
onLoad

  • 🟢 filter
  • 🟢 namespace