Vite Dev 模式下的插件钩子执行详解

vite dev 启动
  ↓
【启动阶段】
config          → 修改/合并用户配置
configResolved  → 读取最终配置（只读）
configureServer → 注册自定义中间件
options         → 修改 Rollup/Vite 内部选项
buildStart      → 服务器就绪，开始处理模块

  ↓（浏览器请求模块时，每个模块触发一次）

【模块请求阶段】
resolveId       → 解析模块路径
load            → 加载模块内容
transform       → 转换模块代码

  ↓（浏览器请求 HTML 时）

【HTML 处理阶段】
transformIndexHtml → 转换 index.html

  ↓（文件变更时）

【HMR 阶段】
hotUpdate / handleHotUpdate → 处理热更新

  ↓（执行 Ctrl+C 关闭服务器时）

【关闭阶段】
buildEnd        → 模块图销毁前
closeBundle     → 服务器完全关闭后

{
  name: 'my-plugin',
  config(userConfig, env) {
    // env.command === 'serve' 时为 dev 模式
    if (env.command === 'serve') {
      return {
        resolve: {
          alias: { '@': '/src' }
        }
      }
    }
  }
}

{
  name: 'my-plugin',
  configResolved(resolvedConfig) {
    // 只读访问最终配置
    console.log('根目录：', resolvedConfig.root)
    console.log('模式：', resolvedConfig.command) // 'serve'
    console.log('插件列表：', resolvedConfig.plugins.map(p => p.name))
  }
}

{
  name: 'my-plugin',
  configureServer(server) {
    // 在内部中间件之前添加自定义中间件
    server.middlewares.use('/api', (req, res) => {
      res.end('mock data')
    })

    // 返回函数则在内部中间件之后执行
    return () => {
      server.middlewares.use((req, res, next) => {
        // 后置中间件
        next()
      })
    }
  }
}

{
  name: 'my-plugin',
  options(rollupOptions) {
    // 可修改 input、external 等选项
    return {
      ...rollupOptions,
      external: ['lodash']
    }
  }
}

{
  name: 'my-plugin',
  buildStart(options) {
    console.log('dev server 已就绪，开始监听模块请求')
    // 适合初始化插件内部状态
  }
}

{
  name: 'my-plugin',
  resolveId(source, importer, options) {
    // source: 导入路径，如 'lodash' 或 './utils'
    // importer: 发起导入的文件路径
    if (source === 'virtual:my-module') {
      return '\0virtual:my-module' // \0 前缀表示虚拟模块
    }
    return null // 返回 null 则交给下一个插件处理
  }
}

{
  name: 'my-plugin',
  load(id) {
    if (id === '\0virtual:my-module') {
      // 返回虚拟模块的代码
      return `export const msg = 'Hello from virtual module'`
    }
    return null // 返回 null 则由 Vite 默认读取文件内容
  }
}

{
  name: 'my-plugin',
  transform(code, id) {
    if (id.endsWith('.custom')) {
      const transformed = myCompiler(code)
      return {
        code: transformed,
        map: null // source map
      }
    }
    return null // 不处理则返回 null
  }
}

{
  name: 'my-plugin',
  transformIndexHtml(html) {
    // 简单字符串替换
    return html.replace('<title>App</title>', '<title>My App</title>')
  }
}

{
  name: 'my-plugin',
  transformIndexHtml(html) {
    return {
      html,
      tags: [
        {
          tag: 'script',
          attrs: { src: '/analytics.js' },
          injectTo: 'body'
        }
      ]
    }
  }
}

{
  name: 'my-plugin',
  hotUpdate(ctx) {
    // ctx.file: 变更的文件路径
    // ctx.timestamp: 变更时间戳
    // ctx.modules: 受影响的模块数组
    // ctx.server: ViteDevServer 实例
    // ctx.read(): 读取文件新内容

    if (ctx.file.endsWith('.json')) {
      // 自定义 HMR 逻辑：向客户端发送自定义事件
      ctx.server.hot.send({
        type: 'custom',
        event: 'json-update',
        data: { file: ctx.file }
      })
      return [] // 返回空数组表示不需要默认 HMR 处理
    }
  }
}

{
  name: 'my-plugin',
  handleHotUpdate(ctx) {
    // 与 hotUpdate 类似，但参数结构略有不同
    // Vite 5 中已被 hotUpdate 取代
    if (ctx.file.endsWith('.custom')) {
      ctx.server.ws.send({ type: 'full-reload' })
      return []
    }
  }
}

{
  name: 'my-plugin',
  buildEnd(error) {
    if (error) {
      console.error('服务器异常关闭：', error)
    }
    // 清理插件内部状态，等待重启后重新初始化
  }
}

{
  name: 'my-plugin',
  closeBundle() {
    // 释放文件句柄、关闭数据库连接等
    console.log('旧 dev server 已关闭，即将以新配置重启')
  }
}

1. config            ← 所有插件按顺序执行
2. configResolved    ← 所有插件按顺序执行
3. configureServer   ← 所有插件按顺序执行
4. options           ← 所有插件按顺序执行
5. buildStart        ← 所有插件按顺序执行

[浏览器请求 index.html]
6. transformIndexHtml

[浏览器请求 main.ts]
7. resolveId('main.ts')
8. load('/path/to/main.ts')
9. transform(code, '/path/to/main.ts')

[浏览器请求 App.vue]
10. resolveId('App.vue')
11. load('/path/to/App.vue')
12. transform(code, '/path/to/App.vue')

[文件变更触发 HMR]
13. hotUpdate(ctx)

[修改 vite.config.* 触发服务器重启（注意：Ctrl+C 不会触发以下两个钩子）]
14. buildEnd
15. closeBundle

enforce: 'pre' 插件
  ↓
Vite 内置插件
  ↓
普通插件（无 enforce）
  ↓
enforce: 'post' 插件

import type { Plugin } from 'vite'

function envInjectPlugin(): Plugin {
  let isDev = false

  return {
    name: 'env-inject',

    config(_, { command }) {
      isDev = command === 'serve'
    },

    configResolved(config) {
      console.log(`[env-inject] 运行模式: ${config.command}`)
    },

    transform(code, id) {
      if (!isDev) return null
      if (!id.endsWith('.ts') && !id.endsWith('.js')) return null

      // 开发模式下注入调试信息
      return code.replace(
        '__DEV_FILE__',
        JSON.stringify(id.replace(process.cwd(), ''))
      )
    }
  }
}

import type { Plugin } from 'vite'

function hmrNotifyPlugin(): Plugin {
  return {
    name: 'hmr-notify',

    hotUpdate(ctx) {
      const affectedModules = ctx.modules.map(m => m.id)
      console.log(`[HMR] 文件变更: ${ctx.file}`)
      console.log(`[HMR] 影响模块: ${affectedModules.join(', ')}`)

      // 不阻断默认 HMR 流程
      return ctx.modules
    }
  }
}