客户端渲染

EffCSS 已在客户端自动运行，无需您进行任何操作。然而，通常用于服务器端渲染的样式水合机制，也可以通过 vite-plugin-effcss 插件用于客户端渲染 (CSR)。

该插件通过 Vite SSR 管道 捕获 EffCSS 生成的 CSS，并将其内联到 HTML 中。由于样式水合机制，它可以消除 FOUC 并加快首次渲染速度。该插件在开发模式和构建模式下均可正常工作，且无需任何额外依赖项（无需 esbuild、tsx 或任何额外的加载器）。

零配置 — 无需任何选项即可运行。只需将其添加到您的插件数组即可。

CSR专用 — 对于SSR/SSG，请手动使用serialize()和serializeMeta()。详情请参阅服务器端渲染

插件使用方法

首先，您需要在项目中安装该插件：

bash

npm install vite-plugin-effcss --save-dev

EffCSS 被声明为对等依赖项——请确保它已安装在您的项目中：
bash
npm install effcss

然后将其添加到 Vite 配置中：

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import effcss from 'vite-plugin-effcss';

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

在 HTML 中添加占位符（可选——如果使用占位符，则会显示 </head>）：

html

<head>
  <!-- EFFCSS_INJECT -->
</head>

就是这样。该插件会捕获所有由 EffCSS 生成的 CSS 并将其内联到您的 HTML 中。

请注意，该插件不管理 prefix、minify 和其他 EffCSS 设置——这些设置需要通过 configure() 函数在您的源代码中进行配置。

// src/effcss-config.ts
import { configure } from 'effcss';

configure({
  prefix: 'my',
  minify: true,
});

选项

该插件支持以下选项：

Option	Type	Default	Description
`verbose`	`boolean`	`false`	详细日志记录
`entry`	`string`	—	显式入口点（例如 `/src/main.tsx`）。如果省略，则会从 `index.html` 中的 `<script type="module" src="...">` 自动检测。
`placeholder`	`string`	`'<!-- EFFCSS_INJECT -->'`	要替换为 `<style>` 的 HTML 占位符
`injectTo`	`'head' \| 'head-prepend' \| 'body'`	`'head'`	如果未找到占位符，则回退注入位置
`injectMeta`	`boolean`	`true`	将 `serializeMeta()` 注入为 `<script>`，并包含 JSON 元数据

工作原理

                    buildStart()
                          │
                 ┌─────────┴─────────┐
                 │                   │
                 ▼                   ▼
           Server exists?      Server null?
           (dev mode)          (build mode)
                 │                   │
                 ▼                   ▼
      write tmp .ts file     createServer() + virtual module
      → ssrLoadModule        → ssrLoadModule('effcss:capture')
                 │                   │
                 └───────┬───────────┘
                         ▼
               mod.css + mod.meta
                         │
                         ▼
               transformIndexHtml
               → inject <style> + <script>

该插件会创建一个捕获模块，其功能如下：

导入 EffCSS（用于访问 serialize() / serializeMeta()）
导入您的入口点 — 用于执行和注册样式
调用 serialize() — 将最终的 CSS 和元数据捕获为字符串
通过 transformIndexHtml 将结果内联到您的 HTML 中

开发模式 — 使用现有的 ViteDevServer 和一个临时的 .ts 文件，然后清理该文件。

构建模式 — 通过 createServer() 创建一个临时的 Vite 开发服务器，注册一个带有 resolveId / load 钩子的虚拟 'effcss:capture' 模块，通过 ssrLoadModule() 加载该模块，然后关闭服务器。用户插件（React、Vue 等）已包含在内，以便正确转换 JSX、SVG 和 CSS 导入。该插件将自身从嵌套服务器中排除，以防止无限递归。

技术说明

Vite: ^5.0.0 || ^6.0.0
EffCSS: ^5.4.0
运行时: EffCSS 保留在浏览器包中。

客户端渲染 ​

插件使用方法 ​

选项 ​

工作原理 ​

技术说明 ​

客户端渲染

插件使用方法

选项

工作原理

技术说明