Vite 插件开发实战：钩子体系、transform 与虚拟模块

开发模式（vite dev）:
  Vite 服务器 + esbuild 转译 + 部分 Rollup 钩子（load/transform/resolveId）

生产构建（vite build）:
  完整 Rollup 管线（esbuild 仅做 minify）

import type { Plugin } from 'vite'

export function myPlugin(): Plugin {
  return {
    name: 'my-plugin',           // 必须：用于报错与日志
    // 可选钩子
    buildStart() {
      this.log('构建开始')
    },
  }
}

import { defineConfig } from 'vite'
import { myPlugin } from './plugins/my-plugin'

export default defineConfig({
  plugins: [myPlugin()],
})

export default {
  name: 'virtual-utils',
  load(id) {
    // 只处理虚拟模块
    if (id === 'virtual:utils') {
      return `export const now = () => Date.now()`
    }
  },
}

export default {
  name: 'add-version',
  transform(code, id) {
    // 只处理 src 下的 .ts 文件
    if (!id.includes('/src/') || !id.endsWith('.ts')) return

    return code.replace(
      /__APP_VERSION__/g,
      `'${process.env.npm_package_version}'`,
    )
  },
}

transform(code, id) {
  if (!id.endsWith('.md')) return

  return {
    code: compiledCode,
    map: null, // 需要时提供 sourcemap
  }
}

import config from 'virtual:app-config'   // 并非真实文件

export default {
  name: 'virtual-config',
  resolveId(id) {
    if (id === 'virtual:app-config') {
      return '\0virtual:app-config'  // \0 前缀标记，防止被当作真实路径
    }
  },
  load(id) {
    if (id === '\0virtual:app-config') {
      return `export default { name: '${process.env.APP_NAME}', version: '1.0.0' }`
    }
  },
}

import { defineConfig, type Plugin } from 'vite'

function serverLogger(): Plugin {
  return {
    name: 'server-logger',
    configureServer(server) {
      // 返回中间件函数，附加在内部中间件之前
      return (req, res, next) => {
        console.log(`[req] ${req.method} ${req.url}`)
        next()
      }
    },
  }
}

configureServer(server) {
  // 在模块加载前执行
  server.middlewares.use((req, res, next) => {
    // ...
    next()
  })

  // 在 Vite 启动后执行
  server.httpServer?.once('listening', () => {
    console.log('dev server ready')
  })
}

先注册的插件先执行（数组顺序）
别名 alias 插件默认放最前
Vite 核心插件与用户插件分层

export function importantPlugin(): Plugin {
  return {
    name: 'important',
    enforce: 'pre',   // pre / normal(默认) / post
    transform(code, id) {
      // pre 阶段先于其他用户插件执行
    },
  }
}

function ssrOnly(): Plugin {
  return {
    name: 'ssr-only',
    apply: 'build',        // 只在 build 时生效
    // apply: (config, { command }) => command === 'build'
    // apply: 'serve'       // 只在 dev 时生效
  }
}

import { execSync } from 'node:child_process'
import type { Plugin } from 'vite'

export function buildInfo(): Plugin {
  return {
    name: 'build-info',
    config() {
      const time = new Date().toISOString()
      let commit = ''
      try {
        commit = execSync('git rev-parse --short HEAD').toString().trim()
      } catch { /* 非 git 仓库 */ }

      return {
        define: {
          __BUILD_TIME__: JSON.stringify(time),
          __COMMIT_HASH__: JSON.stringify(commit),
        },
      }
    },
  }
}

console.log(`构建时间: ${__BUILD_TIME__}`)
console.log(`commit: ${__COMMIT_HASH__}`)

import { readFileSync } from 'node:fs'
import type { Plugin } from 'vite'

export function graphqlLoader(): Plugin {
  return {
    name: 'graphql-loader',
    // 只拦截 .graphql 结尾的模块
    resolveId(source, importer) {
      if (source.endsWith('.graphql')) {
        // 交给 Node 解析真实路径
        return null
      }
    },
    load(id) {
      if (id.endsWith('.graphql')) {
        const content = readFileSync(id, 'utf-8')
        return `export default ${JSON.stringify(content)}`
      }
    },
    // 开发期需要 watch 源文件变化
    handleHotUpdate(ctx) {
      if (ctx.file.endsWith('.graphql')) {
        const mod = ctx.modules.find(m => m.file?.endsWith('.graphql'))
        if (mod) mod.importers.forEach(i => i.hot.accept())
      }
    },
  }
}

import type { Plugin, ResolvedConfig } from 'vite'

interface Options {
  appName: string
  debug?: boolean
}

export function exposeConfig(opts: Options): Plugin {
  let config: ResolvedConfig
  const virtualId = 'virtual:app-config'
  const resolvedVirtual = `\0${virtualId}`

  return {
    name: 'expose-config',
    configResolved(resolved) {
      config = resolved
    },
    resolveId(id) {
      if (id === virtualId) return resolvedVirtual
    },
    load(id) {
      if (id === resolvedVirtual) {
        return `
export const appConfig = ${JSON.stringify(opts)}
export const mode = '${config.mode}'
export default appConfig
`
      }
    },
  }
}

// 使用
import appConfig, { mode } from 'virtual:app-config'
console.log(appConfig, mode)

function debugOrder(): Plugin {
  return {
    name: 'debug-order',
    buildStart() {
      this.debug?.('插件启动')
    },
    transform(code, id) {
      console.log(`[transform] ${id}`)
      return undefined
    },
  }
}

解析(resolveId) -> 加载(load) -> 转换(transform) -> 产出
                └── 虚拟模块让「不存在」的文件可被 import
                └── configureServer 注入开发期中间件