🚀 esbuild 极速打包原理

📑 目录

🚀 esbuild 简介

⚡ 性能对比

🏗️ 核心架构

┌─────────────────────────────────────────────┐
│              esbuild 架构图                  │
├─────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Entry   │→ │ Resolver │→ │  Parser  │   │
│  │  Points  │  │  解析器   │  │  解析器   │   │
│  └──────────┘  └──────────┘  └──────────┘   │
│       ↓              ↓             ↓         │
│  ┌─────────────────────────────────────────┐│
│  │         Bundler (核心打包器)             ││
│  │  • ScanBundle (扫描模块图)               ││
│  │  • parseFile (并行解析)                  ││
│  └─────────────────────────────────────────┘│
│       ↓                                      │
│  ┌─────────────────────────────────────────┐│
│  │         Linker (链接器)                  ││
│  │  • treeShaking (摇树优化)               ││
│  │  • codeSplitting (代码分割)             ││
│  │  • generateChunks (生成代码块)          ││
│  └─────────────────────────────────────────┘│
│       ↓                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ Printer  │→ │ Minifier │→ │  Output  │   │
│  │ 打印器    │  │ 压缩器    │  │  输出    │   │
│  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────┘

🔄 两阶段构建

// bundler.go
func ScanBundle(...) (*Bundle, error)

// linker.go
func Link(...) []OutputFile

🚄 为什么这么快？

📜 架构演进史

🔍 与其他工具对比

🗄️ 核心数据结构

📦 Bundle 结构

// bundler.go - Bundle 是打包的核心结构
type Bundle struct {
    // 唯一键前缀，用于标识每个构建操作
    uniqueKeyPrefix string
    
    // 文件系统接口
    fs          fs.FS
    
    // 模块解析器
    res         *resolver.Resolver
    
    // 所有扫描的文件
    files       []scannerFile
    
    // 入口点列表
    entryPoints []graph.EntryPoint
    
    // 构建选项
    options     config.Options
}

📄 scannerFile 结构

// bundler.go - 扫描文件的内部表示
type scannerFile struct {
    // JSON 元数据块（用于 metafile）
    jsonMetadataChunk string
    
    // 插件数据
    pluginData interface{}
    
    // 输入文件信息
    inputFile  graph.InputFile
}

// graph.InputFile 包含：
// - Source: 源代码信息
// - Loader: 使用的加载器类型
// - Repr: AST 表示 (JS/CSS/Copy)
// - SideEffects: 副作用信息

📋 parseArgs 结构

// bundler.go - 解析参数
type parseArgs struct {
    fs              fs.FS
    log             logger.Log
    res             *resolver.Resolver
    caches          *cache.CacheSet
    
    // 导入源信息
    importSource    *logger.Source
    importWith      *ast.ImportAssertOrWith
    sideEffects     graph.SideEffects
    
    // 结果通道（用于并发）
    results         chan parseResult
    inject          chan config.InjectedFile
    
    // 路径信息
    keyPath         logger.Path
    sourceIndex     uint32
    options         config.Options
}

🔗 linkerContext 结构

// linker.go - 链接器上下文
type linkerContext struct {
    options *config.Options
    timer   *helpers.Timer
    log     logger.Log
    fs      fs.FS
    res     *resolver.Resolver
    
    // 模块图
    graph   graph.LinkerGraph
    
    // 输出代码块
    chunks  []chunkInfo
    
    // 循环检测
    cycleDetector []importTracker
    
    // Source Map 数据（并行计算）
    dataForSourceMaps func() []bundler.DataForSourceMap
    
    // 属性混淆结果
    mangledProps map[ast.Ref]string
    
    // 运行时符号引用
    unboundModuleRef ast.Ref
    cjsRuntimeRef    ast.Ref
    esmRuntimeRef    ast.Ref
}

📦 chunkInfo 结构

