企业官网建设流程全解析

• 前端
• 开发工具

vanilla-extract 是一款 "Zero-runtime Stylesheets-in-TypeScript" 方案——样式在构建期编译为静态 CSS，运行时零开销。本文围绕仓库中 site/docs/integrations/vite.md 这一集成文档展开，完整讲解@vanilla-extract/vite-plugin的安装、配置项与标识符（identifier）体系，并结合 packages/vite-plugin/src/index.ts、packages/integration/src/compiler.ts 等源码，剖析其"编译器 + 虚拟 CSS 模块 + HMR"的底层实现，帮助你掌握在 Vite 项目中接入 vanilla-extract 的完整实战方案。

概述：零运行时样式如何在 Vite 中落地

vanilla-extract 的核心思路是在构建阶段执行.css.ts文件，将 TypeScript 中声明的样式对象编译为 CSS 字符串，再交由 Vite 的 CSS 管线处理；运行时浏览器中只有编译后的静态 CSS 和极简的类名引用，没有任何样式注入逻辑。@vanilla-extract/vite-plugin正是连接这一流程与 Vite 的官方插件，它在 Vite 的开发服务器、生产构建与 SSR 场景下统一工作，是 vanilla-extract 在 Vite 生态中的标准集成方式（对应官方文档 Integrations · Vite）。

安装

与官方文档一致，将插件作为开发依赖安装：

npm install --save-dev @vanilla-extract/vite-plugin

插件本体的运行时依赖仅为 @vanilla-extract/integration，并以vite作为 peerDependency（peer 范围^4.0.3 || ^5.0.0）。注意：vanilla-extract 的编译期架构（见下文"原理"一节）依赖于 Vite 自身的模块图与依赖解析能力，因此该插件只能在 Vite 环境中使用，无法脱离 Vite 单独运行。

基础配置

在项目根目录的vite.config.js（或vite.config.ts）中引入插件并加入plugins数组：

// vite.config.js import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin'; export default { plugins: [vanillaExtractPlugin()] };

配置完成后，项目中形如styles.css.ts的文件即可被识别并编译。仓库的 test-helpers/src/startFixture/vite.ts 给出了测试环境中的真实用法：plugins: [vanillaExtractPlugin(), mode === 'development' && inspect()]，即在开发模式叠加vite-plugin-inspect观察编译产物，并配合build.cssCodeSplit: false、build.minify: false等选项生成便于断言的 CSS 快照。

插件在 Vite 生命周期中的位置

从 packages/vite-plugin/src/index.ts 的实现可以看到，插件名称为vanilla-extract，它实现了 Vite 的多个核心钩子：

• config：将@vanilla-extract/css、@vanilla-extract/css/fileScope、@vanilla-extract/css/adapter加入ssr.external，确保 SSR 场景下这些包不会被错误打包；
• configResolved：拿到最终的 Vite 配置（config），并通过getPackageInfo(config.root)读取项目包名（用于 file scope 哈希）；
• buildStart：创建编译核心compiler（见 packages/integration/src/compiler.ts 中的createCompiler）；
• transform：拦截所有匹配cssFileFilter（正则/\.css\.(js|cjs|mjs|jsx|ts|tsx)(\?used)?$/，见 packages/integration/src/filters.ts）的文件，执行编译并替换其内容；
• resolveId/load：为编译产物对应的虚拟 CSS 模块（xxx.css.ts.vanilla.css）提供解析与内容加载；
• buildEnd/closeWatcher：在构建结束或 watch 关闭时释放编译器资源。

配置项

插件接受一个可选的配置对象：

// vite.config.js import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin'; export default { plugins: [ vanillaExtractPlugin({ // configuration }) ] };

当前公开的配置项为identifiers（类型见 packages/vite-plugin/src/index.ts 中的Options接口）。

identifiers

identifiers控制类名、keyframes 名称、CSS 变量等标识符（identifier）的生成格式。可选值如下：

