Vite 插件 API 约定
Vite 插件扩展了设计出色的 Rollup 接口,带有一些 Vite 独有的配置项。因此,你只需要编写一个 Vite 插件,就可以同时为开发环境和生产环境工作。
如果插件不使用 Vite 特有的钩子,可以作为 兼容 Rollup 的插件 来实现,推荐使用 Rollup 插件名称约定。
- Rollup 插件应该有一个带
rollup-plugin-
前缀、语义清晰的名称。 - 在 package.json 中包含
rollup-plugin
和 vite-plugin
关键字。
这样,插件也可以用于纯 Rollup 或基于 WMR 的项目。
对于 Vite 专属的插件:
- Vite 插件应该有一个带
vite-plugin-
前缀、语义清晰的名称。 - 在 package.json 中包含
vite-plugin
关键字。 - 在插件文档增加一部分关于为什么本插件是一个 Vite 专属插件的详细说明(如,本插件使用了 Vite 特有的插件钩子)。
如果你的插件只适用于特定的框架,它的名字应该遵循以下前缀格式:
-
vite-plugin-vue-
前缀作为 Vue 插件 -
vite-plugin-react-
前缀作为 React 插件 -
vite-plugin-svelte-
前缀作为 Svelte 插件
Vite 对虚拟模块的规范是在路径前加上 virtual:
。如果可能的话,插件名应该作为命名空间使用,以避免与生态系统中的其他插件发生冲突。例如,vite-plugin-posts
可以让用户引入 virtual:posts
或 virtual:posts/helpers
虚拟模块,以获得构建时信息。在内部,使用虚拟模块的插件在解析模块 ID 时应以 \0
为前缀,这是一个来自 Rollup 生态系统的惯例。这可以防止其他插件试图处理这个 ID(如节点解析),而像 sourcemap 这样的核心功能可以使用这些信息来区分虚拟模块和普通文件。\0
在导入的 URL 中不是一个允许的字符,所以我们必须在导入分析中替换它们。在浏览器中,一个 0{id}
的虚拟 ID 最终被编码为 /@id/__x00__{id}
。在进入插件处理管道之前,这个 ID 会被解码回来。所以这个过程在插件钩子代码中将是不可见的。
请注意,模块都直接来源于真实的文件,而单文件组件(比如 .vue 或 .svelte 文件)中的 script 模块将不需要这样的转换。单文件组件被处理时一般会生成一系列子模块但其代码都可以被映射回文件系统。对这些子模块使用 \0
会使得 sourcemap 工作异常。