Rollup 构建管线深入：插件钩子、产物结构与 manifest

1. 输入：HTML 入口（index.html → script 入口）
2. 解析入口：resolveId → 定位入口模块
3. 加载模块：load → 读源码
4. 转换模块：transform → 转译（TS/JSX/CSS）
5. 扫描依赖：es-module-lexer → 收集 import
6. 递归加载：展开所有可达模块（全量导入图）
7. 摇树：标记使用 + 删除未用
8. 分 chunk：按动态导入/公共依赖分割
9. 代码生成：生成 chunk/asset 文件
10. 输出：写入 dist + 生成 manifest
→ 构建 = 输入 → 模块图 → 摇树分割 → 生成输出

Rollup 分两阶段：
  Build 阶段：解析/加载/转换 → 得到「模块图」
  Generate 阶段：图 → chunk → 生成产物内容

插件钩子也分两阶段：
  build 钩子（resolveId/load/transform/...）
  output 钩子（renderChunk/generateBundle/...）
→ 先「建图」再「出产」，钩子按阶段分

- Vite 把 Rollup 作为「构建内核」
- Vite 负责：HTML 入口处理、CSS 处理、assets、env 替换
- Rollup 负责：模块图、摇树、chunk 分割、代码生成
- 两者组合 = Vite build
→ 分工：Vite 管「前端工程」，Rollup 管「打包内核」

- dev：逐模块转换（懒）+ esbuild 转译（快）
- build：全量模块图 + Rollup 打包（优化产物）
- dev 无 chunk 分割（按需请求）
- build 有摇树 + 分割 + 压缩（产物优化）
→ dev 服务开发、build 优化产物，两套路径

// vite.config.ts
export default defineConfig({
  build: {
    outDir: 'dist',
    rollupOptions: {
      input: 'src/main.ts',        // 入口
      output: { format: 'es' },     // 输出格式
      plugins: [myPlugin()]         // 注入插件
    }
  }
})
// rollupOptions = 直接透传给 Rollup

Build 阶段钩子（建图）：
  - resolveId：把导入解析为 id
  - load：读模块源码
  - transform：转换代码
  - moduleParsed：模块解析后（查看依赖）
  - buildEnd：图构建完成

Output 阶段钩子（出产）：
  - renderChunk：生成 chunk 前改代码
  - generateBundle：写文件前改产物
  - writeBundle：写文件后
→ 钩子 = 插件在各阶段「插入逻辑」的口子

resolveId(source, importer, options) → id | null
  - 解析导入；返回 null 走默认

load(id) → 代码 | null
  - 读取模块内容；null 走默认

transform(code, id) → code | null
  - 转换代码；返回转换后代码

renderChunk(code, chunk, options) → code | null
  - 生成 chunk 内容时改写（minify 前）

generateBundle(outputOptions, bundle) → void
  - 产物 bundle 对象：可改/增/删文件

resolveId → load → transform → moduleParsed
  （每个模块一轮，递归所有模块）
→ buildEnd → renderChunk（每个 chunk）
→ generateBundle → writeBundle

→ 顺序 = 建图先、出产后

- 返回 null/undefined：交给下一个插件/默认处理
- 返回对象（id）：resolveId 可返回 { id, external }
- 返回字符串：load 返回源码、transform 返回新代码
- 抛出错误：终止构建（可捕获提示）
→ 约定：不拦截就返回 null，拦截就返回结果

- Vite 特有钩子：config/configResolved（配置阶段）
- Vite 特有钩子：configureServer/handleHotUpdate（dev）
- Vite 会把 Vite 插件转成 Rollup 插件（映射钩子）
- Rollup 钩子在 Vite 插件里同样可用（transform 等）
→ Vite 插件 = Rollup 钩子 + Vite 特有钩子

- 钩子名要准确（拼错不报错但无效）
- async 钩子返回 Promise（慢但可 await）
- 缓存：同一模块只跑一次（除非失效）
- 顺序依赖：先 run 的钩子优先级（插件顺序）
→ 钩子 = 阶段 + 顺序 + 返回约定的三重约束

// 解析插件
export default {
  name: 'resolve-example',
  resolveId(source, importer, options) {
    if (source === 'virtual:config') {
      // 返回 id：虚拟模块用 \0 前缀标记
      return '\0virtual:config';
    }
    // 其他导入走默认解析（node_modules 等）
    return null;
  }
}

