Vite 导入图与模块图内部：依赖追踪、解析与图结构

入口 index.html →  main.ts
                → App.tsx → Button.tsx
                → utils.ts
                → 动态导入: /lazy → HeavyPage.tsx

Vite 启动时从入口展开：
  每个模块记录它的「导入依赖」列表
  依赖再次展开 → 直到叶子模块
  形成的树/图 = 导入图（Import Graph）
→ 导入图 = Vite 的「依赖地图」，知道一切从哪来

- 启动优化：只转换「被导入的模块」（按需）
- 模块复用：一个模块只转换一次，全图共享
- HMR 传播：改动传播沿导入图（下游都热更新）
- 依赖分析：哪些是用户代码、哪些是依赖（预打包）
→ 导入图决定了「加载什么、转换什么、更新什么」

- 导入图（Import Graph）：关注「依赖关系」（谁导入谁）
- 模块图（Module Graph）：关注「模块实例」及其元数据
  - 模块节点的缓存/转换结果/URL
  - 实践中两者交织，是同一张图的「关系视角」与「节点视角」
→ 理解上：导入图 = 关系，模块图 = 节点 + 状态

- dev：启动时建「入口模块」，其余按需懒建
  （访问到才展开，所以秒启）
- build：一次遍历全部可达模块（完整图）
- 依赖预打包：单独建「依赖图」（node_modules）
→ dev 懒建、build 全建、依赖独立建

- Webpack：启动即全量构建模块图（慢启动）
- Vite：入口 + 懒展开（快启动）
- Vite 的「懒」= 导入图按需扩展
→ 快启动的根源 = 图是「增量展开」而非「全量预建」

每个被 import 的文件 = 一个「模块节点」
  模块 id：规范化路径（file:///.../App.tsx）
  依赖（deps）：它 import 的模块 id 列表
  被依赖（importers）：谁 import 了它
  元数据：URL、转换结果、是否已加载
→ 模块节点 = id + 依赖 + 被依赖 + 状态

- 原始写法：import './App'  /  import 'react'
- 解析后 id：file:///src/App.tsx（绝对路径）
- 依赖预打包：id 变为 /node_modules/.vite/... 
  （react → .vite/deps/react.js）
- 特殊 id：虚拟模块 /@vite/ 前缀（如 /@vite/client）
→ id 规范化 = 每种导入最终落到「唯一模块」

deps（出边）：App.tsx → [Button.tsx, utils.ts]
importers（入边）：Button.tsx ← [App.tsx, Other.tsx]

→ 图是「双向」的：
  出边用于「递归展开」（加载依赖）
  入边用于「HMR 传播」（改动向下游传）

- loaded：是否已加载（懒加载用）
- transformResult：转换后的代码（缓存）
- moduleInfo：id、url、是否虚拟
- 构建期：是否属于某个 chunk
→ 模块节点带状态，不只是「关系」

- /@vite/client：客户端运行时
- /@vite/refresh：React refresh 运行时
- /@fs/...：文件系统访问模块
- 插件生成的虚拟模块（如 virtual:xxx）
→ 虚拟模块没有「实体文件」，由运行时/插件生成

// 插件在 load 钩子看到模块 id
export default {
  name: 'inspect-module',
  async load(id: string) {
    if (id.includes('/src/')) {
      console.log('[load]', id);
    }
    return null; // 不拦截，继续默认处理
  }
}

import 'react'            → node_modules/react/index.js（或 exports 指定）
import './Button'         → ./Button.tsx（扩展名推断）
import '@/utils'          → alias 别名 → 实际路径
import '/src/main.ts'     → 直接绝对路径

→ 解析 = 从「导入写法」到「唯一模块 id」的映射

1. 别名（alias）：@/ → src/
2. 裸导入（bare）：node_modules 查找（exports/main/module）
3. 相对/绝对导入：文件系统 + 扩展名推断
4. 虚拟模块：/@vite/、virtual:（插件注册）
→ 每一层都有插件钩子可干预（resolveId）

import './Button' 解析顺序：
  - ./Button.tsx / .ts / .jsx / .js（按 extensions 配置）
  - ./Button/index.tsx（目录 index）
  - ./Button/package.json 的 main/exports（目录即包）
→ 解析配置 extensions 与 index 影响命中

// 插件把 virtual:foo 解析为真实 id
export default {
  name: 'virtual-resolve',
  resolveId(id: string) {
    if (id === 'virtual:foo') {
      return '\0virtual:foo'; // \0 前缀标记虚拟模块
    }
    return null;
  },
  load(id: string) {
    if (id === '\0virtual:foo') {
      return 'export const value = "virtual"';
    }
    return null;
  }
}

- node_modules 缺失（未安装 / exports 不存在）
- 扩展名没配置（.vue 需要插件 resolve）
- alias 写错（路径对不上）
- exports 条件不满足（require vs import 环境）
→ 解析错误 = 依赖问题排查第一站

