esbuild 极速打包工具配置指南：JavaScript/TypeScript 构建专家教程

esbuild-bundler by mindrally/skills

133 周安装量

55 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/mindrally/skills --skill esbuild-bundler

TypeScript JavaScript 框架工程/构建系统

🇨🇳中文介绍

esbuild 打包工具

您是一位精通 esbuild 的专家，esbuild 是一款用 Go 语言编写的极速 JavaScript 和 TypeScript 打包工具。在处理 esbuild 配置时，请遵循以下指南。

核心原则

esbuild 的速度比传统打包工具快 10-100 倍
大多数用例无需配置
原生支持 TypeScript 和 JSX，无需额外设置
在保持代码质量的同时专注于速度
使用 Go 语言编写以获得原生性能

项目结构

project/
├── src/
│   ├── index.ts          # 主入口点
│   ├── components/       # UI 组件
│   └── utils/            # 工具函数
├── dist/                 # 构建输出目录
├── esbuild.config.mjs    # 构建脚本（可选）
├── tsconfig.json         # TypeScript 配置
└── package.json

基本用法

命令行

# 基本打包
esbuild src/index.ts --bundle --outfile=dist/bundle.js

# 生产环境构建
esbuild src/index.ts --bundle --minify --sourcemap --outfile=dist/bundle.js

# 监听模式
esbuild src/index.ts --bundle --watch --outfile=dist/bundle.js

JavaScript API

import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  sourcemap: true,
  outfile: 'dist/bundle.js'
});

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

tsconfig.json 最佳实践

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "esModuleInterop": true,
    "isolatedModules": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "verbatimModuleSyntax": true,
    "noUncheckedIndexedAccess": true
  },
  "include": ["src/**/*"]
}

重要的 TypeScript 设置

isolatedModules: true - esbuild 兼容性所必需
esModuleInterop: true - 更好的 ESM 兼容性
noEmit: true - 让 esbuild 处理输出，仅使用 tsc 进行类型检查

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: ['chrome90', 'firefox88', 'safari14', 'edge90'],
  outfile: 'dist/bundle.js'
});

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  platform: 'node',
  target: 'node18',
  format: 'esm',
  outfile: 'dist/index.js'
});

await esbuild.build({
  entryPoints: ['src/index.ts', 'src/worker.ts'],
  bundle: true,
  outdir: 'dist',
  splitting: true,
  format: 'esm'
});

await esbuild.build({
  format: 'esm',
  // 输出：import/export 语法
});

await esbuild.build({
  format: 'cjs',
  // 输出：require/module.exports
});

IIFE（浏览器脚本）

await esbuild.build({
  format: 'iife',
  globalName: 'MyApp',
  // 输出：自执行函数
});

await esbuild.build({
  loader: {
    '.png': 'file',
    '.svg': 'text',
    '.json': 'json',
    '.woff': 'dataurl'
  }
});

js - JavaScript
ts - TypeScript
jsx - 带 JSX 的 JavaScript
tsx - 带 JSX 的 TypeScript
json - JSON 数据
text - 纯文本
file - 复制文件，返回路径
dataurl - 内联为 data URL
binary - 内联为 Uint8Array
base64 - 内联为 base64
copy - 复制文件，无引用

标记为外部依赖

await esbuild.build({
  external: ['react', 'react-dom', 'lodash']
});

await esbuild.build({
  external: ['*.png', '@aws-sdk/*']
});

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  splitting: true,
  format: 'esm',
  outdir: 'dist'
});

注意：代码分割需要 format: 'esm' 和 outdir（而不是 outfile）。

const myPlugin = {
  name: 'my-plugin',
  setup(build) {
    // On resolve - 拦截导入路径
    build.onResolve({ filter: /^env$/ }, args => ({
      path: args.path,
      namespace: 'env-ns'
    }));

    // On load - 提供模块内容
    build.onLoad({ filter: /.*/, namespace: 'env-ns' }, () => ({
      contents: JSON.stringify(process.env),
      loader: 'json'
    }));
  }
};

await esbuild.build({
  plugins: [myPlugin]
});

import esbuildPluginTsc from 'esbuild-plugin-tsc';

await esbuild.build({
  plugins: [
    esbuildPluginTsc({
      force: true
    })
  ]
});

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

await ctx.serve({
  servedir: 'dist',
  port: 3000
});

const ctx = await esbuild.context({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js'
});

await ctx.watch();
console.log('正在监听更改...');

await esbuild.build({
  define: {
    'process.env.NODE_ENV': '"production"',
    'process.env.API_URL': JSON.stringify(process.env.API_URL)
  }
});

await esbuild.build({
  minify: true,
  // 或进行细粒度控制：
  minifyWhitespace: true,
  minifyIdentifiers: true,
  minifySyntax: true
});

await esbuild.build({
  treeShaking: true,
  // 将文件标记为无副作用
  ignoreAnnotations: false
});

移除 Console 和 Debugger

await esbuild.build({
  drop: ['console', 'debugger']
});

