[!info] related notes

• 所属：插件与 SSR MOC
• 前置：双路径
• 后续：常用插件 · SSR 概览

Vite 插件系统

这个概念为什么出现

框架 JSX/SFC 转换、SVG 组件化、Markdown 页面、本地 mock、可视化分析——都需要稳定扩展点。Vite 选择：兼容 Rollup 插件生态，并增加 dev-only 钩子。

[!abstract] 一句话理解 Vite 插件 = 以钩子介入模块转换与构建生命周期的对象；多数构建钩子对齐 Rollup，开发服务器另有扩展钩子。

最小可观察示例

场景：把 virtual:app-version 注入业务横幅

// plugins/versionPlugin.ts
import type { Plugin } from 'vite'

export function versionPlugin(version: string): Plugin {
  const virtualId = 'virtual:app-version'
  const resolved = '\0' + virtualId

  return {
    name: 'version-plugin',
    // 教学点：resolveId/load 让虚拟模块进入模块图
    resolveId(id) {
      if (id === virtualId) return resolved
    },
    load(id) {
      if (id === resolved) {
        return `export const appVersion = ${JSON.stringify(version)}`
      }
    },
  }
}

// vite.config.ts
import { defineConfig } from 'vite'
import { versionPlugin } from './plugins/versionPlugin'

export default defineConfig({
  plugins: [versionPlugin(process.env.npm_package_version || '0.0.0')],
})

业务中：import { appVersion } from 'virtual:app-version'。TypeScript 项目另需声明该虚拟模块，否则构建转换成功仍可能类型检查失败：

// src/virtual.d.ts
declare module 'virtual:app-version' {
  export const appVersion: string
}

要限制 dev/build 作用阶段使用 apply: 'serve' / 'build'；enforce 只控制排序。

核心模型

钩子类别	用途
通用/构建（Rollup 对齐）	resolveId load transform buildStart…
Vite 特有	configureServer handleHotUpdate transformIndexHtml…
插件排序	enforce: 'pre' / 默认 / 'post'，与作用阶段不同

开发按请求调用模块钩子；Vite 8 生产由 Rolldown 消费兼容钩子，Vite 7 及以前标准实现使用 Rollup。兼容不等于完整超集：输出生成钩子如 generateBundle 不在普通 dev 请求中运行，部分旧 Rollup 钩子在 Rolldown 中不受支持。

边界

• 过多 transform 会拖慢 dev
• 插件顺序敏感（框架插件通常靠前）
• 不要把业务分支写进不可测插件黑洞

常见误区

[!warning] 常见误区：插件能抹平 dev/prod 一切差异 双路径仍在；插件应显式处理双方，或文档化差异。

工程实践

1. 先找官方/社区成熟插件
2. 自研插件保持单一职责
3. 用最小复现证明钩子触发点

本节总结

插件是 Vite 的正规扩展面：能改模块图与转换，不该成为隐藏业务层。

自测题

1. 为什么 configureServer 在生产构建无意义？
2. 虚拟模块常为什么要 \0 前缀？

参考答案

1. 它扩展的是 dev server，不参与静态产物生成主路径。
2. 标记为已解析/虚拟，避免再被当作真实磁盘路径解析。

延伸阅读

资料	类型	支撑内容
Vite Plugin API	官方	钩子