esbuild

从esbuild迁移到Bun打包器的指南

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。

esbuild	bun build	注释
--bundle	n/a	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"，但计划支持更多模块格式。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	n/a	不适用
--sourcemap	--sourcemap	没有差异
--splitting	--splitting	没有差异
--target	n/a	不支持。Bun的打包器此时不执行语法降级。
--watch	--watch	没有差异
--allow-overwrite	n/a	永远不允许覆盖
--analyze	n/a	不支持
--asset-names	--asset-naming	为与JS API中的命名一致而重命名
--banner	--banner	仅应用于js包
--footer	--footer	仅应用于js包
--certfile	n/a	不适用
--charset=utf8	n/a	不支持
--chunk-names	--chunk-naming	为与JS API中的命名一致而重命名
--color	n/a	始终启用
--drop	--drop
n/a	--feature	Bun特定。通过import { feature } from "bun:bundle"启用编译时死代码消除的功能标志
--entry-names	--entry-naming	为与JS API中的命名一致而重命名
--global-name	n/a	不适用，Bun此时不支持iife输出
--ignore-annotations	--ignore-dce-annotations
--inject	n/a	不支持
--jsx	--jsx-runtime <runtime>	支持"automatic"（使用jsx转换）和"classic"（使用React.createElement）
--jsx-dev	n/a	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	n/a	JSX始终假定为无副作用
--keep-names	n/a	不支持
--keyfile	n/a	不适用
--legal-comments	n/a	不支持
--log-level	n/a	不支持。这可以在bunfig.toml中设置为logLevel。
--log-limit	n/a	不支持
--log-override:X=Y	n/a	不支持
--main-fields	n/a	不支持
--mangle-cache	n/a	不支持
--mangle-props	n/a	不支持
--mangle-quoted	n/a	不支持
--metafile	n/a	不支持
--minify-whitespace	--minify-whitespace
--minify-identifiers	--minify-identifiers
--minify-syntax	--minify-syntax
--out-extension	n/a	不支持
--outbase	--root
--preserve-symlinks	n/a	不支持
--public-path	--public-path
--pure	n/a	不支持
--reserve-props	n/a	不支持
--resolve-extensions	n/a	不支持
--servedir	n/a	不适用
--source-root	n/a	不支持
--sourcefile	n/a	不支持。Bun还不支持stdin输入。
--sourcemap	--sourcemap	没有差异
--sources-content	n/a	不支持
--supported	n/a	不支持
--tree-shaking	n/a	始终为true
--tsconfig	--tsconfig-override
--version	n/a	运行bun --version查看Bun版本。

JavaScript API

esbuild.build()	Bun.build()	注释
absWorkingDir	n/a	始终设置为process.cwd()
alias	n/a	不支持
allowOverwrite	n/a	始终为false
assetNames	naming.asset	使用与esbuild相同的模板语法，但必须显式包含[ext]。 ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> asset: "[name].[ext]",<br/> },<br/>});<br/>
banner	n/a	不支持
bundle	n/a	始终为true。使用Bun.Transpiler在不打包的情况下转译。
charset	n/a	不支持
chunkNames	naming.chunk	使用与esbuild相同的模板语法，但必须显式包含[ext]。 ts<br/>Bun.build({<br/> entrypoints: ["./index.tsx"],<br/> naming: {<br/> chunk: "[name].[ext]",<br/> },<br/>});<br/>
color	n/a	Bun在构建结果的logs属性中返回日志。
conditions	n/a	不支持。导出条件优先级由target确定。
define	define
drop	n/a	不支持
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	n/a	不支持
format	format	目前仅支持"esm"。计划支持"cjs"和"iife"。
globalName	n/a	不支持
ignoreAnnotations	n/a	不支持
inject	n/a	不支持
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	JS API中不支持，在tsconfig.json中配置
keepNames	n/a	不支持
legalComments	n/a	不支持
loader	loader	Bun支持与esbuild不同的内置加载器集合；请参阅打包器>加载器以获得完整参考。esbuild加载器dataurl、binary、base64、copy和empty尚未实现。
logLevel	n/a	不支持
logLimit	n/a	不支持
logOverride	n/a	不支持
mainFields	n/a	不支持
mangleCache	n/a	不支持
mangleProps	n/a	不支持
mangleQuoted	n/a	不支持
metafile	n/a	不支持
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	n/a	不支持
outExtension	n/a	不支持
outbase	root	不同名称
outdir	outdir	没有差异
outfile	outfile	没有差异
packages	n/a	不支持，使用external
platform	target	支持"bun"、"node"和"browser"（默认）。不支持"neutral"。
plugins	plugins	Bun的插件API是esbuild的一个子集。一些esbuild插件将在Bun中开箱即用。
preserveSymlinks	n/a	不支持
publicPath	publicPath	没有差异
pure	n/a	不支持
reserveProps	n/a	不支持
resolveExtensions	n/a	不支持
sourceRoot	n/a	不支持
sourcemap	sourcemap	支持"inline"、"external"和"none"
sourcesContent	n/a	不支持
splitting	splitting	没有差异
stdin	n/a	不支持
supported	n/a	不支持
target	n/a	不支持语法降级
treeShaking	n/a	始终为true
tsconfig	n/a	不支持
write	n/a	如果设置了outdir/outfile则为true，否则为false

插件API

Bun的插件API设计为与esbuild兼容。Bun不支持esbuild的整个插件API表面，但已实现核心功能。许多第三方esbuild插件将在Bun中开箱即用。

从长远来看，我们的目标是与esbuild的API实现功能对等，所以如果某些功能不起作用，请提交问题以帮助我们确定优先级。

Bun和esbuild中的插件使用构建器对象定义。

myPlugin.ts

import type { BunPlugin } from "bun";

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

构建器对象提供了一些方法，用于挂钩到打包过程的某些部分。Bun实现了onResolve和onLoad；尚未实现esbuild钩子onStart、onEnd和onDispose，以及resolve工具。initialOptions部分实现，只读且仅有esbuild选项的子集；使用config（相同的东西但使用Bun的BuildConfig格式）代替。

myPlugin.ts

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

选项

• 🟢 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