// linker.go - 代码块信息
type chunkInfo struct {
    // 唯一键（最终路径确定前使用）
    uniqueKey string
    
    // 包含的文件和部分
    filesWithPartsInChunk map[uint32]bool
    entryBits             helpers.BitSet
    
    // 跨块导入（代码分割）
    crossChunkImports []chunkImport
    
    // 块表示（JS/CSS）
    chunkRepr chunkRepr
    
    // 最终路径模板
    finalTemplate []config.PathTemplate
    finalRelPath  string
    
    // 哈希计算
    waitForIsolatedHash func() []byte
    
    // 入口点信息
    entryPointBit uint
    sourceIndex   uint32
    isEntryPoint  bool
}

⚙️ BuildOptions 配置

// api.go - 构建选项
type BuildOptions struct {
    // 入口点
    EntryPoints         []string
    EntryPointsAdvanced []EntryPoint
    
    // 输出配置
    Outfile     string  // 单文件输出
    Outdir      string  // 目录输出
    Outbase     string  // 路径计算基准
    
    // 格式和平台
    Platform    Platform  // browser/node/neutral
    Format      Format    // iife/cjs/esm
    
    // 优化
    Bundle            bool
    MinifyWhitespace  bool
    MinifyIdentifiers bool
    MinifySyntax      bool
    
    // 代码分割
    Splitting   bool
    
    // Source Map
    Sourcemap   SourceMap
}

📁 Loader 枚举

🔌 Plugin 系统

// api.go - 插件定义
type Plugin struct {
    Name  string
    Setup func(PluginBuild)
}

type PluginBuild struct {
    // 初始选项
    InitialOptions *BuildOptions
    
    // 解析钩子
    Resolve func(path string, opts) ResolveResult
    
    // 生命周期钩子
    OnStart  func(callback)
    OnEnd    func(callback)
    
    // 解析钩子
    OnResolve func(options, callback)
    
    // 加载钩子
    OnLoad    func(options, callback)
    
    // 清理钩子
    OnDispose func(callback)
}

🔧 parseFile 函数

// bundler.go - 解析单个文件
func parseFile(args parseArgs) {
    // 1. 确定文件加载器
    loader := determineLoader(args)
    
    // 2. 运行 OnLoad 插件
    result := runOnLoadPlugins(plugins, ...)
    
    // 3. 根据加载器类型解析
    switch loader {
    case config.LoaderJS, config.LoaderJSX:
        ast := jsParser.Parse(source)
    case config.LoaderTS, config.LoaderTSX:
        ast := tsParser.Parse(source)
    case config.LoaderCSS:
        ast := cssParser.Parse(source)
    case config.LoaderJSON:
        ast := jsonParser.Parse(source)
    }
    
    // 4. 解析导入依赖
    for _, record := range ast.ImportRecords {
        resolveResult := resolver.Resolve(record.Path)
    }
    
    // 5. 发送结果到通道
    args.results <- result
}

🔍 ScanBundle 函数

// bundler.go - 扫描整个模块图
func ScanBundle(...) (*Bundle, error) {
    // 1. 初始化扫描器
    scanner := &scanner{
        results: make([]parseResult, estimateFileCount),
        visited: make(map[logger.Path]visitedFile),
    }
    
    // 2. 从入口点开始扫描
    for _, entryPoint := range entryPoints {
        scanner.addEntry(entryPoint)
    }
    
    // 3. 并行处理队列中的文件
    for scanner.remaining > 0 {
        // 在多个 goroutine 中并行解析
        go parseFile(args)
        
        // 收集结果
        result := <-scanner.resultChannel
        scanner.processResult(result)
    }
    
    // 4. 返回完整的 Bundle
    return &Bundle{files: scanner.files}, nil
}

🔗 Link 函数