esbuild 不执行类型检查。请单独运行 TypeScript：

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "build": "npm run typecheck && node esbuild.config.mjs",
    "dev": "concurrently \"tsc --noEmit --watch\" \"node esbuild.config.mjs --watch\""
  }
}

// esbuild.config.mjs
import * as esbuild from 'esbuild';

const isProduction = process.env.NODE_ENV === 'production';
const isWatch = process.argv.includes('--watch');

const config = {
  entryPoints: ['src/index.ts'],
  bundle: true,
  platform: 'browser',
  target: ['es2020'],
  format: 'esm',
  outdir: 'dist',
  sourcemap: !isProduction,
  minify: isProduction,
  splitting: true,
  define: {
    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development')
  }
};

if (isWatch) {
  const ctx = await esbuild.context(config);
  await ctx.watch();
  console.log('正在监听更改...');
} else {
  await esbuild.build(config);
  console.log('构建完成！');
}

在 TypeScript 配置中使用 isolatedModules: true
使用 tsc --noEmit 单独运行类型检查
在监听模式中使用 context API
利用原生的 TypeScript 和 JSX 支持
在库中使用 external 处理 peer dependencies

依赖 esbuild 进行类型检查
使用需要类型信息的功能（带元数据的装饰器）
忽略 isolatedModules 要求
在默认配置可用时过度配置

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  external: ['react', 'react-dom'],
  format: 'esm',
  outfile: 'dist/index.js',
  sourcemap: true
});

await esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  splitting: true,
  format: 'esm',
  outdir: 'dist',
  minify: true,
  sourcemap: true,
  target: ['chrome90', 'firefox88', 'safari14']
});

esbuild 会自动并行化工作
内置文件系统缓存
在开发中使用增量构建
避免使用会减慢构建速度的不必要插件

🇺🇸English

esbuild Bundler

You are an expert in esbuild, the extremely fast JavaScript and TypeScript bundler written in Go. Follow these guidelines when working with esbuild configurations.

Core Principles

esbuild is 10-100x faster than traditional bundlers
Zero configuration needed for most use cases
Native TypeScript and JSX support without additional setup
Focus on speed while maintaining code quality
Written in Go for native performance

Project Structure

project/
├── src/
│   ├── index.ts          # Main entry point
│   ├── components/       # UI components
│   └── utils/            # Utility functions
├── dist/                 # Build output
├── esbuild.config.mjs    # Build script (optional)
├── tsconfig.json         # TypeScript config
└── package.json

Basic Usage

Command Line

# Basic bundle
esbuild src/index.ts --bundle --outfile=dist/bundle.js

# Production build
esbuild src/index.ts --bundle --minify --sourcemap --outfile=dist/bundle.js

# Watch mode
esbuild src/index.ts --bundle --watch --outfile=dist/bundle.js

JavaScript API

import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  sourcemap: true,
  outfile: 'dist/bundle.js'
});

TypeScript Configuration

tsconfig.json Best Practices

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "esModuleInterop": true,
    "isolatedModules": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "verbatimModuleSyntax": true,
    "noUncheckedIndexedAccess": true
  },
  "include": ["src/**/*"]
}

Important TypeScript Settings

isolatedModules: true - Required for esbuild compatibility
esModuleInterop: true - Better ESM compatibility
noEmit: true - Let esbuild handle output, use tsc for type checking only

Build Configuration

Browser Build

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: ['chrome90', 'firefox88', 'safari14', 'edge90'],
  outfile: 'dist/bundle.js'
});

Node.js Build

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  platform: 'node',
  target: 'node18',
  format: 'esm',
  outfile: 'dist/index.js'
});

Multiple Entry Points

await esbuild.build({
  entryPoints: ['src/index.ts', 'src/worker.ts'],
  bundle: true,
  outdir: 'dist',
  splitting: true,
  format: 'esm'
});

Output Formats

ESM (ES Modules)

await esbuild.build({
  format: 'esm',
  // Outputs: import/export syntax
});

CommonJS

await esbuild.build({
  format: 'cjs',
  // Outputs: require/module.exports
});

IIFE (Browser Scripts)

await esbuild.build({
  format: 'iife',
  globalName: 'MyApp',
  // Outputs: self-executing function
});

Loaders

Built-in Loaders

await esbuild.build({
  loader: {
    '.png': 'file',
    '.svg': 'text',
    '.json': 'json',
    '.woff': 'dataurl'
  }
});

Loader Types

js - JavaScript
ts - TypeScript
jsx - JavaScript with JSX
tsx - TypeScript with JSX
json - JSON data
text - Plain text
file - Copy file, return path
dataurl - Inline as data URL
binary - Inline as Uint8Array
base64 - Inline as base64

External Dependencies

Mark as External

await esbuild.build({
  external: ['react', 'react-dom', 'lodash']
});

External Patterns

await esbuild.build({
  external: ['*.png', '@aws-sdk/*']
});

Code Splitting

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  splitting: true,
  format: 'esm',
  outdir: 'dist'
});

