依赖预构建(Dependency Pre-Bundling)原理

依赖预构建(Dependency Pre-Bundling)原理

Vite.js 在开发模式下利用浏览器原生 ES 模块支持，直接按需提供源码文件。但裸模块导入（如 import vue from 'vue'）会导致浏览器大量请求瀑布流，依赖预构建通过将 CommonJS/UMD 依赖转换为 ESM 格式并合并为单个文件来解决这个问题。

预构建触发机制

预构建在以下场景自动触发：

1. 首次启动开发服务器时
2. node_modules 依赖发生变化时
3. 手动删除 node_modules/.vite 缓存目录时

// vite.config.js
export default {
  optimizeDeps: {
    // 强制预构建的依赖项
    include: ['lodash-es'],
    // 排除预构建的依赖项
    exclude: ['moment'],
    // 禁用预构建
    disabled: false
  }
}

预构建核心流程

1. 依赖扫描：通过静态分析找出所有裸模块导入

   • 使用 esbuild 扫描器快速解析 import 语句
   • 递归分析入口文件的所有依赖

2. 依赖打包：

   • 将每个依赖及其深层依赖打包为单个 ESM 文件
   • 处理特殊格式转换（CommonJS → ESM）
   • 应用最小化优化（minify）

3. 缓存处理：

   • 生成内容哈希作为缓存标识
   • 将结果存储在 node_modules/.vite 目录
   • 下次启动时复用已有缓存

技术实现细节

依赖图构建算法

interface DepInfo {
  id: string
  imports: Set<string>
  // 其他元数据...
}

function scanImports(filePath: string): DepInfo {
  // 使用 esbuild 的解析能力
  const result = esbuild.buildSync({
    entryPoints: [filePath],
    bundle: true,
    write: false,
    metafile: true
  })
  
  return {
    id: filePath,
    imports: extractImports(result.metafile)
  }
}

模块格式转换

处理 CommonJS 模块的典型转换示例：

// 转换前 (CommonJS)
const _ = require('lodash')
module.exports = _.cloneDeep

// 转换后 (ESM)
import * as _ from 'lodash'
export default _.cloneDeep

缓存失效策略

Vite 使用多层缓存校验：

1. package.json 的 dependencies 字段哈希
2. 锁文件（package-lock.json/yarn.lock）内容哈希
3. 配置文件中的 optimizeDeps 配置哈希

性能优化手段

1. 并行处理：使用 worker 线程并行处理多个依赖
2. 增量构建：仅重新构建变更的依赖
3. 智能缓存：基于文件内容哈希的持久化缓存

// 多线程处理示例
const worker = new Worker('./pre-bundle-worker.js')
worker.postMessage({
  dep: 'vue',
  version: '3.2.0'
})

特殊场景处理

循环依赖解决方案

// a.js
import { b } from './b'
export const a = b + 1

// b.js
import { a } from './a'
export const b = a || 0

// 预构建后会生成：
const __a = { a: undefined }
const __b = { b: undefined }
__a.a = __b.b + 1
__b.b = __a.a || 0
export { __a as a, __b as b }

动态导入处理

// 原始代码
const module = await import('lodash-es')

// 预构建后
const module = await import('/node_modules/.vite/lodash-es.js')

自定义预构建配置

高级配置示例：

// vite.config.js
export default {
  optimizeDeps: {
    // 自定义入口文件
    entries: [
      'src/main.js',
      '!src/excluded.js'
    ],
    // 自定义 esbuild 插件
    esbuildOptions: {
      plugins: [myEsbuildPlugin()]
    },
    // 强制重新构建
    force: process.env.FORCE_REBUILD === 'true'
  }
}

与常规打包的区别

1. 开发阶段专用：仅用于开发服务器加速
2. 保留模块边界：不像生产打包那样完全扁平化
3. 不应用完整优化：省略代码分割、Tree-shaking 等生产优化

调试预构建过程

可以通过环境变量输出调试信息：

DEBUG=vite:deps vite

典型输出示例：

vite:deps 预构建依赖: vue, lodash-es +12ms
vite:deps 缓存命中: react, react-dom +4ms
vite:deps 重建依赖: vue-router (版本变更) +8ms

预构建产物分析

生成的缓存文件结构示例：

node_modules/.vite/
  ├── _metadata.json
  ├── vue.js
  ├── lodash-es.js
  └── dep-hash.json

其中 _metadata.json 包含：

{
  "hash": "a1b2c3d",
  "browserHash": "e4f5g6h",
  "optimized": {
    "vue": {
      "file": "/path/to/vue.js",
      "src": "/path/to/node_modules/vue/dist/vue.runtime.esm-bundler.js",
      "needsInterop": false
    }
  }
}