esbuild - 用 Go 写的极速打包器

esbuild 是 Evan Wallace（Figma 的联合创始人）用 Go 语言写的 JavaScript/TypeScript 打包器。它的速度快到什么程度？官方给的数据是比 Webpack 快 10-100 倍。

这个数字不是吹的。在一个中等规模的项目里，Webpack 需要 30 秒完成的构建，esbuild 可能 300 毫秒就搞定了。Vite 的开发服务器之所以启动飞快，底层就是用 esbuild 做依赖预构建。

为什么这么快

esbuild 快的原因不是什么黑魔法，而是做对了几件事：

用 Go 而不是 JavaScript

JavaScript 是单线程的，虽然有 Worker，但进程间通信开销大。Go 天生支持并发，可以充分利用多核 CPU。esbuild 的解析、转换、代码生成都是并行执行的。

从零开始写，没有历史包袱

Webpack 的架构是十年前设计的，为了兼容各种场景，代码路径非常复杂。esbuild 没有这些负担，可以针对现代 JavaScript 生态做极致优化。

尽量少做 AST 遍历

传统打包器的流程是：解析代码生成 AST → 各种插件遍历 AST 做转换 → 生成代码。每个插件都要遍历一遍，效率很低。

esbuild 把常用的转换（TypeScript、JSX、压缩等）全部内置，一次遍历搞定所有事情。

内存布局优化

esbuild 对内存的使用非常克制，数据结构紧凑，GC 压力小。这在处理大型项目时效果明显。

安装与基本使用

# 安装
npm install esbuild --save-dev

# 或者全局安装
npm install -g esbuild

最简单的用法，打包一个文件：

# 打包 app.js，输出到 out.js
esbuild app.js --bundle --outfile=out.js

常用的命令行参数：

# 开启压缩
esbuild app.js --bundle --minify --outfile=out.js

# 生成 source map
esbuild app.js --bundle --sourcemap --outfile=out.js

# 指定目标环境
esbuild app.js --bundle --target=es2020 --outfile=out.js

# 指定输出格式（esm/cjs/iife）
esbuild app.js --bundle --format=esm --outfile=out.js

# 处理 JSX
esbuild app.jsx --bundle --loader:.jsx=jsx --outfile=out.js

JavaScript API

命令行适合简单场景，复杂项目还是用 API 更灵活。

同步构建

const esbuild = require('esbuild')

const result = esbuild.buildSync({
  entryPoints: ['src/index.js'],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: ['es2020'],
  outfile: 'dist/bundle.js',
})

console.log('构建完成')

异步构建

const esbuild = require('esbuild')

async function build() {
  const result = await esbuild.build({
    entryPoints: ['src/index.js'],
    bundle: true,
    minify: true,
    sourcemap: true,
    outdir: 'dist',
    splitting: true, // 代码分割，需要 format: 'esm'
    format: 'esm',
  })

  console.log('构建完成', result)
}

build()

监听模式

const esbuild = require('esbuild')

async function watch() {
  const ctx = await esbuild.context({
    entryPoints: ['src/index.js'],
    bundle: true,
    outdir: 'dist',
  })

  // 开启监听
  await ctx.watch()
  console.log('监听文件变化中...')

  // 需要停止时调用
  // await ctx.dispose()
}

watch()

开发服务器

esbuild 内置了一个简单的开发服务器：

const esbuild = require('esbuild')

async function serve() {
  const ctx = await esbuild.context({
    entryPoints: ['src/index.js'],
    bundle: true,
    outdir: 'public',
  })

  const { host, port } = await ctx.serve({
    servedir: 'public',
    port: 3000,
  })

  console.log(`服务器运行在 http://${host}:${port}`)
}

serve()

这个服务器比较简陋，没有 HMR，只有 Live Reload。生产项目建议用 Vite。

常用配置项详解

entryPoints - 入口文件

// 单入口
entryPoints: ['src/index.js']

// 多入口
entryPoints: ['src/index.js', 'src/admin.js']

// 指定输出名称
entryPoints: {
  main: 'src/index.js',
  admin: 'src/admin.js',
}

loader - 文件类型处理

esbuild 通过 loader 来处理不同类型的文件：

{
  loader: {
    '.js': 'jsx',      // 把 .js 文件当作 JSX 处理
    '.png': 'file',    // 图片输出为文件
    '.svg': 'text',    // SVG 作为文本导入
    '.json': 'json',   // JSON 文件
    '.css': 'css',     // CSS 文件
  }
}

内置的 loader 类型：