// 加载插件（提供虚拟模块内容）
export default {
  name: 'load-example',
  load(id) {
    if (id === '\0virtual:config') {
      return `export const config = { theme: 'dark' }`;
    }
    return null; // 其他模块走默认读文件
  }
}

- resolveId：回答「这个导入指向哪个模块」→ id
- load：回答「这个 id 的内容是什么」→ 源码
- 解析到 id 但没加载：走默认文件读取
- 虚拟模块：resolve 到 \0 前缀 id + load 返回内容
→ resolve 定位、load 取内容，两步分开

- \0 前缀：标记「非真实文件」的模块（隐藏于文件系统逻辑）
- 常见：virtual:config、virtual:svg、virtual:md
- 好处：打包器不会去磁盘找（省 IO 报错）
- 约定：真实文件不加 \0，虚拟必须加
→ 虚拟模块 = resolve 到 \0 id + load 给内容

- 多插件 resolveId 按顺序尝试（先返回先赢）
- 找不到 → 默认解析（node_modules/相对路径）
- 解析结果缓存（同一导入不再重复解析）
- 依赖更新（装新包）→ 缓存失效（需重启 dev/重建）
→ 解析 = 顺序尝试 + 默认兜底 + 缓存

- load 返回 null 时走文件系统（默认）
- 二进制/大文件：load 可用（读成字符串/ArrayBuffer）
- 目录导入：load 可能被触发两次（index 解析）
- 加载错误：抛错会定位到模块
→ 加载 = 默认读文件 + 虚拟模块拦截 + 错误定位

// 转换插件：把 TODO 注释替换
export default {
  name: 'replace-todo',
  transform(code, id) {
    if (id.includes('/src/')) {
      return code.replace(/TODO/g, 'TODO(app)');
    }
    return null;
  }
}

- 转译：TS → JS、JSX → JS、Vue SFC → JS
- 替换：环境变量、alias、常量（define）
- 注入：代码替换/插桩（埋点、HMR 注入）
- 预编译：CSS 预处理、模板编译
- 分析：解析模块、收集元数据（不修改也可返回 null）
→ 转换 = 每个模块「进入产物前」的处理

输入：源码（字符串）+ id（模块标识）
输出：转换后代码（字符串）| null（不改）
附加：可返回 sourcemap、可声明非 JS 处理
→ 转换 = code in → code out，可选 sourcemap

源码 → 插件A transform → 插件B transform → ... → 最终代码
- 顺序 = 插件注册顺序
- 前一个的输出 = 后一个的输入
- 每个都可返回 null（透传）
- 转换后再「重新扫描依赖」（可能改变）
→ 转换链 = 顺序管道 + 可选透传 + 依赖重扫

- 每个模块跑所有插件的 transform（耗时）
- dev：转换懒执行（用到才转）+ 缓存
- build：全量转换一次
- 大项目：transform 是构建耗时大头
→ 性能 = 缓存 + 懒执行 + 减少不必要转换

- vite-plugin-inspect：查看每个模块「转换前/后」代码
- transform 里 console 打日志（id + 耗时）
- 断点：插件在 IDE 里调试
- 对比 dev/build 的转换（路径可能不同）
→ 调试 = inspect + 日志 + 断点

- 图构建完：所有可达模块在「模块图」里
- 摇树后：只保留被使用模块/导出
- 分 chunk：把模块分配到「输出 chunk」
  - 入口模块 → 入口 chunk
  - 动态导入模块 → 独立 chunk（懒加载）
  - 公共依赖 → 共享 chunk（被多入口引用）
- 生成：每个 chunk 生成「打包后代码」
→ 打包 = 图 → 摇树 → chunk 分配 → 代码生成

- 按「谁加载谁」组织
- 动态导入点 = 天然分割点
- 公共依赖提升到父 chunk 或独立共享 chunk
- manualChunks 手动控制（按自定义规则）
- 目标：首包最小 + 缓存友好
→ 分配 = 分割点 + 公共提取 + 手动覆盖

// 在生成 chunk 内容时改写（minify 前）
export default {
  name: 'render-chunk-example',
  renderChunk(code, chunk, options) {
    // chunk 含模块信息，code 是生成内容
    return code.replace(/console\.log/g, 'console.info');
  }
}