// linker.go - 链接阶段入口
func Link(
    options *config.Options,
    inputFiles []graph.InputFile,
    entryPoints []graph.EntryPoint,
) []graph.OutputFile {
    
    // 1. 创建链接上下文
    c := linkerContext{
        options: options,
        graph:   CloneLinkerGraph(inputFiles),
    }
    
    // 2. 扫描导入和导出
    c.scanImportsAndExports()
    
    // 3. Tree Shaking 和代码分割
    c.treeShakingAndCodeSplitting()
    
    // 4. 计算代码块
    c.computeChunks()
    
    // 5. 计算跨块依赖
    c.computeCrossChunkDependencies()
    
    // 6. 属性混淆
    c.mangleProps(mangleCache)
    
    // 7. 并行生成代码块
    return c.generateChunksInParallel()
}

📤 scanImportsAndExports

// linker.go - 扫描导入导出关系
func (c *linkerContext) scanImportsAndExports() {
    for _, sourceIndex := range c.graph.ReachableFiles {
        file := &c.graph.Files[sourceIndex]
        
        switch repr := file.InputFile.Repr.(type) {
        case *graph.JSRepr:
            // 处理 ES 导入
            for _, record := range repr.AST.ImportRecords {
                if record.SourceIndex.IsValid() {
                    // 绑定导入到导出
                    c.bindImport(record)
                }
            }
            
            // 处理 CommonJS
            if repr.AST.ExportsKind == js_ast.ExportsCommonJS {
                c.wrapCommonJS(sourceIndex)
            }
        }
    }
}

🌳 treeShakingAndCodeSplitting

// linker.go - Tree Shaking 和代码分割
func (c *linkerContext) treeShakingAndCodeSplitting() {
    // 1. 标记可达代码
    for _, entryPoint := range c.graph.EntryPoints() {
        c.markReachableCode(entryPoint.SourceIndex)
    }
    
    // 2. 移除未使用的导出
    for _, file := range c.graph.Files {
        repr := file.InputFile.Repr.(*graph.JSRepr)
        for i, part := range repr.AST.Parts {
            if !c.isPartUsed(part) {
                part.IsLive = false  // 标记为死代码
            }
        }
    }
    
    // 3. 代码分割（如果启用）
    if c.options.CodeSplitting {
        c.splitIntoChunks()
    }
}

📦 computeChunks

// linker.go - 计算输出代码块
func (c *linkerContext) computeChunks() {
    // 1. 为每个入口点创建代码块
    for i, entryPoint := range c.graph.EntryPoints() {
        chunk := chunkInfo{
            uniqueKey:    generateUniqueKey(),
            isEntryPoint: true,
            entryPointBit: uint(i),
            sourceIndex:  entryPoint.SourceIndex,
        }
        c.chunks = append(c.chunks, chunk)
    }
    
    // 2. 代码分割：创建共享代码块
    if c.options.CodeSplitting {
        sharedFiles := c.findSharedFiles()
        if len(sharedFiles) > 0 {
            c.createSharedChunk(sharedFiles)
        }
    }
}

⚡ generateChunksInParallel

// linker.go - 并行生成代码块
func (c *linkerContext) generateChunksInParallel() []OutputFile {
    // 1. 使用 WaitGroup 并行生成
    waitGroup := sync.WaitGroup{}
    waitGroup.Add(len(c.chunks))
    
    for chunkIndex := range c.chunks {
        go func(idx int) {
            defer waitGroup.Done()
            
            switch c.chunks[idx].chunkRepr.(type) {
            case *chunkReprJS:
                c.generateChunkJS(idx)
            case *chunkReprCSS:
                c.generateChunkCSS(idx)
            }
        }(chunkIndex)
    }
    
    // 2. 等待所有代码块完成
    waitGroup.Wait()
    
    // 3. 合并结果
    return c.mergeOutputFiles()
}

🔤 mangleProps

