esbuild 高性能打包：Go 语言写就的极速构建器

esbuild 高性能打包教程

esbuild 是一个使用 Go 语言编写的 JavaScript 打包器与压缩工具，以极致的构建速度著称。它支持 CommonJS、ES Modules、TypeScript、JSX 等现代前端开发生态，能在毫秒级别完成大多数项目的构建，速度比传统工具快 10-100 倍。

为什么 esbuild 这么快

• Go 语言实现：不同于 Webpack、Rollup 等基于 JavaScript 的工具，esbuild 以原生编译的 Go 编写，充分利用系统资源，规避了 Node.js 单线程与解释执行的开销。
• 极致的并行化：解析、打印、生成 source map 等阶段均使用并行算法，多核 CPU 利用率极高。
• 自研解析器与代码生成器：没有依赖第三方库，所有逻辑从头构建，避免了不必要的抽象层与数据结构转换。
• 零配置内存共享：在打包过程中，各阶段尽可能共享 AST（抽象语法树）引用，减少内存分配与垃圾回收。

安装 esbuild

推荐通过 npm 安装，也可以直接下载平台对应的原生二进制文件。

# npm 全局安装
npm install -g esbuild

# 项目本地安装
npm install --save-dev esbuild

# 验证安装
esbuild --version

本地安装后，可使用 npx esbuild 运行命令，或配置 package.json 中的脚本。

快速开始：第一个打包命令

假设有一个入口文件 app.js：

// app.js
import { greet } from './utils';
console.log(greet('World'));

// utils.js
export const greet = (name) => `Hello, ${name}!`;

使用终端执行以下命令，将其打包成一个可直接在浏览器使用的文件：

esbuild app.js --bundle --outfile=out.js

• --bundle 表示将依赖全部内联到一个文件
• --outfile=out.js 指定输出文件路径

输出结果 out.js 将会是包含所有依赖的立即执行函数（IIFE）格式，可直接在浏览器中引用。

核心概念

• 入口点（Entry point）：打包开始的根文件，esbuild 会从该文件出发解析 import/require 图。
• 打包（Bundle）：是否将图中所有模块合并为一个或少数几个文件。不使用 --bundle 时，esbuild 仅对文件进行语法转换而不处理模块依赖。
• 输出格式（Format）：通过 --format 指定生成代码模块系统，支持 iife（浏览器自执行）、cjs（CommonJS）、esm（ES Module）。
• 目标平台（Platform）：--platform 可设为 browser（默认）、node 或 neutral，影响内置模块解析与打包行为。
• 目标环境（Target）：--target 指定 JavaScript 语言版本或浏览器/Node 环境，例如 es2015、chrome58、node12，esbuild 会自动应用语法降级。

命令行常用选项

esbuild src/index.js \
  --bundle \
  --outfile=dist/bundle.js \
  --minify \
  --sourcemap \
  --target=es2016,chrome58 \
  --platform=browser \
  --format=iife

常用标志说明：

处理多入口

esbuild src/page1.js src/page2.js --bundle --outdir=dist

每个入口会生成对应名称的打包文件，共享重复的代码模块不会被打包多次（未来版本会支持更好的代码拆分）。

JavaScript API 使用

esbuild 提供了同步和异步的 Node.js API，适合在构建脚本中使用。

首先安装依赖后，在 Node 脚本中引入：

const esbuild = require('esbuild');

// 异步打包
esbuild.build({
  entryPoints: ['src/app.js'],
  bundle: true,
  outfile: 'dist/out.js',
  minify: true,
  sourcemap: true,
  platform: 'browser',
  target: ['es2020', 'chrome90'],
  define: {
    'process.env.NODE_ENV': '"production"',
  },
}).catch(() => process.exit(1));

亦支持同步版本 esbuild.buildSync，配置选项与 CLI 参数基本映射。

使用 esbuild 转换 TypeScript 与 JSX

esbuild 内置 TypeScript 和 JSX 支持，无需额外安装插件。它会自动剥离类型注释，不执行类型检查（如需类型检查可并行使用 tsc --noEmit）。

esbuild src/index.tsx --bundle --outfile=dist/bundle.js --loader:.tsx=tsx

对 .tsx 文件，esbuild 默认使用 React 的 JSX 转换。可以通过 --jsx-factory 和 --jsx-fragment 自定义，或使用 --jsx=automatic 启用新的 JSX 运行时。

基础插件系统

esbuild 的插件允许拦截加载路径和文件内容，实现虚拟模块、自定义转换等。插件通过 JavaScript API 注入，无法在 CLI 中直接使用。

一个简单插件示例：将 .txt 文件作为字符串导入。

const esbuild = require('esbuild');

