Vite 插件怎么开发？Plugin API 常用钩子有哪些？

Question

仓乃文 · Accepted Answer

Vite 插件基于 Rollup 插件接口扩展，比 Webpack 插件简单得多。核心是理解构建的三个阶段：开发服务器（configureServer）、构建转换（transform）、构建完成（closeBundle）。掌握这几个钩子就能覆盖 80% 的插件需求。

插件基本结构：
```typescript
// vite-plugin-my-plugin.ts
import type { Plugin } from "vite";

export default function myPlugin(options?: { prefix?: string }): Plugin {
  const prefix = options?.prefix || "MY_";
  let config: ResolvedConfig;

return {
    name: "vite-plugin-my-plugin",  // 插件名，必须唯一

// 1. 获取最终配置
    configResolved(resolvedConfig) {
      config = resolvedConfig;
    },

// 2. 开发服务器配置
    configureServer(server) {
      // 添加自定义中间件
      server.middlewares.use("/api/health", (req, res) => {
        res.end(JSON.stringify({ status: "ok" }));
      });
    },

// 3. 转换代码（最常用）
    transform(code, id) {
      if (id.endsWith(".custom")) {
        return {
          code: code.replace(/{{(\w+)}}/g, (_, key) => process.env[`${prefix}${key}`] || ""),
          map: null,
        };
      }
    },

// 4. 热更新处理
    handleHotUpdate({ file, server }) {
      if (file.endsWith(".custom")) {
        server.ws.send({ type: "full-reload" });
      }
    },

// 5. 构建完成
    closeBundle() {
      console.log("构建完成！");
    },
  };
}
```

常用钩子一览：
```
| 钩子              | 阶段       | 用途                          |
|------------------|-----------|-------------------------------|
| config           | 配置解析前  | 修改 Vite 配置                 |
| configResolved   | 配置解析后  | 获取最终配置                    |
| configureServer  | 开发服务器  | 添加中间件、WebSocket           |
| transform        | 模块转换   | 转换代码内容（最常用）           |
| resolveId        | 模块解析   | 自定义模块解析逻辑              |
| load             | 模块加载   | 自定义模块加载逻辑              |
| handleHotUpdate  | 热更新     | 自定义 HMR 行为                |
| buildStart       | 构建开始   | 构建前初始化                    |
| buildEnd         | 构建结束   | 构建后清理                      |
| closeBundle      | 输出完成   | 生成额外文件、上报               |
```

补充说明：
- transform 是最常用的钩子，类似 Webpack 的 loader
- 开发环境用 configureServer，生产构建用 transform/closeBundle
- 插件的 enforce 选项控制执行顺序："pre" | "post" | 默认中间
- Vite 插件兼容 Rollup 插件，但 Rollup 插件不一定兼容 Vite