534 lines
22 KiB
JavaScript
534 lines
22 KiB
JavaScript
/**
|
||
* ============================================================
|
||
* Rollup / Vite 插件钩子函数 完整参考手册
|
||
* ============================================================
|
||
*
|
||
* 钩子分为两大阶段：
|
||
* 1. Build 阶段 — 解析模块、构建依赖图
|
||
* 2. Output Generate 阶段 — 生成最终产物（chunk/bundle）
|
||
*
|
||
* 钩子类型：
|
||
* - async : 可返回 Promise，等待 resolve 后继续
|
||
* - sync : 同步执行
|
||
* - first : 多个插件有该钩子时，按顺序执行，第一个返回非 null 值的生效
|
||
* - sequential : 多个插件按顺序依次执行
|
||
* - parallel : 多个插件并行执行
|
||
*
|
||
* 以下是按 Rollup → Vite 分类的全部钩子。
|
||
*/
|
||
|
||
// ============================================================
|
||
// 一、Rollup 通用钩子（Build 阶段）
|
||
// ============================================================
|
||
|
||
export default function pluginHooksDemo() {
|
||
return {
|
||
name: 'plugin-hooks-demo',
|
||
|
||
// ----------------------------------------------------------
|
||
// 1. options
|
||
// 类型: async, sequential
|
||
// 触发时机: 读取完用户传入的 rollup/vite 配置后，开始构建之前
|
||
// 用途: 替换或操纵传给 rollup 的 options 对象
|
||
// ----------------------------------------------------------
|
||
options(rawOptions) {
|
||
// rawOptions — 用户的原始配置对象
|
||
// 返回 null/undefined 不做修改
|
||
// 返回一个 options 对象来覆盖（会合并到现有 options）
|
||
console.log('[options] 原始配置:', Object.keys(rawOptions))
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 2. buildStart
|
||
// 类型: async, parallel
|
||
// 触发时机: 构建开始时
|
||
// 用途: 构建前的初始化、创建输出目录、注册构建级变量等
|
||
// ----------------------------------------------------------
|
||
buildStart(options) {
|
||
// options — 最终合并后的配置对象
|
||
console.log('[buildStart] 构建开始, input:', options.input)
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 3. resolveId
|
||
// 类型: async, first
|
||
// 触发时机: 解析模块导入路径时（对每个 import 都会调用）
|
||
// 用途: 自定义模块解析逻辑，例如 alias、虚拟模块
|
||
// ----------------------------------------------------------
|
||
resolveId(source, importer, options) {
|
||
// source — import 语句中的原始路径，如 './utils' 或 'vue'
|
||
// importer — 发起导入的模块的绝对路径（入口模块为 undefined）
|
||
// options — { attributes, custom, isEntry }
|
||
//
|
||
// 返回:
|
||
// null — 交给下一个插件的 resolveId
|
||
// string — 解析后的模块绝对路径
|
||
// { id } — 对象形式，id 为解析路径
|
||
// false — 标记为 external（不打包）
|
||
console.log('[resolveId]', source, '←', importer)
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 4. load
|
||
// 类型: async, first
|
||
// 触发时机: 加载模块源码内容时（resolveId 之后）
|
||
// 用途: 返回模块内容，用于虚拟模块、加载非 JS 文件等
|
||
// ----------------------------------------------------------
|
||
load(id) {
|
||
// id — 模块的绝对路径
|
||
//
|
||
// 返回:
|
||
// null — 交给下一个插件
|
||
// string — 模块源代码
|
||
// { code, map, ... } — 带 sourcemap 等
|
||
console.log('[load] 加载模块:', id)
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 5. transform
|
||
// 类型: async, sequential
|
||
// 触发时机: 拿到模块源码后，AST 解析之前
|
||
// 用途: 对单个模块源码做转换（最常见的钩子之一）
|
||
// ----------------------------------------------------------
|
||
transform(code, id) {
|
||
// code — 模块源代码（前置插件 transform 后的结果）
|
||
// id — 模块的绝对路径
|
||
//
|
||
// 返回:
|
||
// null — 不做转换
|
||
// string — 转换后的代码
|
||
// { code, map, ... } — 带 sourcemap
|
||
// { code, ast, ... } — 直接提供 AST（跳过解析）
|
||
console.log('[transform] 转换模块:', id)
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 6. moduleParsed
|
||
// 类型: async, parallel
|
||
// 触发时机: 模块 AST 解析完成（所有 transform 之后）
|
||
// 用途: 读取模块信息，如 import/export 列表
|
||
// ----------------------------------------------------------
|
||
moduleParsed(moduleInfo) {
|
||
// moduleInfo 主要属性:
|
||
// id — 模块路径
|
||
// code — 模块源码
|
||
// ast — ESTree 语法的 AST 树
|
||
// importedIds — 静态 import 的模块 id 数组
|
||
// dynamicallyImportedIds — 动态 import
|
||
// importedIdResolutions — 静态 import 解析详情
|
||
// dynamicallyImportedIdResolutions — 动态 import 解析详情
|
||
// importers — 导入了本模块的模块 id 列表
|
||
// dynamicImporters — 动态导入了本模块的模块 id 列表
|
||
// isEntry — 是否为入口
|
||
// isExternal — 是否为 external
|
||
// meta — 插件间共享的自定义元数据对象
|
||
// assertions/attributes — import assertions
|
||
console.log('[moduleParsed] 解析完成:', moduleInfo.id)
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 7. resolveDynamicImport
|
||
// 类型: async, first
|
||
// 触发时机: 解析动态 import() 时
|
||
// 用途: 自定义动态导入的解析逻辑
|
||
// ----------------------------------------------------------
|
||
resolveDynamicImport(specifier, importer) {
|
||
// specifier — import(xxx) 中的 xxx
|
||
// importer — 发起动态导入的模块路径
|
||
//
|
||
// 返回:
|
||
// null — 交给下一个插件
|
||
// { id, external }
|
||
console.log('[resolveDynamicImport]', specifier, '←', importer)
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 8. buildEnd
|
||
// 类型: async, parallel
|
||
// 触发时机: 构建结束（无论成功/失败）时
|
||
// 用途: 清理资源、关闭文件句柄、输出统计信息
|
||
// ----------------------------------------------------------
|
||
buildEnd(error) {
|
||
// error — 如果构建失败则传入 Error 对象，成功则为 null
|
||
if (error) {
|
||
console.log('[buildEnd] 构建失败:', error.message)
|
||
} else {
|
||
console.log('[buildEnd] 构建结束')
|
||
}
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 9. watchChange [Rollup watch 模式]
|
||
// 类型: sync, sequential
|
||
// 触发时机: rollup --watch 时文件发生变化
|
||
// 用途: 监控文件变化，根据变更决定是否重新构建
|
||
// ----------------------------------------------------------
|
||
watchChange(id, change) {
|
||
// id — 变化文件的绝对路径
|
||
// change — { event: 'create' | 'update' | 'delete' }
|
||
console.log('[watchChange]', change.event, ':', id)
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 10. closeWatcher [Rollup watch 模式]
|
||
// 类型: async, parallel
|
||
// 触发时机: watch 进程关闭时
|
||
// 用途: 清理 watcher 相关资源
|
||
// ----------------------------------------------------------
|
||
closeWatcher() {
|
||
console.log('[closeWatcher] watcher 关闭')
|
||
},
|
||
|
||
// ============================================================
|
||
// 二、Rollup Output Generation 阶段钩子
|
||
// ============================================================
|
||
|
||
// ----------------------------------------------------------
|
||
// 11. outputOptions
|
||
// 类型: sync, sequential
|
||
// 触发时机: 获取 outputOptions 时
|
||
// 用途: 替换或操纵输出选项
|
||
// ----------------------------------------------------------
|
||
outputOptions(outputOptions) {
|
||
// outputOptions — 输出配置对象
|
||
console.log('[outputOptions] 输出配置:', Object.keys(outputOptions))
|
||
return null // 返回新对象则替换
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 12. renderStart
|
||
// 类型: async, parallel
|
||
// 触发时机: 每次调用 bundle.generate() 或 bundle.write() 时
|
||
// 用途: 输出阶段的初始化
|
||
// ----------------------------------------------------------
|
||
renderStart(outputOptions, inputOptions) {
|
||
console.log('[renderStart] 开始生成产物')
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 13. banner
|
||
// 类型: async, parallel
|
||
// 触发时机: 每个 chunk 生成前
|
||
// 用途: 在 chunk 最前面插入内容（如版权声明）
|
||
// ----------------------------------------------------------
|
||
banner(chunk) {
|
||
// chunk — 当前 chunk 信息对象
|
||
// 返回 string 或 Promise<string>
|
||
// console.log('[banner] chunk:', chunk.fileName)
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 14. footer
|
||
// 类型: async, parallel
|
||
// 触发时机: 每个 chunk 生成前
|
||
// 用途: 在 chunk 最后面追加内容
|
||
// ----------------------------------------------------------
|
||
footer(chunk) {
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 15. intro
|
||
// 类型: async, parallel
|
||
// 触发时机: 每个 chunk 生成前
|
||
// 用途: 在模块打包代码最前面插入内容（banner 之后、wrapper 内部）
|
||
// ----------------------------------------------------------
|
||
intro(chunk) {
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 16. outro
|
||
// 类型: async, parallel
|
||
// 触发时机: 每个 chunk 生成前
|
||
// 用途: 在模块打包代码最后面追加内容（footer 之前、wrapper 内部）
|
||
// ----------------------------------------------------------
|
||
outro(chunk) {
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 17. renderChunk
|
||
// 类型: async, sequential
|
||
// 触发时机: 每个 chunk 的代码生成时
|
||
// 用途: 对 chunk 代码做最终转换（可返回 sourcemap）
|
||
// ----------------------------------------------------------
|
||
renderChunk(code, chunk, outputOptions) {
|
||
// code — chunk 的完整代码
|
||
// chunk — chunk 信息对象
|
||
// outputOptions — 输出配置
|
||
//
|
||
// 返回:
|
||
// null — 不修改
|
||
// string — 修改后代码
|
||
// { code, map }
|
||
console.log('[renderChunk]', chunk.fileName)
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 18. augmentChunkHash
|
||
// 类型: sync, sequential
|
||
// 触发时机: 计算 chunk hash 时，用于追加自定义信息
|
||
// 用途: 让 chunk hash 也能反映插件自定义内容的变化
|
||
// ----------------------------------------------------------
|
||
augmentChunkHash(chunkInfo) {
|
||
// 返回一个字符串，会被追加到 hash 输入中
|
||
// 常用于：[hash] 文件名需要反映插件版本等场景
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 19. renderDynamicImport
|
||
// 类型: sync, first
|
||
// 触发时机: 渲染动态 import 表达式时
|
||
// 用途: 自定义动态 import 的运行时行为
|
||
// ----------------------------------------------------------
|
||
renderDynamicImport({ format, moduleId, targetModuleId, customResolution }) {
|
||
// format — 输出格式 (es / cjs / …)
|
||
// moduleId — 发起导入的模块 id
|
||
// targetModuleId — 被导入模块 id
|
||
// customResolution — resolveDynamicImport 返回的 custom 值
|
||
//
|
||
// 返回:
|
||
// null — 默认渲染
|
||
// { left, right } — 自定义 import 表达式的左/右半部分
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 20. resolveFileUrl
|
||
// 类型: sync, first
|
||
// 触发时机: 渲染文件引用 URL 时（如 import.meta.ROLLUP_FILE_URL_reference_xxx）
|
||
// 用途: 自定义文件 URL 解析
|
||
// ----------------------------------------------------------
|
||
resolveFileUrl({ chunkId, fileName, format, moduleId, referenceId, relativePath }) {
|
||
// 返回 null 使用默认，或返回自定义 URL 字符串
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 21. resolveImportMeta
|
||
// 类型: sync, first
|
||
// 触发时机: 渲染 import.meta 属性时
|
||
// 用途: 自定义 import.meta.xxx 的展开逻辑
|
||
// ----------------------------------------------------------
|
||
resolveImportMeta(property, { chunkId, moduleId, format }) {
|
||
// property — 访问的属性名，如 'url'
|
||
// 返回:
|
||
// null — 交给下一个插件
|
||
// string — 替换为指定字符串
|
||
// false — 保持 import.meta.property 不变
|
||
console.log('[resolveImportMeta]', property, 'in', moduleId)
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 22. generateBundle
|
||
// 类型: async, sequential
|
||
// 触发时机: bundle 生成完毕、写入磁盘之前
|
||
// 用途: 增、删、改最终产物（最常用的输出钩子之一）
|
||
// ----------------------------------------------------------
|
||
generateBundle(options, bundle, isWrite) {
|
||
// options — 输出配置
|
||
// bundle — { [fileName]: AssetInfo | ChunkInfo }
|
||
// isWrite — bundle.write() 为 true, bundle.generate() 为 false
|
||
//
|
||
// AssetInfo: { type: 'asset', fileName, source, name, needsCodeReference, ... }
|
||
// ChunkInfo: { type: 'chunk', fileName, code, map, modules, exports, facadeModuleId, isEntry, ... }
|
||
console.log('[generateBundle] 产物数:', Object.keys(bundle).length)
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 23. writeBundle
|
||
// 类型: async, parallel
|
||
// 触发时机: bundle 写入磁盘后
|
||
// 用途: 产物写盘后的后处理（上传 CDN、生成报告等）
|
||
// ----------------------------------------------------------
|
||
writeBundle(options, bundle) {
|
||
console.log('[writeBundle] 产物已写入磁盘')
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 24. closeBundle
|
||
// 类型: async, parallel
|
||
// 触发时机: bundle 生成完成后（最后的清理钩子）
|
||
// 用途: 收尾清理
|
||
// ----------------------------------------------------------
|
||
closeBundle() {
|
||
console.log('[closeBundle] Bundle 流程结束，清理资源')
|
||
},
|
||
|
||
// ============================================================
|
||
// 三、Vite 独有钩子
|
||
// ============================================================
|
||
|
||
// ----------------------------------------------------------
|
||
// 25. config
|
||
// 类型: async, sequential
|
||
// 触发时机: 解析 Vite 用户配置之前
|
||
// 用途: 修改/扩展用户配置，或返回部分配置与已有配置合并
|
||
// 这是 Vite 插件最常用的入口钩子
|
||
// ----------------------------------------------------------
|
||
config(config, env) {
|
||
// config — 用户传入的 vite 配置（未解析）
|
||
// env — { mode: 'development'|'production', command: 'serve'|'build', ssrBuild }
|
||
//
|
||
// 返回 null 或 部分配置对象（会被 deep-merge 到用户配置）
|
||
console.log('[config] 模式:', env.mode, '命令:', env.command)
|
||
return null
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 26. configResolved
|
||
// 类型: async, parallel
|
||
// 触发时机: Vite 配置解析完毕后
|
||
// 用途: 读取最终配置，做插件内部初始化（常在此缓存 resolvedConfig）
|
||
// ----------------------------------------------------------
|
||
configResolved(resolvedConfig) {
|
||
// resolvedConfig — 完整解析后的 Vite 配置（只读参考）
|
||
console.log('[configResolved] root:', resolvedConfig.root)
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 27. configureServer
|
||
// 类型: async, sequential
|
||
// 触发时机: Vite 开发服务器创建时
|
||
// 用途: 注册自定义中间件、WebSocket 事件等
|
||
// ----------------------------------------------------------
|
||
configureServer(viteDevServer) {
|
||
// viteDevServer 主要属性/方法:
|
||
// middlewares — Connect 实例，可用 .use() 添加中间件
|
||
// httpServer — Node http.Server 实例
|
||
// ws — WebSocket 服务器
|
||
// watcher — chokidar 文件监听器
|
||
// moduleGraph — 模块图
|
||
// config — 最终配置
|
||
// listen() — 启动服务器
|
||
// close() — 关闭服务器
|
||
// printUrls() — 打印服务地址
|
||
// transformIndexHtml() — 转换 HTML
|
||
// ssrFixStacktrace() — SSR 堆栈修复
|
||
// ssrLoadModule() — SSR 加载模块
|
||
// ssrTransform() — SSR 转换
|
||
viteDevServer.middlewares.use((req, res, next) => {
|
||
// 在这里可以拦截请求，自定义响应
|
||
next()
|
||
})
|
||
console.log('[configureServer] 开发服务器已创建')
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 28. configurePreviewServer
|
||
// 类型: async, sequential
|
||
// 触发时机: vite preview 命令创建预览服务器时
|
||
// 用途: 类似 configureServer，针对预览服务器
|
||
// ----------------------------------------------------------
|
||
configurePreviewServer(previewServer) {
|
||
// previewServer 接口与 viteDevServer 类似
|
||
previewServer.middlewares.use((req, res, next) => {
|
||
next()
|
||
})
|
||
console.log('[configurePreviewServer] 预览服务器已创建')
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 29. transformIndexHtml
|
||
// 类型: async, sequential / order: 'pre' | 'post' | undefined
|
||
// 触发时机: 转换 index.html 时
|
||
// 用途: 注入 <script> / <link> 标签、修改 HTML 内容
|
||
// 这是 Vite 插件最常用的输出钩子之一
|
||
// ----------------------------------------------------------
|
||
transformIndexHtml: {
|
||
// order: 'pre' — 在其他插件之前执行
|
||
// order: 'post' — 在其他插件之后执行
|
||
// 不设 order — 按插件注册顺序
|
||
order: 'pre',
|
||
handler(html, ctx) {
|
||
// html — index.html 文本内容
|
||
// ctx — 上下文对象
|
||
// ctx.path — 请求路径
|
||
// ctx.filename — HTML 文件路径
|
||
// ctx.server — ViteDevServer 实例
|
||
// ctx.bundle — 构建产物 bundle（serve 命令下可能为 undefined）
|
||
// ctx.chunk — 当前 HTML 对应的 chunk
|
||
// ctx.originalUrl — 原始请求 URL
|
||
//
|
||
// 返回:
|
||
// string — 转换后的 HTML
|
||
// { html: string, tags: [...] } — HTML + 注入标签
|
||
// { tags: [...] } — 仅注入标签
|
||
// Tag 格式:
|
||
// { tag: 'script', attrs: { src: '/foo.js' }, injectTo: 'head'|'body'|'head-prepend'|'body-prepend' }
|
||
// { tag: 'link', attrs: { rel: 'stylesheet', href: '/foo.css' }, injectTo: 'head' }
|
||
// { tag: 'meta', attrs: { name: 'viewport', content: 'width=device-width' }, injectTo: 'head' }
|
||
return html
|
||
}
|
||
},
|
||
|
||
// ----------------------------------------------------------
|
||
// 30. handleHotUpdate
|
||
// 类型: async, sequential / order: 'pre' | 'post' | undefined
|
||
// 触发时机: HMR 热更新时文件变化
|
||
// 用途: 自定义 HMR 更新行为：过滤哪些变更触发热更新、
|
||
// 执行自定义 HMR 逻辑而非默认重载页面
|
||
// ----------------------------------------------------------
|
||
handleHotUpdate(ctx) {
|
||
// ctx 上下文对象:
|
||
// ctx.file — 变更的文件路径
|
||
// ctx.modules — 受变更影响的模块数组
|
||
// ctx.read() — 读取变更后文件内容
|
||
// ctx.server — ViteDevServer 实例
|
||
// ctx.timestamp — 变更时间戳
|
||
//
|
||
// 返回:
|
||
// ModuleNode[] — 自定义受影响模块列表
|
||
// void — 默认行为，使用 ctx.modules
|
||
console.log('[handleHotUpdate] 文件变更:', ctx.file)
|
||
},
|
||
|
||
// ============================================================
|
||
// 四、已废弃的 Rollup 钩子（兼容旧插件，不推荐使用）
|
||
// ============================================================
|
||
|
||
// transformBundle(code, options) → 请用 generateBundle 替代
|
||
// transformChunk(code, options, chunk) → 请用 renderChunk 替代
|
||
// ongenerate(options, bundle) → 请用 generateBundle 替代
|
||
// onwrite(options, bundle) → 请用 writeBundle 替代
|
||
}
|
||
}
|
||
|
||
// ============================================================
|
||
// 附：钩子执行顺序总览
|
||
// ============================================================
|
||
//
|
||
// 【Build 阶段】
|
||
// options → buildStart → (每个入口模块并行)
|
||
// resolveId → load → transform → moduleParsed
|
||
// → resolveDynamicImport（遇到动态 import 时）
|
||
// → buildEnd
|
||
//
|
||
// 【Output Generate 阶段】
|
||
// outputOptions → renderStart → (每个 chunk 顺序)
|
||
// banner → footer → intro → outro
|
||
// → renderChunk → augmentChunkHash
|
||
// → renderDynamicImport → resolveFileUrl → resolveImportMeta
|
||
// → generateBundle → writeBundle → closeBundle
|
||
//
|
||
// 【Watch 模式】
|
||
// watchChange (文件变化时)
|
||
// closeWatcher (退出时)
|
||
//
|
||
// 【Vite 独有】
|
||
// config → configResolved
|
||
// → configureServer → configurePreviewServer
|
||
// → transformIndexHtml
|
||
// → handleHotUpdate
|
||
// ============================================================
|