Note: Code splitting requires format: 'esm' and outdir (not outfile).

Plugins

Plugin Structure

const myPlugin = {
  name: 'my-plugin',
  setup(build) {
    // On resolve - intercept import paths
    build.onResolve({ filter: /^env$/ }, args => ({
      path: args.path,
      namespace: 'env-ns'
    }));

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

await esbuild.build({
  plugins: [myPlugin]
});

Common Plugins

import esbuildPluginTsc from 'esbuild-plugin-tsc';

await esbuild.build({
  plugins: [
    esbuildPluginTsc({
      force: true
    })
  ]
});

Development Server

Serve API

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

await ctx.serve({
  servedir: 'dist',
  port: 3000
});

Watch Mode

const ctx = await esbuild.context({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js'
});

await ctx.watch();
console.log('Watching for changes...');

Environment Variables

Define API

await esbuild.build({
  define: {
    'process.env.NODE_ENV': '"production"',
    'process.env.API_URL': JSON.stringify(process.env.API_URL)
  }
});

Optimization

Minification

await esbuild.build({
  minify: true,
  // Or granular control:
  minifyWhitespace: true,
  minifyIdentifiers: true,
  minifySyntax: true
});

Tree Shaking

await esbuild.build({
  treeShaking: true,
  // Mark files as side-effect free
  ignoreAnnotations: false
});

Drop Console and Debugger

await esbuild.build({
  drop: ['console', 'debugger']
});

Type Checking

esbuild does not perform type checking. Run TypeScript separately:

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "build": "npm run typecheck && node esbuild.config.mjs",
    "dev": "concurrently \"tsc --noEmit --watch\" \"node esbuild.config.mjs --watch\""
  }
}

Build Script Example

// esbuild.config.mjs
import * as esbuild from 'esbuild';

const isProduction = process.env.NODE_ENV === 'production';
const isWatch = process.argv.includes('--watch');

const config = {
  entryPoints: ['src/index.ts'],
  bundle: true,
  platform: 'browser',
  target: ['es2020'],
  format: 'esm',
  outdir: 'dist',
  sourcemap: !isProduction,
  minify: isProduction,
  splitting: true,
  define: {
    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development')
  }
};

if (isWatch) {
  const ctx = await esbuild.context(config);
  await ctx.watch();
  console.log('Watching for changes...');
} else {
  await esbuild.build(config);
  console.log('Build complete!');
}

Best Practices

Do

Use isolatedModules: true in TypeScript config
Run type checking separately with tsc --noEmit
Use the context API for watch mode
Leverage native TypeScript and JSX support
Use external for peer dependencies in libraries

Avoid

Relying on esbuild for type checking
Using features that require type information (decorators with metadata)
Ignoring the isolatedModules requirement
Over-configuring when defaults work

Common Patterns

Library Build

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  external: ['react', 'react-dom'],
  format: 'esm',
  outfile: 'dist/index.js',
  sourcemap: true
});

Application Build

await esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  splitting: true,
  format: 'esm',
  outdir: 'dist',
  minify: true,
  sourcemap: true,
  target: ['chrome90', 'firefox88', 'safari14']
});

Performance Tips

esbuild parallelizes work automatically
File system caching is built-in
Use incremental builds in development
Avoid unnecessary plugins that slow builds

Weekly Installs

101

Repository

mindrally/skills

GitHub Stars

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode83

gemini-cli81

codex77

claude-code77

cursor76

github-copilot73

Genkit JS 开发指南：AI 应用构建、错误排查与最佳实践

7,700 周安装

copy - Copy file, no reference

esbuild 极速打包工具配置指南：JavaScript/TypeScript 构建专家教程

🇨🇳中文介绍

esbuild 打包工具

核心原则

项目结构

基本用法

命令行

JavaScript API

相关 Skills

TypeScript 配置

tsconfig.json 最佳实践

重要的 TypeScript 设置

构建配置

浏览器构建

Node.js 构建

多入口点

输出格式

ESM（ES 模块）

CommonJS

IIFE（浏览器脚本）

加载器

内置加载器

加载器类型

外部依赖

标记为外部依赖

外部依赖模式

代码分割

插件

插件结构

常用插件

开发服务器

Serve API

监听模式

环境变量

Define API

优化

代码压缩

摇树优化

移除 Console 和 Debugger

类型检查

构建脚本示例

最佳实践

建议

避免

常用模式

库构建

应用构建

性能提示

🇺🇸English

esbuild Bundler

Core Principles

Project Structure

Basic Usage

Command Line

JavaScript API

TypeScript Configuration

tsconfig.json Best Practices

Important TypeScript Settings

Build Configuration

Browser Build

Node.js Build

Multiple Entry Points

Output Formats

ESM (ES Modules)

CommonJS

IIFE (Browser Scripts)

Loaders

Built-in Loaders

Loader Types

External Dependencies

Mark as External

External Patterns

Code Splitting

Plugins

Plugin Structure

Common Plugins

Development Server

Serve API

Watch Mode

Environment Variables