// linker.go - 属性名混淆
func (c *linkerContext) mangleProps(cache map[string]interface{}) {
    // 1. 收集所有需要混淆的属性
    mergedProps := make(map[string]ast.Ref)
    for _, sourceIndex := range c.graph.ReachableFiles {
        repr := c.graph.Files[sourceIndex].InputFile.Repr.(*graph.JSRepr)
        for name, ref := range repr.AST.MangledProps {
            mergedProps[name] = ref
        }
    }
    
    // 2. 按使用频率排序
    sorted := sortByUseCount(mergedProps)
    
    // 3. 分配短名称
    minifier := ast.DefaultNameMinifierJS
    for i, symbolCount := range sorted {
        name := minifier.NumberToMinifiedName(i)
        c.mangledProps[symbolCount.Ref] = name
    }
}

🔍 Resolve 流程

// 模块解析流程
1. 检查插件 OnResolve 钩子
   ↓
2. 检查路径别名 (alias)
   ↓
3. 确定路径类型
   ├─ 相对路径 (./ ../)
   ├─ 绝对路径 (/)
   └─ 包路径 (react)
   ↓
4. 查找文件
   ├─ 检查 package.json
   ├─ 尝试扩展名 (.js .ts .jsx .tsx)
   └─ 检查目录 index 文件
   ↓
5. 返回解析结果
   ├─ 路径
   ├─ 是否外部
   └─ 副作用信息

📊 模块图构建

// 模块图数据结构
type LinkerGraph struct {
    // 所有文件
    Files []LinkerFile
    
    // 可达文件索引
    ReachableFiles []uint32
    
    // 入口点
    entryPoints []EntryPoint
    
    // 符号表
    Symbols ast.SymbolMap
    
    // 稳定排序索引
    StableSourceIndices []uint32
}

// LinkerFile 表示链接器中的文件
type LinkerFile struct {
    InputFile     InputFile
    LineColumnTracker *logger.LineColumnTracker
    EntryPointChunkIndex uint32
}

🔀 并行处理策略

// 并行解析
for i := 0; i < numFiles; i++ {
    go parseFile(args)
}
results := collectResults()

// 并行生成
var wg sync.WaitGroup
wg.Add(len(chunks))
for _, chunk := range chunks {
    go generateChunk(chunk)
}
wg.Wait()

🏭 工厂模式

// 解析器工厂
func newParser(loader config.Loader) Parser {
    switch loader {
    case config.LoaderJS:
        return &jsParser{}
    case config.LoaderTS:
        return &tsParser{}
    case config.LoaderCSS:
        return &cssParser{}
    case config.LoaderJSON:
        return &jsonParser{}
    default:
        return ©Loader{}
    }
}

// 打印器工厂
func newPrinter(format config.Format) Printer {
    switch format {
    case config.FormatESModule:
        return &esmPrinter{}
    case config.FormatCommonJS:
        return &cjsPrinter{}
    case config.FormatIIFE:
        return &iifePrinter{}
    }
}

🔍 访问者模式

// AST 访问者接口
type Visitor interface {
    VisitNode(node ast.Node) ast.Node
    VisitStmt(stmt ast.Stmt)
    VisitExpr(expr ast.Expr)
}

// 打印器实现访问者
type Printer struct{}

func (p *Printer) VisitStmt(stmt ast.Stmt) {
    switch s := stmt.Data.(type) {
    case *ast.SImport:
        p.printImport(s)
    case *ast.SExportClause:
        p.printExport(s)
    case *ast.SFunction:
        p.printFunction(s)
    }
}

🔀 并发模式

💾 缓存模式

// 缓存系统
type CacheSet struct {
    // 文件系统缓存
    FSCache *FSCache
    
    // JS 解析缓存
    JSCache *JSCache
    
    // CSS 解析缓存
    CSSCache *CSSCache
    
    // JSON 解析缓存
    JSONCache *JSONCache
}

// FSCache 缓存文件读取
type FSCache struct {
    entries map[string]*fsEntry
    mutex   sync.RWMutex
}