• short：7 位以上的纯哈希标识符，例如hnw5tz3。适用于生产环境，体积最小；
• debug：带可读前缀的标识符，前缀包含所属文件名与可能的规则级调试名（debugId），例如myfile_mystyle_hnw5tz3。适用于开发环境，便于在 DevTools 中定位样式来源；
• 自定义函数：接收一个包含hash、filePath、debugId、packageName四个属性的对象，返回自定义标识符。例如：

vanillaExtractPlugin({ identifiers: ({ hash }) => `prefix_${hash}` });

插件会根据传给打包器的配置自动设定默认值：从 packages/vite-plugin/src/index.ts 的getIdentOption可见，未显式传入时，生产模式（config.mode === 'production'）默认short，其他模式默认debug。

标识符生成机制的源码佐证

标识符的底层生成逻辑在 packages/css/src/identifier.ts 的generateIdentifier中：基于packageName + filePath计算哈希得到fileScopeHash，再拼接当前文件的引用计数（转 base 36）形成基础标识符。当identOption === 'debug'时，会叠加getDevPrefix生成的可读前缀（文件名 + debugId）；当传入自定义函数时，则以{ hash, debugId, filePath, packageName }为参数调用该函数，并对返回值做正则校验（/^[A-Z_][0-9A-Z_-]+$/i），不合法则抛出Identifier function returned invalid indentifier错误。

值得注意的是，"debug 模式注入 debugId"这一步发生在编译前：见 packages/integration/src/transform.ts 的transformSync/transform——当identOption === 'debug'时，会先用@vanilla-extract/babel-plugin-debug-ids（packages/babel-plugin-debug-ids/src/index.ts）对源码做一次 Babel 转换，为style等调用注入调试标识，再执行addFileScope（packages/integration/src/addFileScope.ts），在文件头尾包裹setFileScope/endFileScope，从而让每个.css.ts文件拥有独立的作用域上下文。

unstable_mode（内部选项）

源码中还存在一个带unstable_前缀的内部选项unstable_mode，取值为'transform' | 'emitCss'，默认'emitCss'（见 packages/vite-plugin/src/index.ts）：

• emitCss（默认）：在buildStart中创建编译核心compiler，由其在transform阶段调用compiler.processVanillaFile（packages/integration/src/compiler.ts）产出源码与 CSS 虚拟模块；
• transform：跳过编译器，直接在transform钩子中调用transform（packages/integration/src/transform.ts），以纯文本转换方式处理每个文件。

由于名称带unstable_前缀，该选项不在官方文档公开的稳定配置范围内，实际使用时应优先依赖默认行为。

工作原理：从 .css.ts 到静态 CSS 的编译管线

文档只给出了配置层面的说明，这里结合源码梳理出插件背后的完整编译管线，帮助理解为什么"零运行时"能够成立。

1. 文件拦截与作用域注入

所有匹配cssFileFilter的*.css.{ts,tsx,js,...}文件都会被插件的transform钩子捕获。编译前，源码先经 packages/integration/src/transform.ts 处理：debug 模式下用 Babel 插件注入 debugId，随后 packages/integration/src/addFileScope.ts 根据模块语法（ESM 或 CJS，由mlly的detectSyntax判断）在文件首尾注入setFileScope("<相对路径>", "<包名>")与endFileScope()。这一"文件作用域"决定了每个样式声明的哈希命名空间与归属。

2. 编译核心：processVanillaFile

在默认emitCss模式下，transform钩子将处理后的文件交给compiler.processVanillaFile(absoluteId, { outputCss: true })（packages/integration/src/compiler.ts）。该方法的实现要点：