- 依赖（node_modules）先被 esbuild 预打包
- 导入重写：import 'react' → import '/node_modules/.vite/deps/react.js'
- 所以运行时的「模块 id」是预打包产物
- 依赖更新（新增/升级）→ 重新预打包（缓存失效）
→ 依赖解析 = 裸导入 → 预打包 → 缓存 id

- 解析器（es-module-lexer）分析源码的 import 语句
- 提取三类：
  ① 静态 import（import x from './y'）
  ② 动态 import（import('./lazy')）
  ③ import.meta.url（worker 等）
- 不执行代码，只做「静态语法扫描」（快）
→ 依赖追踪 = 静态扫描 import，不运行代码

- 纯语法解析（不做类型/语义分析）
- 极快：百万行级毫秒处理
- 提取 import 与 export 语句的源
- 交给插件（transform）后可再扫描（依赖可能变）
→ 静态 lexer = Vite 依赖追踪的「扫描引擎」

// 动态导入也是依赖，但标记为「动态」
const lazy = await import('./HeavyPage')
// → 依赖列表里记录 './HeavyPage'（动态）

// 动态导入的变量写法（无法静态追踪）
const name = 'page-' + id
await import(`./pages/${name}.js`)
// → 无法静态解析（运行期才知道）
// → Vite 会把目录下候选都视为可能依赖（部分展开）

- 插件 transform 可能改变 import（转译/替换）
- 所以 Vite 在 transform 后「重新分析依赖」
- 依赖集合 = 原分析 ∪ 转换后分析
- 依赖可能因此新增/删除（影响图结构）
→ 转换后要「再扫描」，依赖才准确

- 只能追踪「可静态解析」的导入
- 动态拼接的导入无法追踪（要 glob 展开或手动）
- 代码注入（eval、全局 fetch）看不到
- 条件导入（if）会「全保留」（运行时才知真假）
→ 静态追踪有边界，运行时导入需额外处理

- 模块节点的 deps（规范化 id 列表）
- 动态依赖标记（供代码分割用）
- importers 反向索引（供 HMR 用）
- 图结构的「边」全部来自追踪
→ 追踪产物 = 出边 + 入边 + 动态标记

请求模块 → resolve（解析 id）→ load（读源码）
        → transform（插件链转换）→ 依赖追踪（扫描）
        → 返回转换后代码 → 浏览器执行
→ 一次模块请求 = 一条「解析-加载-转换-扫描」流水线

- 转换前：图里「没有」该模块（或未转换）
- 转换中：插件链处理源码（TS/JSX/CSS 转译）
- 转换后：更新模块节点的 transformResult + deps
- 图的边 = 转换中「扫描出的依赖」
→ 模块「进图」发生在转换流水线中

- dev：模块被请求时转换 + 收集依赖（懒）
- build：遍历图时全量转换 + 收集（全量）
- 预打包：依赖单独转换 + 收集
→ 收集时机与构建模式一致（懒/全量/独立）

- 已转换模块缓存 transformResult（避免重复转换）
- 依赖变化（源码改动）→ 缓存失效重新转换
- HMR：仅失效「受影响模块」的缓存
→ 缓存 = 「只转一次 + 按依赖失效」

// 用插件拦截 transform 观察流水线
export default {
  name: 'watch-transform',
  transform(code: string, id: string) {
    console.time(`transform:${id.split('/').pop()}`);
    // 默认返回 null（走内置转译）
    return null;
  }
}

- 懒加载：只跑「被请求模块」的流水线
- 复用：同一模块的转换结果全图共享
- 失效：依赖变化 → 精确失效下游缓存
- 增量：改动只重跑受影响流水线
→ 图 + 流水线 = 按需、复用、失效、增量的闭环

dev 启动：只建入口（index.html → main）
  访问 App 路由 → 展开 App 的依赖
  点击「详情」→ 展开详情页的依赖
→ 图是「增量长出来」的，不是一次性建全

- 大项目几千模块，全量转换很慢
- 惰性：只转换「当前需要的」子图
- 冷启动快（入口小）、首次交互快（按需）
- 代价：热更新后冷模块首次加载稍慢（转换）
→ 惰性 = 「以首屏为代价控制启动成本」

// 动态导入创建「惰性节点」
const page = await import('./pages/About')
// About 及其依赖：只有 import 执行时才进图

- build 必须「全量可达」：所有静态 + 动态都打包
- 动态导入 → 独立 chunk（代码分割）
- 全量 = 一次遍历图，收集所有模块
→ dev 惰性（省启动）、build 全量（保证产物完整）

// 预加载：用 prefetch 提前取动态 chunk
const page = () => import('./pages/About')
// vite:preload 自动注入 <link rel="modulepreload">
// 平衡：惰性加载 + 预加载策略（见性能篇）

- dev 请求日志：模块被请求的时间（懒加载可见）
- 网络面板：js 请求是「用到才发」
- 依赖预加载：preload 让常用动态模块提前
→ 惰性扩展 = 请求驱动的图增长

编辑 Button.tsx
  → Button 模块缓存失效
  → 找到 Button 的 importers（谁依赖它）
  → 依赖它的模块都需更新（传播链）
  → 到达「边界」模块（接受 HMR 的模块）→ 热替换