func (c *FSCache) ReadFile(fs fs.FS, path string) (string, error) {
    c.mutex.RLock()
    entry := c.entries[path]
    c.mutex.RUnlock()
    
    if entry != nil {
        return entry.contents, nil
    }
    
    // 读取并缓存
    contents := fs.ReadFile(path)
    c.mutex.Lock()
    c.entries[path] = &fsEntry{contents: contents}
    c.mutex.Unlock()
    
    return contents, nil
}

📐 系统架构 UML

┌──────────────┐     ┌──────────────┐
│   API Layer  │────→│   CLI/JS     │
└──────────────┘     └──────────────┘
        │                    │
        ↓                    ↓
┌─────────────────────────────────────┐
│             Bundler                 │
│  ┌───────────┐  ┌───────────────┐  │
│  │  Scanner  │  │   Resolver    │  │
│  └───────────┘  └───────────────┘  │
│  ┌───────────┐  ┌───────────────┐  │
│  │  Parser   │  │   Cache       │  │
│  └───────────┘  └───────────────┘  │
└─────────────────────────────────────┘
        │
        ↓
┌─────────────────────────────────────┐
│             Linker                  │
│  ┌───────────┐  ┌───────────────┐  │
│  │  Tree     │  │   Chunk       │  │
│  │  Shaker   │  │   Generator   │  │
│  └───────────┘  └───────────────┘  │
│  ┌───────────┐  ┌───────────────┐  │
│  │  Renamer  │  │   Printer     │  │
│  └───────────┘  └───────────────┘  │
└─────────────────────────────────────┘

📊 构建流程图

┌─────────────┐
│   Start     │
└──────┬──────┘
       ↓
┌─────────────┐
│ Parse Opts  │ ← BuildOptions
└──────┬──────┘
       ↓
┌─────────────┐
│ ScanBundle  │ ← 并行扫描模块
│  ├ parseFile│ ← 每个 goroutine
│  ├ resolve  │ ← 解析依赖
│  └ cache    │ ← 缓存 AST
└──────┬──────┘
       ↓
┌─────────────┐
│    Link     │ ← 链接阶段
│  ├ scan     │ ← 扫描导入导出
│  ├ shake    │ ← Tree Shaking
│  ├ split    │ ← 代码分割
│  └ mangle   │ ← 属性混淆
└──────┬──────┘
       ↓
┌─────────────┐
│  Generate   │ ← 并行生成
│  ├ chunks   │ ← 输出块
│  ├ hash     │ ← 文件哈希
│  └ source   │ ← Source Map
└──────┬──────┘
       ↓
┌─────────────┐
│   Output    │ → OutputFile[]
└─────────────┘

🔍 模块解析流程

import { foo } from './utils'

         ↓
┌────────────────────┐
│  OnResolve Plugin  │ ← 插件钩子
└─────────┬──────────┘
          ↓
┌────────────────────┐
│   Alias Mapping    │ ← 路径别名
└─────────┬──────────┘
          ↓
┌────────────────────┐
│   Path Type Check  │ ← 相对/包/绝对
└─────────┬──────────┘
          ↓
┌────────────────────┐
│   File Resolution  │ ← 查找文件
│   ├ try .ts        │
│   ├ try .js        │
│   └ try index.ts   │
└─────────┬──────────┘
          ↓
┌────────────────────┐
│   Package.json     │ ← 浏览/模块
└─────────┬──────────┘
          ↓
┌────────────────────┐
│  ResolveResult     │ → 路径 + 元信息
└────────────────────┘

🔗 链接流程