// 在写文件前增删产物
export default {
  name: 'generate-bundle-example',
  generateBundle(outputOptions, bundle) {
    // 删除 sourcemap
    for (const [name, item] of Object.entries(bundle)) {
      if (name.endsWith('.map')) delete bundle[name];
    }
  }
}

- format：es/cjs/umd/iife（产物格式）
- minify：压缩（esbuild 默认）
- sourcemap：是否生成 map
- chunkFileNames/assetFileNames：命名规则
- generatedCode：ES 特性降级级别
→ 生成选项 = 格式 + 压缩 + map + 命名

- renderChunk 里看 chunk 内容（拼接是否正确）
- generateBundle 看产物文件清单（是否有预期文件）
- 产物大小：visualizer（占比分析）
- 重复模块：同依赖出现在多个 chunk（要提取）
→ 诊断 = chunk 内容 + 文件清单 + 大小分布

chunk：JS 模块打包后的文件（.js）
  - 入口 chunk：由入口模块生成（含启动代码）
  - 动态 chunk：懒加载的独立文件
  - 公共 chunk：多入口共享的依赖
asset：非 JS 资源（CSS/图片/字体/...）
  - 独立文件 + 内容哈希命名
entry：HTML 入口（Vite 生成）
  - 引用入口 chunk 与关键 asset
→ 产物 = chunk（JS）+ asset（资源）+ entry（HTML）

- 入口 chunk 引用动态 chunk（import() 运行时加载）
- 公共 chunk 被多个入口 chunk 引用（import 共享）
- 依赖关系由「import 语句」表达（ESM 产物）
- modulepreload 预加载（HTML 注入）
→ chunk = 有依赖关系的「ESM 文件集合」

- chunk 默认：[name]-[hash].js（hash = 内容哈希）
- 入口 chunk：[name] = 入口名（如 index-[hash].js）
- 动态 chunk：按导入点命名（About-[hash].js）
- asset：[name]-[hash][ext]（内容哈希防缓存失效）
- 手动配置：chunkFileNames/assetFileNames
→ 命名 = 可读名 + 内容哈希（缓存友好）

- CSS 独立成 asset（或注入 JS）
- CSS 与 chunk 关联（该 chunk 导入的 CSS）
- 生产常用：独立 CSS 文件 + link 引入
- CSS 也按内容哈希命名
→ CSS = 与 chunk 关联的 asset，独立缓存

- import logo from './logo.png' → asset 文件
- 返回 URL（/assets/logo-[hash].png）
- 小资源内联（base64，默认 4KB 阈值）
- 大资源独立文件 + 哈希
→ assets = 导入即处理，小内联大独立

- dist/ 静态部署（Nginx/CDN）
- index.html 是入口（引用打包资源）
- 服务端渲染读 manifest（见下节）
- PWA/离线：清单中资源预缓存
→ 产物 = 一套可部署的「静态站点」

// vite.config.ts 开启
export default defineConfig({
  build: { manifest: true }
})
// 生成 dist/.vite/manifest.json
{
  "src/main.ts": {
    "file": "assets/main-abc123.js",
    "src": "src/main.ts",
    "isEntry": true,
    "imports": ["assets/vendor-xyz.js"]
  }
}

- 服务端渲染：SSR 框架读 manifest 找到产物文件
- 预加载：知道入口 chunk 的依赖（modulepreload）
- 校验：部署后确认资源存在
- 指纹：内容哈希用于缓存策略
→ manifest = 构建产物与「消费方」的接口

<!-- Vite 构建时注入到 index.html -->
<script type="module" crossorigin
  src="/assets/main-abc123.js"></script>
<link rel="stylesheet" href="/assets/index-def456.css">
<link rel="modulepreload" href="/assets/vendor-xyz.js">
<!-- crossorigin + modulepreload = 生产资源加载优化 -->

- 入口 chunk 的依赖 chunk 预加载
- 提前发起请求（减少加载瀑布）
- 与动态 chunk 配合：预取懒加载 chunk（vite:preload）
- 浏览器缓存预加载资源（二次访问快）
→ preload = 提前拉取关键 chunk，减少等待

- 动态导入 chunk：vite:preload 自动注入预取
  （静态已知的动态导入 → 注入 modulepreload）
