Vite 插件

**⚠️ 正在开发中：**Vize正在积极开发中，尚未准备好投入生产使用。在采用非简单项目前，请彻底测试。

捆绑状态：@vizejs/vite-plugin目前是最稳定的捆绑器集成。 rollup/webpack/esbuild用@vizejs/unplugin，Rspack用@vizejs/rspack-plugin。这些非Vite路径仍然不稳定，应被视为实验性。

@vizejs/vite-plugin为 Vite 项目提供原生速度的 Vue SFC 编译。它被设计为直接替换的，@vitejs/plugin-vue——你现有的Vue组件无需修改即可正常工作。

安装

从Vite+安装指南中安装一次vp，然后添加这些软件包：

vp install -D @vizejs/vite-plugin

只有当你的项目从"vize"导入共享配置助手时，才vize直接依赖或者暴露如vize:lint和vize:check等包脚本。

基本用法

// vite.config.js
import { defineConfig } from "vite";
import vize from "@vizejs/vite-plugin";

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

就这样。用 @vizejs/vite-plugin 替换@vitejs/plugin-vue，你的项目通过 Rust 编译。

TypeScript Vue 导入

把插件包添加到compilerOptions.types，这样直接.vue导入问题可以通过以下方式解决。未写本地 env.d.ts shim 的 TypeScript：

{
  "compilerOptions": {
    "types": ["vite/client", "@vizejs/vite-plugin"]
  }
}

这不需要直接添加vize作为项目依赖。

对于 Vite Plus 项目，保留 Vite Plus 客户端类型，并附加插件包：

{
  "compilerOptions": {
    "types": ["vite-plus/client", "@vizejs/vite-plugin"]
  }
}

共享原生设置

将共享原生设置放在 vite.config.* 的 vue: 中。Vite+ 可以使用 defineConfig(vpConfig).withVue(vueConfig) 保留现有配置；普通 Vite 也可以直接传入插件选项。CLI 和编辑器读取同一份 Vue 设置；语法和文件发现规则见配置指南。

编译器选项

直接传给 vize() 的选项优先，然后是内联 config、发现的项目设置和默认值。共享设置使用 Vite 配置中的 vue:；专用的 vize.config.* 已不再受支持。config: false 禁用自动发现。

vize({
  vueVersion: 3,
  sourceMap: true,
  ssr: false,
  vapor: false,
  customRenderer: false,
  templateSyntax: "standard",
  scanPatterns: ["src/**/*.vue"],
  ignorePatterns: ["node_modules/**", "dist/**", ".git/**"],
});

选项	设置在哪里	描述
`vueVersion`	`vize({ vueVersion })`	将`0.11`、`1`、`2`或`"legacy"`设置为非侵入式的遗留Vue兼容性模式运行，SFC编译则交由主机编译器完成。
`sourceMap`	`compiler.sourceMap`或`vize({ sourceMap })`	生成源图。默认是开启开发，关闭生产。
`ssr`	`compiler.ssr`或`vize({ ssr })`	当Vite的SSR构建旗帜不够时，强制SSR汇编。
`vapor`	`compiler.vapor`或`vize({ vapor })`	通过Vapor后端编译模板。
`jsxMode`	`compiler.jsxMode`或`vize({ jsxMode })`	`.jsx`/`.tsx`组件的默认输出后端（`"vdom"` / `"vapor"`）。每个组件的 `"use vue:*"` 指令覆盖了它。
`customRenderer`	`compiler.customRenderer`或`vize({ customRenderer })`	把小写非HTML标签当作自定义渲染器元素。不匹配 `<TresMesh>` 这类 PascalCase 标签。
`customElements`	`compiler.customElements`或`vize({ customElements })`	作为自定义元素编译的标签模式。TresJS 的 PascalCase 渲染器标签使用 `["Tres*"]`。
`templateSyntax`	`compiler.templateSyntax`或`vize({ templateSyntax })`	选择`"standard"`、`"strict"`或`"quirks"`模板语法处理。
`include`	`vite.include`或`vize({ include })`	插件应该编译的文件。
`exclude`	`vite.exclude`或`vize({ exclude })`	这些文件是插件应该忽略的。
`scanPatterns`	`vite.scanPatterns`或`vize({ scanPatterns })`	用于启动预编译的球状模式。
`ignorePatterns`	`vite.ignorePatterns`或`vize({ ignorePatterns })`	启动前编译时，球状模式跳过。
`configMode`	`vize({ configMode })`	使用`"root"`、`"auto"`或`false`来实现共享配置加载。
`configFile`	`vize({ configFile })`	加载一个特定的配置文件。
`config`	`vize({ config })`	Vite Plus 运行时设置的内联共享配置。
`handleNodeModulesVue`	`vize({ handleNodeModulesVue })`	按需编译`.vue`从`node_modules`导入的文件。
`debug`	`vize({ debug })`	打印插件调试日志。

常见食谱：

// Vapor-oriented build
vize({ vapor: true });

// TresJS PascalCase 渲染器标签
vize({
  customRenderer: true,
  customElements: ["Tres*", "primitive"],
});

// Existing templates that rely on parser edge cases, such as
// v-for alias edge parens or `<div />` as a self-closing leaf
vize({ templateSyntax: "quirks" });

// Monorepo package with explicit scan roots
vize({
  root: import.meta.dirname,
  scanPatterns: ["src/**/*.vue", "examples/**/*.vue"],
});

// Legacy Vue / Nuxt 2 Bridge project with an existing host compiler plugin
vize({ vueVersion: 2 });