• 内部 Vite 服务：createCompiler通过vite.createServer在内存中创建一个静默（logLevel: 'silent'）、禁用 HMR 与依赖预构建（optimizeDeps.disabled）的内部 Vite 服务，并挂载"外部化@vanilla-extract/*"与"转换.css.ts"两个内部插件，以复用 Vite 的模块解析能力；
• 执行源码：通过vite-node的ViteNodeRunner真正执行.css.ts文件，同时注入一个自定义 CSS 适配器（cssAdapter），在appendCss、registerClassName、registerComposition等回调中收集每个文件产生的 CSS 对象、本地类名与样式组合信息；
• 模块扫描：利用createModuleScanner沿 Vite 模块图递归收集所有依赖的.css.ts模块及其 watch 文件；
• 生成 CSS 与虚拟导入：对每个 CSS 模块调用 @vanilla-extract/css/transformCss 将 CSS 对象序列化为 CSS 字符串，写入cssCache，并向输出源码中追加import '<file>.vanilla.css';这样的虚拟 CSS 导入语句；
• 导出序列化：通过 packages/integration/src/processVanillaFile.ts 的serializeVanillaModule将模块导出（如style生成的类名、createTheme生成的变量）序列化为可运行的 ESM 代码——仅允许导出普通对象、数组、字符串、数字、null/undefined 以及带有__function_serializer__/__recipe__标记的函数（如 recipe、复杂函数），这正是编译期"把运行逻辑留在构建时"的关键；
• 缓存与失效：结果按filePath + outputCss缓存，借助 Vite 模块节点的lastInvalidationTimestamp判断是否需要重新编译，支持 watch 模式下的增量编译。

3. 虚拟 CSS 模块与 HMR

编译后的文件源码中包含指向.vanilla.css的导入语句，插件的resolveId/load钩子负责处理这些虚拟模块：resolveId在compiler.getCssForFile能查到对应 CSS 时返回绝对路径（保留原 query 以便 HMR），load则把缓存中的 CSS 字符串作为模块内容返回，交由 Vite 的 CSS 管线做最终的样式注入或产物输出。

开发模式下，插件通过configureServer持有 dev server 引用，在transform后遍历watchFiles，对每个 CSS 依赖调用invalidateModule（packages/vite-plugin/src/index.ts）：先使虚拟模块及其依赖失效，再更新lastHMRTimestamp，Vite 据此自动追加?t=时间戳触发热更新——当某个.css.ts修改时，浏览器无需刷新即可获得最新样式。此外buildStart中创建编译器时会过滤掉所有名为vanilla-extract、以remix/react-router开头的插件（removeIncompatiblePlugins），避免编译器内嵌 Vite 服务与这些框架插件互相递归实例化。

常见集成场景与验证

• 开发模式：vite dev下默认使用debug标识符，配合浏览器 DevTools 可直接从类名（如myfile_mystyle_hnw5tz3）反查样式文件与规则名；叠加vite-plugin-inspect可查看每个.css.ts的编译中间产物。
• 生产构建：vite build下自动切换为short哈希标识符，输出最小的 CSS 与 JS；可在构建结果中看到独立的 CSS 文件或按cssCodeSplit拆分的样式 chunk。
• SSR：插件在config阶段将@vanilla-extract/css相关包标记为 SSR 外部依赖，保证服务端渲染时样式声明不会产生运行时副作用。
• watch / 增量构建：compiler实例在多次构建间复用（if (mode !== 'transform' && !compiler)），buildEnd仅在非 watch 模式下关闭编译器，closeWatcher则在 watch 结束时统一释放，兼顾了 watch 场景的性能与资源回收。

仓库的端到端测试（如 tests/e2e/features.playwright.ts、tests/e2e/recipes.playwright.ts）会在 Vite 开发与生产两种模式下启动真实 fixture 并断言生成的 CSS 快照（参见 tests/e2e/features.playwright.ts-snapshots/features-vite--production.css 等文件），这些快照是验证上述编译管线输出稳定性的直接依据。

小结

在 Vite 项目中集成 vanilla-extract 只需两步：安装@vanilla-extract/vite-plugin，并在vite.config的plugins中加入vanillaExtractPlugin()。identifiers配置项负责控制产物体积与可调试性，默认随构建模式自动切换（生产short/ 开发debug），也支持自定义函数做前缀定制。其背后是一套完整的"文件作用域注入 → 内存 Vite 服务执行源码 → CSS 对象收集与序列化 → 虚拟 CSS 模块 → HMR 失效刷新"编译管线，确保了样式在构建期被完整编译为静态 CSS，真正实现零运行时开销。

• 前端
• 开发工具