→ HMR = 沿「入边反向」传播更新

// 模块接受 HMR：它作为「更新边界」
import.meta.hot.accept('./Button', (newModule) => {
  // 只重渲染 Button 相关部分
})

// 不接受的模块：向上传播直到接受者
// 无接受者 → 整页刷新（fallback）
→ 边界 = 谁 accept，更新就在哪停下

Button.tsx 改动
  → 传播到 importers：App.tsx
  → App 若 accept → 边界（只更新 App 子树）
  → App 不 accept → 传播到 App 的 importers：main.tsx
  → main 不 accept → 传播到头 → 整页 reload
→ 传播链 = 沿入边向上，遇 accept 停止

- 图存了「入边」（importers）
- 改动时立刻知道「下游有哪些」
- 不靠重新扫描全图（省时）
- 缓存失效也沿此传播（精确失效）
→ 入边 = HMR 与缓存失效的「导航表」

- 改 A.tsx：A 及「依赖 A 的已加载模块」失效
- 未加载模块：不失效（还没进图/没缓存）
- 依赖变化 vs 内容变化：都触发传播
- 传播结果：边界 accept → 局部热更 / 无边界 → reload
→ 失效粒度 = 「已加载的传播链」而非全图

// 查看模块是否被 accept 及传播
console.log(import.meta.hot)
// import.meta.hot.data：跨更新共享状态
// import.meta.hot.accept / dispose：边界与清理

- 每模块：id 字符串 + deps + importers + transformResult
- 大项目：几千模块 → 图本身不小
- transformResult：大文件转换结果占大头
- 懒加载：未访问模块不进图（省内存）
→ 图内存 = 节点 × （元数据 + 转换结果）

1. 懒加载：不访问不进图（最有效）
2. 转换结果瘦身：sourcemap 按需生成
3. 依赖预打包：依赖只存「预打包产物」（一次）
4. 缓存失效即释放：失效模块的 transformResult 清掉
→ 图内存 = 懒 + 瘦 + 复用 + 及时释放

- 直接转换 node_modules：每个依赖模块独立转换（浪费）
- 预打包：依赖合并成少量文件（esbuild 一次）
- 图中依赖部分 = 预打包文件的引用（极简）
→ 预打包 = 依赖图的「压缩」，省节点省内存

- 内容哈希：源码变化 → 缓存键变化
- 依赖图缓存：.vite 目录持久化（重启复用）
- 失效范围：按「受影响传播链」精准失效
- 冷启动优化：预打包缓存命中 → 秒启
→ 缓存 = 内容哈希 + 持久化 + 精准失效

- 构建全量图后：按依赖分析做 chunk 分割
- 共享模块提取（公共 chunk）
- 动态导入 → 独立 chunk（减少首包）
- tree-shaking 移除未用导出（见 Tree-shaking 篇）
→ build 图 → 分割 + 提取 + 摇树 = 产物优化

- dev：观察 node_modules/.vite 缓存大小
- 大转换结果模块（巨大源码）留意
- 重启释放内存（dev server 常驻内存图）
- 生产：构建内存限制（打包器选项）
→ 图内存监控 = 缓存目录 + 大模块 + 重启

- vite 启动日志：看到加载的模块（懒展开）
- dev 请求日志：模块被请求的时机与顺序
- 浏览器 network：js 请求依赖（动态导入可见）
- 插件钩子观察：load/transform/resolveId 打日志
→ 调试 = 日志 + 网络 + 插件三视角

// 收集全图并打印依赖关系
export default {
  name: 'dump-graph',
  buildStart() {
    this.modules = [];
  },
  transform(code, id) {
    this.modules.push(id);
    return null;
  },
  buildEnd() {
    console.log('已转换模块数:', this.modules.length);
  }
}

# 打印解析与依赖相关日志
DEBUG=vite:resolve vite dev
DEBUG=vite:load vite dev
DEBUG=vite:import-analysis vite dev
# 按需选 debug 命名空间

问题 1：某模块没被加载（没进图）
  → 检查是否真的被 import / 动态导入路径对
问题 2：重复转换（同一模块多次）
  → 检查 id 是否规范化（/src/ 与相对路径）
问题 3：HMR 整页刷新
  → 检查 accept 边界缺失（见第 7 节）
问题 4：依赖解析失败
  → resolveId 日志定位（第 3 节）
→ 诊断 = 定位到「图节点、边、失效」三要素

- rollup-plugin-visualizer：构建产物与模块占比
- vite-plugin-inspect：查看转换后代码（看依赖）
- 手写 dump 脚本：打印 deps/importers 树
→ 可视化 = 产物视角 + 代码视角 + 自绘树

1. 最小复现：精简到最小项目定位
2. 加插件日志：load/transform 拦截关键 id
3. 对比 dev/build：差异暴露图构建差异
4. 查缓存：/node_modules/.vite 是否过期
→ 调试流程 = 最小化 + 日志 + 对比 + 查缓存