Loader	说明
js	JavaScript
jsx	JSX
ts	TypeScript
tsx	TypeScript + JSX
json	JSON 文件
css	CSS 文件
text	作为字符串导入
file	输出为文件，返回 URL
dataurl	转为 Data URL
binary	作为 Uint8Array 导入
base64	作为 Base64 字符串导入
copy	复制文件，不做处理

define - 全局常量替换

{
  define: {
    'process.env.NODE_ENV': '"production"',
    '__DEV__': 'false',
    'API_URL': '"https://api.example.com"',
  }
}

注意值需要是 JavaScript 表达式的字符串形式，所以字符串要用引号包裹。

external - 排除依赖

{
  external: [
    'react',
    'react-dom',
    // 排除所有 node_modules
    './node_modules/*',
  ]
}

被排除的依赖不会被打包，而是保留 import/require 语句。

alias - 路径别名

{
  alias: {
    '@': './src',
    '@components': './src/components',
    '@utils': './src/utils',
  }
}

target - 目标环境

// 指定 ES 版本
target: ['es2020']

// 指定浏览器版本
target: ['chrome80', 'firefox78', 'safari14']

// 指定 Node 版本
target: ['node16']

esbuild 会根据目标环境自动转换语法，比如把箭头函数转成普通函数。

代码分割

{
  entryPoints: ['src/index.js', 'src/admin.js'],
  bundle: true,
  splitting: true,    // 开启代码分割
  format: 'esm',      // 必须是 esm 格式
  outdir: 'dist',     // 必须用 outdir，不能用 outfile
  chunkNames: 'chunks/[name]-[hash]',  // 分割出的 chunk 命名规则
}

插件开发

esbuild 的插件 API 相对简单，主要是两个钩子：onResolve 和 onLoad。

基本结构

const myPlugin = {
  name: 'my-plugin',
  setup(build) {
    // 解析模块路径时触发
    build.onResolve({ filter: /.*/ }, (args) => {
      console.log('解析:', args.path)
      return null // 返回 null 表示不处理
    })

    // 加载模块内容时触发
    build.onLoad({ filter: /.*/ }, (args) => {
      console.log('加载:', args.path)
      return null
    })
  },
}

// 使用插件
esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  plugins: [myPlugin],
  outfile: 'dist/bundle.js',
})

实战：处理 YAML 文件

const yaml = require('js-yaml')
const fs = require('fs')

const yamlPlugin = {
  name: 'yaml',
  setup(build) {
    build.onLoad({ filter: /\.ya?ml$/ }, async (args) => {
      const content = await fs.promises.readFile(args.path, 'utf8')
      const data = yaml.load(content)

      return {
        contents: `export default ${JSON.stringify(data)}`,
        loader: 'js',
      }
    })
  },
}

实战：环境变量注入

const envPlugin = {
  name: 'env',
  setup(build) {
    build.onResolve({ filter: /^env$/ }, (args) => ({
      path: args.path,
      namespace: 'env-ns',
    }))

    build.onLoad({ filter: /.*/, namespace: 'env-ns' }, () => ({
      contents: JSON.stringify(process.env),
      loader: 'json',
    }))
  },
}

// 使用
// import env from 'env'
// console.log(env.NODE_ENV)

实战：Vue SFC 简易处理

const vuePlugin = {
  name: 'vue',
  setup(build) {
    build.onLoad({ filter: /\.vue$/ }, async (args) => {
      const source = await fs.promises.readFile(args.path, 'utf8')

      // 简单解析，实际需要用 @vue/compiler-sfc
      const templateMatch = source.match(/<template>([\s\S]*)<\/template>/)
      const scriptMatch = source.match(/<script>([\s\S]*)<\/script>/)

      const template = templateMatch ? templateMatch[1] : ''
      const script = scriptMatch ? scriptMatch[1] : 'export default {}'

      // 这只是示例，实际要复杂得多
      const code = `
        ${script.replace('export default', 'const __component__ =')}
        __component__.template = \`${template}\`
        export default __component__
      `

      return { contents: code, loader: 'js' }
    })
  },
}

与 TypeScript 配合

esbuild 原生支持 TypeScript，但有些细节要注意。

tsconfig.json 支持

esbuild 只读取部分 tsconfig 选项：

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "jsx": "react-jsx",
    "jsxImportSource": "react",
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

esbuild 会识别 jsx、jsxFactory、jsxFragmentFactory、useDefineForClassFields、importsNotUsedAsValues 等选项。

但 paths 别名需要通过 esbuild 的 alias 配置，或者用 esbuild-plugin-alias 插件。

类型检查

esbuild 不做类型检查，它只是把 TypeScript 语法剥掉。类型检查需要单独跑 tsc --noEmit：

{
  "scripts": {
    "build": "npm run typecheck && esbuild src/index.ts --bundle --outfile=dist/bundle.js",
    "typecheck": "tsc --noEmit"
  }
}

