Vite 依赖预构建：optimizeDeps 原理、缓存失效与 Monorepo 实战

Vite 开发期用原生 ESM，但 node_modules 里大量包是 CJS（module.exports）。
浏览器不认识 CJS → 需要预先把它们转成 ESM。

import { debounce } from 'lodash-es'
→ 开发期 lodash-es 拆成上千个 ESM 文件 → 浏览器要发上千个请求 → 慢！

预构建：esbuild 把 lodash-es 合并成「一个文件」→ 一次请求。

1. 启动 dev server → Vite 读取 index.html / 入口模块
2. 扫描 import 语句 → 找出依赖（裸导入，非相对路径）
3. 交给 esbuild 打包：CJS→ESM、合并、压缩
4. 产物写入 node_modules/.vite/deps/
5. 后续请求直接命中缓存，无需再构建

import 'react'                 // ✓ 扫描
import 'lodash-es/map'         // ✓ 子路径
import './utils'               // ✗ 相对路径，不预构建

ls node_modules/.vite/deps/   # 每个依赖一个 .js 文件 + 索引
cat node_modules/.vite/deps/_metadata.json   # 版本与 hash 元信息

import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    // 强制把某些包纳入预构建（默认 esbuild 已扫描大部分）
    include: ['my-lib', 'lodash-es/map'],
    // 排除（已 ESM 化、或想按需加载的）
    exclude: ['@testing-library/react'],
    // 强制重新预构建（忽略缓存）
    force: true,
    // 预构建也用的 esbuild 选项
    esbuildOptions: {
      target: 'esnext',
    },
    // 限定只预构建这些顶层依赖（大型项目加速）
    needsInterop: [],
  },
})

触发重建：
1. 依赖版本变化（lockfile 变更）
2. 依赖的 import 路径变化
3. 手动 npm install / 更新依赖
4. optimizeDeps 配置变化
5. force: true / 删除 .vite

rm -rf node_modules/.vite
# 或一条命令重新安装并清缓存
npm install && rm -rf node_modules/.vite

packages/
  app/          # 你的 Vite 应用
  ui/           # 共享组件库（pnpm link 到 app）
  utils/

import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    // 1. 把链接包纳入预构建（并在源码变更时重扫）
    include: ['@repo/ui', '@repo/utils'],
  },
  server: {
    // 2. 监听链接包的真实源码目录
    watch: {
      ignored: ['!**/packages/**'],
    },
    // 3. 源码变更时让预构建失效（fs 事件）
    fs: {
      allow: ['..', 'packages'],
    },
  },
})

// 运行时才 import → 初始扫描可能漏
const module = await import('heavy-chart-lib')

export default defineConfig({
  optimizeDeps: {
    // 1. 显式 include 动态导入的依赖
    include: ['heavy-chart-lib'],
  },
})

1. 页面请求 import('heavy-lib') → 未预构建
2. Vite 发现新依赖 → 立即用 esbuild 预构建
3. 触发页面 reload → 再次请求命中新缓存

export default defineConfig({
  resolve: {
    // 解决重复依赖/命名冲突（多份相同库）
    dedupe: ['react', 'react-dom'],
  },
  optimizeDeps: {
    include: ['react', 'react-dom'],
  },
})

DEBUG=vite:deps npm run dev   # 看预构建详细日志