vueVersion: 0.11、1、2和"legacy"是主机-编译器的兼容模式。Vize没有在这些模式下编译.vue文件，不会暴露 Vue 3 vite:vue API shim，也不会注入Vue 3捆绑器的功能标志。保留现有的Vue编译器插件、vue-loader或Nuxt 2的插件自己的编译器配置正常。

工作原理

该插件拦截.vue文件请求，并通过Vize的Rust原生流水线通过Node.js NAPI绑定进行编译：

1.预编译— 在buildStart时，插件会发现所有.vue文件并使用compileBatch批量编译。这会触发基于Rayon的Rust端并行编译，同时处理所有CPU核心上的所有文件。

2.按需编译— 开发过程中，如果请求的缓存中不存在的 .vue 文件（例如动态导入），则通过 compileFile 实时编译。

3.HMR— 当.vue文件发生变化时，只有该文件会被重新编译。插件检测该更改是否仅样式，并在可能的情况下应用仅样式的HMR更新，避免了整个组件的重新渲染。

4.CSS 提取— 在生产版本中，所有来自 Vue 组件的 Scopeed CSS 都会被提取并合并为 assets/vize-components.css，消除了每个组件的注入开销。

合辑流程

.vue file
  → Armature (Parser)          — Tokenizes and parses the SFC structure
  → Croquis (Semantic Analysis) — Analyzes template expressions and bindings
  → Atelier (Compilation)       — Generates optimized JavaScript output
  → Vitrine (NAPI Binding)      — Delivers the result to Node.js
  → Vite module graph            — Served as a virtual module

同一语义分析层通过linting和类型检查被重复使用。参见静态分析用于管道的诊断部分。

比较

特色	@vitejs/plugin-vue	@vizejs/vite-plugin
语言	JavaScript	锈蚀（NAPI）
SFC合辑	是的	是的
模板汇编	是的	是的
脚本设置	是的	是的
CSS 范围	是的	是的
SSR支持	是的	是的
HMR	是的	是的（仅样式优化）
批次预编译	不	是的（通过人造丝平行）
CSS 提取	每个组件	合并单文件
蒸汽模式	实验	一等舱（`vize_atelier_vapor`）

高级功能

批次预编译

与@vitejs/plugin-vue在首次请求时编译每个.vue文件不同，Vize在构建开始时通过多线程批处理编译对发现的所有.vue文件进行预编译。这意味着：

开发服务器启动— 所有组件在第一个页面加载前已准备好
生产构建— 从一开始就实现最大并行性

静态资产重写

插件会自动重写模板中的静态资源URL。例如：

<template>
  <img src="./logo.png" />
</template>

src属性被提升到导入语句中，使 Vite 能够通过其资产流水线处理该资产（哈希、优化等）。

定义替代

Vite 通常跳过import.meta.*替换虚拟模块（前缀为 \0）。Vize 的插件手动应用定义替换，确保import.meta.env.*值在编译后的 Vue 组件中正确工作。

按环境隔离

为了与 Nuxt 兼容，插件会根据 Vite 环境（客户端与服务器/SSR）分离define值。这防止客户端环境值泄漏到SSR输出中。

样式预处理器与 Pug

<style lang="scss">、sass、less 和 stylus 按 Vue 的顺序处理：先运行预处理器，再由 Vize 为其输出添加作用域并解析 v-bind()。<style module> 的类名映射由打包器的 CSS Modules 流水线生成。与 @vitejs/plugin-vue 一样，请在项目中安装预处理器包（sass 或 sass-embedded、less、stylus）。<template lang="pug"> 由 Vize 自身编译，无需额外的包。旧版 <template lang="jade"> 写法也可在相同场景中作为别名使用。

场景	scss / sass / less / stylus	pug / jade
Vite	由 Vite 预处理，Vize 为结果添加作用域	原生
`@vizejs/unplugin`（webpack、Rollup、Rolldown、esbuild）	webpack 使用项目的 loader；Rollup、Rolldown、esbuild 运行已安装的预处理器	原生
`@vizejs/rspack`	项目的 loader（css-loader 或原生 CSS）	原生
`vize build`	通过 Node 运行已安装的预处理器	原生
`vize fmt`	预处理器块保持原样，一个字节都不改	格式化
`vize lint`	应用模板规则；样式块不会作为 CSS 进行 lint	应用模板规则
LSP	CSS 补全和悬停（包括缩进语法）、`v-bind()` 跳转到定义、所有预处理器中的 CSS Modules 类名补全	标签补全和跳转到定义

Nuxt 兼容性

该插件为探测@vitejs/plugin-vue API（如 Nuxt）的工具提供了兼容性垫片。这意味着 Vize 无需特殊配置即可使用 Nuxt 内置的 Vue 集成：

// nuxt.config.ts — using the dedicated Nuxt module
export default defineNuxtConfig({
  modules: ["@vizejs/nuxt"],
  vize: {
    compiler: true,
  },
});

详情请参见Nuxt Integration。

注释

该插件需要@vizejs/native Node.js NAPI绑定（作为依赖自动安装）
蒸汽模式编译可通过vize_atelier_vapor（Vue 3.6+）获得
VDOM编译使用vize_atelier_dom
插件支持导入所有编译后的CSS模块virtual:vize-styles
.jsx/.tsx Vue 组件通过同一插件自动编译 — 详见 JSX & TSX 指南
关于实验性汇总/webpack / esbuild / Rspack支持，请参见实验性捆绑器集成