let txtPlugin = {
  name: 'txt',
  setup(build) {
    // 拦截 .txt 路径
    build.onResolve({ filter: /\.txt$/ }, args => ({
      path: args.path,
      namespace: 'txt-ns',
    }));

    // 加载并转换内容
    build.onLoad({ filter: /.*/, namespace: 'txt-ns' }, async (args) => {
      const text = await require('fs').promises.readFile(args.path, 'utf8');
      return {
        contents: `export default ${JSON.stringify(text)}`,
        loader: 'js',
      };
    });
  },
};

esbuild.build({
  entryPoints: ['src/app.js'],
  bundle: true,
  outfile: 'dist/out.js',
  plugins: [txtPlugin],
});

插件系统提供了 onResolve、onLoad、onStart、onEnd 等钩子，可用于实现类似 webpack loader 的功能，但设计更简洁。

实战：构建一个 React 应用

1. 项目结构

react-app/
├── src/
│   ├── index.jsx
│   └── App.jsx
├── package.json
└── build.js

2. 编写组件

src/App.jsx

import React from 'react';

export default function App() {
  return <h1>Hello, esbuild + React!</h1>;
}

src/index.jsx

import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';

ReactDOM.render(<App />, document.getElementById('root'));

3. 构建脚本 build.js

const esbuild = require('esbuild');

esbuild.build({
  entryPoints: ['src/index.jsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  minify: true,
  sourcemap: true,
  target: ['es2016', 'chrome70'],
  platform: 'browser',
  format: 'iife',
  loader: { '.jsx': 'jsx' },
  jsxFactory: 'React.createElement',
  jsxFragment: 'React.Fragment',
  define: {
    'process.env.NODE_ENV': '"production"',
  },
}).catch(() => process.exit(1));

4. 运行构建

node build.js

生成的 dist/bundle.js 即可在 HTML 页面中通过 <script> 引入，配合一个 <div id="root"></div> 即可运行。

代码拆分（Code Splitting）

esbuild 目前对代码拆分的支持仍处于实验阶段（截至当前知识截止日期），但已经可以处理动态 import() 语法，并输出多个 chunk 文件。

esbuild src/index.js --bundle --splitting --outdir=dist --format=esm

--splitting 仅在 format 为 esm 时生效。此时 esbuild 会自动分析共享依赖并将公共模块提取为独立 chunk。因为输出格式必须是 ES Modules，所以需要浏览器或环境原生支持 type="module" 或配套使用预处理器。

CSS 支持

esbuild 对 CSS 有实验性支持，可以将 @import 合并、压缩、生成 source map。

esbuild style.css --bundle --minify --outfile=dist/style.css

也可以在 JavaScript 中导入 CSS 文件（使用 --loader:.css=css），但需注意，默认情况下 CSS 内容将以字符串形式注入，可通过插件将其提取为独立文件。

性能对比概览

基于官方基准测试与社区反馈，esbuild 的构建速度通常是一个数量级的提升。例如：

• 打包一个包含 3000 个模块的大型 TypeScript 项目：esbuild 0.03 秒，Webpack 5 约 30 秒。
• 上述 React 应用的打包：esbuild 完成在 20ms 以内，传统工具则需数百毫秒至数秒。

这种速度优势使得 esbuild 非常适合在开发环节作为底层编译器，例如 Vite 就使用 esbuild 进行预构建与 TypeScript 编译。

常用配置模板

将常用的构建选项抽离为配置文件，方便复用。

build.js：

const esbuild = require('esbuild');

const options = {
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'dist',
  minify: process.env.NODE_ENV === 'production',
  sourcemap: true,
  target: 'es2018',
  platform: 'browser',
  format: 'esm',
};

if (process.argv.includes('--watch')) {
  // 简单 watch 模式示例（esbuild 本身未内建 watch，需社区方案或利用 chokidar）
  const ctx = esbuild.context(options);
  ctx.watch();
  console.log('watching...');
} else {
  esbuild.build(options).catch(() => process.exit(1));
}

总结

esbuild 凭借其 Go 语言内核与高度优化的算法，将打包构建速度推向极致，同时提供了开箱即用的 TypeScript、JSX、ESM 支持。无论是作为独立打包器，还是作为大型工具的底层引擎，都能显著提升开发效率。它的插件系统虽然不如 webpack 丰富，但核心功能已经能覆盖绝大多数构建场景，且学习曲线平缓，适合追求极速反馈的中小型项目或现代化工具链。

对于需要高度定制化、复杂模块处理的项目，可以将 esbuild 作为代码压缩器或与 Rollup/webpack 结合使用，利用其速度优势加速编译环节。

进一步学习可参考 esbuild 官方文档。