Link(inputFiles, entryPoints)
        │
        ├─→ CloneLinkerGraph()    // 复制模块图
        │
        ├─→ scanImportsAndExports() // 绑定导入导出
        │       │
        │       ├─→ 处理 ES Module
        │       ├─→ 处理 CommonJS
        │       └─→ 处理外部模块
        │
        ├─→ treeShakingAndCodeSplitting()
        │       │
        │       ├─→ 标记可达代码
        │       ├─→ 移除死代码
        │       └─→ 分割共享代码
        │
        ├─→ computeChunks()       // 计算输出块
        │
        ├─→ computeCrossChunkDependencies() // 跨块依赖
        │
        ├─→ mangleProps()         // 属性混淆
        │
        └─→ generateChunksInParallel() // 并行生成
                │
                └─→ []OutputFile

🖨️ 代码生成流程

generateChunkJS(chunkIndex)
        │
        ├─→ 收集块内文件
        │
        ├─→ 排序文件（拓扑排序）
        │
        ├─→ 生成导入语句
        │       // import { a } from './chunk-abc.js'
        │
        ├─→ 遍历每个文件
        │       │
        │       ├─→ 打印 AST
        │       ├─→ 重命名符号
        │       └─→ 添加 Source Map
        │
        ├─→ 生成导出语句
        │       // export { a, b }
        │
        ├─→ 应用代码转换
        │       ├─→ ES5 降级
        │       └─→ 特性 polyfill
        │
        ├─→ 压缩代码（可选）
        │       ├─→ 移除空白
        │       ├─→ 缩短标识符
        │       └─→ 优化语法
        │
        └─→ 返回字节码

⚡ 性能优化策略

🔀 并行编译详解

// Go runtime 自动利用多核
func parallelParse(files []string) []Result {
    numWorkers := runtime.GOMAXPROCS(0)
    
    // 创建任务队列
    tasks := make(chan string, len(files))
    results := make(chan Result, len(files))
    
    // 启动 worker
    for i := 0; i < numWorkers; i++ {
        go func() {
            for path := range tasks {
                results <- parseFile(path)
            }
        }()
    }
    
    // 分发任务
    for _, file := range files {
        tasks <- file
    }
    close(tasks)
    
    // 收集结果
    var allResults []Result
    for i := 0; i < len(files); i++ {
        allResults = append(allResults, <-results)
    }
    
    return allResults
}

💾 内存管理

📊 基准测试

✅ 使用最佳实践

// 推荐配置
await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  minify: true,
  sourcemap: true,
  target: 'es2020',
  format: 'esm',
  outdir: 'dist',
})

❓ 常见问题

🔗 与其他工具集成

// Vite 配置
// vite.config.js
export default {
  esbuild: {
    jsxFactory: 'h',
    jsxFragment: 'Fragment',
  }
}

// Webpack 集成（esbuild-loader）
module.exports = {
  module: {
    rules: [{
      test: /\.tsx?$/,
      loader: 'esbuild-loader',
      options: {
        loader: 'tsx',
        target: 'es2020'
      }
    }]
  }
}

// Rollup 插件
import esbuild from 'rollup-plugin-esbuild'

export default {
  plugins: [esbuild()]
}

🔧 调试技巧

# 查看 metafile
esbuild src/index.ts --bundle \
  --metafile=meta.json

# 分析结果
esbuild-visualizer \
  meta.json

# 详细日志
esbuild ... --log-level=debug

const result = await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  metafile: true,
  write: false,
})

// 分析输出
console.log(result.metafile)

// 检查警告
result.warnings.forEach(w => 
  console.log(w))

⚔️ 打包器对比总结

🔮 未来发展趋势

⚡ Go vs JavaScript

📚 总结与扩展阅读

📖 API 速查

// 基础构建 API
import * as esbuild from 'esbuild'

// 一次性构建
await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
})

// Transform API
const result = await esbuild.transform(code, {
  loader: 'tsx',
  target: 'es2020',
})

// Context API（支持 watch/serve）
const ctx = await esbuild.context({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'dist',
})

// 启用 watch 模式
await ctx.watch()

// 启用 serve 模式
const { host, port } = await ctx.serve({
  port: 3000,
  servedir: 'dist',
})