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"]
  }
}

对于大多数项目，保持直接插件选项较小，并在编译器设置中保持稳定 vize.config.ts。

共享配置

推荐的共享入口是vize。两个npm都会读取单个vize.config.*文件 打包命令和@vizejs/vite-plugin。

vp install -D vize

支持的配置文件：

• vize.config.pkl

• vize.config.ts

• vize.config.js

• vize.config.mjs

• vize.config.json

TypeScript 配置：

// vize.config.ts
import { defineConfig } from "vize";

export default defineConfig({
  compiler: {
    sourceMap: true,
    vapor: false,
    customRenderer: false,
    templateSyntax: "standard",
  },
  vite: {
    scanPatterns: ["src/**/*.vue"],
  },
});

PKL 配置：

amends "node_modules/vize/pkl/vize.pkl"

compiler {
  sourceMap = true
}

vite {
  scanPatterns = new Listing {
    "src/**/*.vue"
  }
}

带模式的JSON配置：

{
  "$schema": "./node_modules/vize/schemas/vize.config.schema.json",
  "vite": {
    "scanPatterns": ["src/**/*.vue"]
  }
}

从@vizejs/vite-plugin导入defineConfig仍然可以实现向后兼容，但import { defineConfig } from "vize"是未来的共享路径。

完整的共享配置形状请参见配置。

Vite Plus-first项目还可以在vite.config.ts中保持仅启动时的设置：

import { defineConfig } from "vite-plus";
import vize from "@vizejs/vite-plugin";

export default defineConfig({
  plugins: [
    vize({
      config: {
        compiler: {
          sourceMap: true,
          vapor: false,
        },
        vite: {
          scanPatterns: ["src/**/*.vue"],
        },
        musea: {
          include: ["src/**/*.art.vue"],
        },
      },
    }),
  ],
});

Vite插件和插件商店在执行Vite Plus时可以使用内联配置。 使用 vize.config.* 来处理那些必须由 CLI 和 LSP 命令读取的设置。

编译器选项

直接选项被传递到vize()覆盖vize.config.*。 完整的优先级是直接插件选项，然后是内联config，然后是vize.config.*，然后 默认值。

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

常见食谱：

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

// TresJS or another custom renderer
vize({ customRenderer: true });

// 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在首次请求时编译每个.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输出中。

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支持，请参见实验性捆绑器集成