- 运行时动态路径：无法预注入（glob 可部分）
- 平衡：预取太多 = 首屏请求爆炸
→ 预取 = 静态动态导入自动注入，控制数量

// SSR 框架（如 vite-plugin-ssr）
const manifest = JSON.parse(fs.readFileSync(
  'dist/.vite/manifest.json', 'utf-8'))
const entry = manifest['src/main.ts']
// 用 entry.file 作为 script src
→ SSR 用 manifest 把 HTML 与产物关联

- 构建后检查 manifest.json 完整性（文件存在性）
- 对比 manifest 的 imports 与产物文件
- 部署后：资源 404 → 查 manifest 文件路径
- 多入口：manifest 覆盖所有入口
→ 调试 = manifest 与 dist 文件对比

// vite.config.ts
export default defineConfig({
  build: {
    target: 'es2020'   // 默认 esnext（现代）
  }
})
// 或 browserslist 字符串
target: ['es2020', 'safari14']

- 决定产物「使用哪些 ES 特性」
  - esnext：最新语法（现代浏览器支持）
  - es2020：可选链、空值合并等
  - 更低的 target：转换更多语法（体积大）
- 不匹配的语法会「转译/保留」
- 影响 chunk 大小与兼容性
→ target = 兼容性与体积的旋钮

- 现代应用：esnext（体积最小，需现代浏览器）
- 企业/兼容：es2018/es2015（转译更多，体积大）
- 极端：es5（老浏览器，几乎全转）
- 分层：现代给现代、老浏览器给 legacy（见下）
→ 降级 = 按「目标受众」选 ES 水平

- @vitejs/plugin-legacy：对老浏览器生成「旧版产物」
  - 检测不支持现代语法 → 加载旧版
  - 现代浏览器：现代产物（小快）
  - 旧浏览器：legacy 产物（转译全、大）
- 原理：双产物 + 特性检测加载
→ legacy = 现代快 + 旧兼容的「双产物方案」

- target 越低：转换越多、产物越大
- 转译：语法降级（async/await → generator）
- polyfill：新 API 需要 polyfill（core-js）
- 权衡：兼容受众 vs 体积性能
→ 评估 = 目标用户浏览器分布 + 体积预算

- 产物里搜索现代语法（?. ?? #field 等）
- 检查是否意外保留目标不支持的特性
- 用浏览器测试矩阵（chrome/safari/firefox）
- 生产监控：旧浏览器错误率
→ 检查 = 产物语法 + 浏览器实测 + 监控

# 打印构建调试信息
DEBUG=vite:build vite build
DEBUG=vite:resolve vite build
DEBUG=rollup vite build
# 组合：DEBUG=vite:*,rollup vite build

- 解析：哪些导入被解析到哪（vite:resolve）
- 构建：构建阶段进度与时间（vite:build）
- Rollup：插件钩子执行细节（rollup:*）
- 警告：构建时的潜在问题（未压缩/重复）
→ debug = 定位「解析、阶段、钩子、警告」

常见构建错误：
  1. 解析失败：依赖缺失/exports 错误
     → 查 resolveId 日志 + package.json
  2. 转换错误：语法/插件转换崩溃
     → 定位到出错模块（错误栈有文件）
  3. 产物错误：chunk 异常/循环依赖
     → 查循环 import + manualChunks
  4. 内存不足：大图/大文件
     → 减并行、提内存、拆构建
→ 错误 = 解析/转换/产物/资源 四类定位

- 循环 import：A → B → A
- 症状：产物中有未定义（TDZ）/执行顺序错
- 检测：Rollup 警告循环依赖（检查日志）
- 修复：重构（提取公共/延迟引用）
- 或：移动副作用初始化（避免顶层互依赖）
→ 循环 = 产物隐患，重构消除

- 构建耗时：transform 是大头（见第 4 节）
- 工具：vite build 的 time 输出（阶段耗时）
- 插件耗时：各插件 transform 时间（日志）
- 优化：缓存、减少插件、esbuild 转译
→ 耗时 = 阶段/插件定位，针对性优化

- 构建后冒烟：打开 dist 首页（资源加载）
- 校验 manifest：文件存在 + imports 完整
- 检查 gzip 大小（传输体积预算）
- 多浏览器实测（兼容性）
→ 验证 = 构建成功 + 产物可跑 + 体积达标