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 倍。

CLI API
Bun 和 esbuild 都提供命令行界面。
esbuild <entrypoint> --outdir=out --bundle
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 禁用此行为。 |
|
| 语法上的小差异;没有冒号。
|
|
| 语法上的小差异;没有冒号。
|
--format | --format | Bun 目前支持 "esm" 和 "cjs" ,但计划支持更多模块格式。esbuild 默认为 "iife" 。 |
|
| Bun 支持一套与 esbuild 不同的内置加载器;有关完整参考,请参阅 Bundler > Loaders。esbuild 加载器
|
--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 中的 naming 保持一致而重命名 |
--banner | --banner | 仅适用于 js 包 |
--footer | --footer | 仅适用于 js 包 |
--certfile | 不适用 | 不适用 |
--charset=utf8 | 不适用 | 不支持 |
--chunk-names | --chunk-naming | 为了与 JS API 中的 naming 保持一致而重命名 |
--color | 不适用 | 始终启用 |
--drop | --drop | |
--entry-names | --entry-naming | 为了与 JS API 中的 naming 保持一致而重命名 |
--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 以确定默认值。如果 compilerOptions.jsx 为 "react-jsx" ,或者 NODE_ENV=production ,Bun 将使用 jsx 转换。否则,它将使用 jsxDEV 。对于任何 to Bun 都使用 jsxDEV 。打包器不支持 preserve 。 |
--jsx-factory | --jsx-factory | |
--jsx-fragment | --jsx-fragment | |
--jsx-import-source | --jsx-import-source | |
--jsx-side-effects | --jsx-side-effects | 控制 JSX 表达式是否被标记为 /* @__PURE__ */ 以进行死代码消除。默认为 false (JSX 被标记为 pure)。 |
--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 尚不支持 stdin 输入。 |
--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 |
|
| 使用与 esbuild 相同的模板语法,但
|
banner | 不适用 | 不支持 |
bundle | 不适用 | 始终为 true 。使用 Bun.Transpiler 进行无打包转译。 |
charset | 不适用 | 不支持 |
|
| 使用与 esbuild 相同的模板语法,但
|
color | 不适用 | Bun 在构建结果的 logs 属性中返回日志。 |
conditions | 不适用 | 不支持。导出条件优先级由 target 确定。 |
define | define | |
drop | 不适用 | 不支持 |
|
| Bun 支持一个
|
entryPoints | entrypoints | 大小写差异 |
external | external | 无差异 |
footer | 不适用 | 不支持 |
format | format | 目前仅支持 "esm" 。计划支持 "cjs" 和 "iife" 。 |
globalName | 不适用 | 不支持 |
ignoreAnnotations | 不适用 | 不支持 |
inject | 不适用 | 不支持 |
jsx | jsx | JS API 中不支持,在 tsconfig.json 中配置 |
jsxDev | jsxDev | JS API 中不支持,在 tsconfig.json 中配置 |
jsxFactory | jsxFactory | JS API 中不支持,在 tsconfig.json 中配置 |
jsxFragment | jsxFragment | JS API 中不支持,在 tsconfig.json 中配置 |
jsxImportSource | jsxImportSource | JS API 中不支持,在 tsconfig.json 中配置 |
jsxSideEffects | jsxSideEffects | 控制 JSX 表达式是否被标记为 pure 以进行死代码消除 |
keepNames | 不适用 | 不支持 |
legalComments | 不适用 | 不支持 |
loader | loader | Bun 支持一套与 esbuild 不同的内置加载器;有关完整参考,请参阅 Bundler > Loaders。esbuild 加载器 dataurl 、binary 、base64 、copy 和 empty 尚未实现。 |
logLevel | 不适用 | 不支持 |
logLimit | 不适用 | 不支持 |
logOverride | 不适用 | 不支持 |
mainFields | 不适用 | 不支持 |
mangleCache | 不适用 | 不支持 |
mangleProps | 不适用 | 不支持 |
mangleQuoted | 不适用 | 不支持 |
metafile | 不适用 | 不支持 |
|
| 在 Bun 中,
|
minifyIdentifiers | minify.identifiers | 参见 minify |
minifySyntax | minify.syntax | 参见 minify |
minifyWhitespace | minify.whitespace | 参见 minify |
nodePaths | 不适用 | 不支持 |
outExtension | 不适用 | 不支持 |
outbase | root | 名称不同 |
outdir | outdir | 无差异 |
outfile | outfile | 无差异 |
packages | 不适用 | 不支持,使用 external |
platform | target | 支持 "bun" 、"node" 和 "browser" (默认)。不支持 "neutral" 。 |
plugins | plugins | Bun 的插件 API 是 esbuild 的一个子集。一些 esbuild 插件可以开箱即用地与 Bun 一起使用。 |
preserveSymlinks | 不适用 | 不支持 |
publicPath | publicPath | 无差异 |
pure | 不适用 | 不支持 |
reserveProps | 不适用 | 不支持 |
resolveExtensions | 不适用 | 不支持 |
sourceRoot | 不适用 | 不支持 |
sourcemap | sourcemap | 支持 "inline" 、"external" 和 "none" |
sourcesContent | 不适用 | 不支持 |
splitting | splitting | 无差异 |
stdin | 不适用 | 不支持 |
supported | 不适用 | 不支持 |
target | 不适用 | 不支持语法降级 |
treeShaking | 不适用 | 始终为 true |
tsconfig | 不适用 | 不支持 |
write | 不适用 | 如果设置了 outdir /outfile ,则设置为 true ,否则为 false |
插件 API
Bun 的插件 API 设计为兼容 esbuild。Bun 不支持 esbuild 的全部插件 API 范围,但核心功能已实现。许多第三方 esbuild
插件可以开箱即用地与 Bun 一起使用。
长远来看,我们的目标是实现与 esbuild API 的功能对等,因此如果有什么不起作用,请提交 issue 以帮助我们确定优先级。
Bun 和 esbuild 中的插件使用 builder
对象定义。
import type { BunPlugin } from "bun";
const myPlugin: BunPlugin = {
name: "my-plugin",
setup(builder) {
// define plugin
},
};
builder
对象提供了一些方法来钩入打包过程的各个部分。Bun 实现 onResolve
和 onLoad
;它尚未实现 esbuild 的钩子 onStart
、onEnd
和 onDispose
,以及 resolve
工具。initialOptions
已部分实现,为只读,并且只有 esbuild 选项的子集;请改用 config
(与 Bun 的 BuildConfig
格式相同,但具有 Bun 的格式)而不是。
import type { BunPlugin } from "bun";
const myPlugin: BunPlugin = {
name: "my-plugin",
setup(builder) {
builder.onResolve(
{
/* onResolve.options */
},
args => {
return {
/* onResolve.results */
};
},
);
builder.onLoad(
{
/* onLoad.options */
},
args => {
return {
/* onLoad.results */
};
},
);
},
};
onResolve
options
🟢 | filter |
---|---|
🟢 | namespace |
arguments
🟢 | path |
---|---|
🟢 | importer |
🔴 | namespace |
🔴 | resolveDir |
🔴 | kind |
🔴 | pluginData |
results
🟢 | namespace |
---|---|
🟢 | path |
🔴 | errors |
🔴 | external |
🔴 | pluginData |
🔴 | pluginName |
🔴 | sideEffects |
🔴 | suffix |
🔴 | warnings |
🔴 | watchDirs |
🔴 | watchFiles |
onLoad
options
🟢 | filter |
🟢 | namespace |
arguments
🟢 | path |
🔴 | namespace |
🔴 | suffix |
🔴 | pluginData |
results
🟢 | contents |
🟢 | loader |
🔴 | errors |
🔴 | pluginData |
🔴 | pluginName |
🔴 | resolveDir |
🔴 | warnings |
🔴 | watchDirs |
🔴 | watchFiles |