装饰器

esbuild 不支持旧版装饰器语法（TypeScript 的 experimentalDecorators）。如果项目用了装饰器（比如 NestJS），需要用 SWC 或 Babel 先转换一遍。

与 React 配合

JSX 配置

{
  loader: { '.js': 'jsx', '.ts': 'tsx' },
  jsx: 'automatic',  // 使用新版 JSX 转换，不需要手动 import React
  jsxDev: process.env.NODE_ENV === 'development',  // 开发模式添加调试信息
}

如果用的是老项目：

{
  jsx: 'transform',
  jsxFactory: 'React.createElement',
  jsxFragment: 'React.Fragment',
}

完整的 React 项目配置

const esbuild = require('esbuild')
const { copy } = require('esbuild-plugin-copy')

const isDev = process.env.NODE_ENV === 'development'

async function build() {
  const ctx = await esbuild.context({
    entryPoints: ['src/index.tsx'],
    bundle: true,
    minify: !isDev,
    sourcemap: isDev,
    target: ['es2020'],
    format: 'esm',
    splitting: true,
    outdir: 'dist',
    jsx: 'automatic',
    define: {
      'process.env.NODE_ENV': JSON.stringify(
        process.env.NODE_ENV || 'development'
      ),
    },
    plugins: [
      copy({
        assets: [{ from: './public/*', to: './' }],
      }),
    ],
  })

  if (isDev) {
    await ctx.watch()
    const { port } = await ctx.serve({ servedir: 'dist', port: 3000 })
    console.log(`开发服务器: http://localhost:${port}`)
  } else {
    await ctx.rebuild()
    await ctx.dispose()
    console.log('构建完成')
  }
}

build()

性能优化技巧

减少入口点

每个入口点都会触发一次完整的依赖分析。如果可能，把多个入口合并：

// 不太好
entryPoints: ['page1.js', 'page2.js', 'page3.js', ...]

// 如果它们共享很多依赖，考虑用动态导入
entryPoints: ['main.js']
// main.js 里动态导入各个页面

排除大型依赖

像 lodash、moment 这种体积大的库，可以用 CDN 引入：

{
  external: ['lodash', 'moment'],
  // 然后在 HTML 里用 script 标签引入 CDN
}

使用增量构建

开发时用 context API 和 watch，esbuild 会缓存中间结果：

const ctx = await esbuild.context(options)
await ctx.watch()
// 后续的重新构建会很快

并行处理多个构建

如果有多个独立的构建任务，可以并行执行：

await Promise.all([
  esbuild.build({ entryPoints: ['client.js'], outfile: 'dist/client.js' }),
  esbuild.build({
    entryPoints: ['server.js'],
    outfile: 'dist/server.js',
    platform: 'node',
  }),
  esbuild.build({ entryPoints: ['worker.js'], outfile: 'dist/worker.js' }),
])

当前限制

esbuild 追求速度，牺牲了一些功能：

不支持的特性

HMR（热模块替换）：只有 Live Reload，没有状态保持的 HMR
旧版装饰器：不支持 TypeScript 的 experimentalDecorators
CSS Modules 的 ：部分语法不支持
某些 Babel 插件的功能：比如 macros

插件生态

相比 Webpack 的海量插件，esbuild 的插件生态还在发展中。常用的都有，但冷门需求可能要自己写。

生产环境使用

esbuild 可以用于生产，但很多团队选择：

开发环境用 esbuild（或 Vite）
生产环境用 Rollup（更成熟的 tree shaking 和代码分割）

与其他工具对比

对比项	esbuild	Webpack	Rollup	Vite
语言	Go	JavaScript	JavaScript	JavaScript
构建速度	极快	慢	中等	快（用 esbuild）
HMR	无	有	需插件	有
插件生态	发展中	非常丰富	丰富	丰富
配置复杂度	简单	复杂	中等	简单
适用场景	库、简单应用	复杂应用	库	现代应用

常见问题

1. 构建后引入路径错误

检查 publicPath 配置：

{
  publicPath: '/assets/',
}

2. 第三方库报错

有些库没有正确的 ESM 导出，用 mainFields 调整：

{
  mainFields: ['module', 'main'],
  conditions: ['import', 'module'],
}

3. 动态 import 不工作

确保用了 splitting: true 和 format: 'esm'：

{
  splitting: true,
  format: 'esm',
  outdir: 'dist',  // 必须用 outdir
}

4. Node.js 内置模块报错

打包给浏览器用时，需要排除或 polyfill Node 模块：

{
  platform: 'browser',
  external: ['fs', 'path', 'crypto'],
}

参考资料