# @griffel/vite-plugin 中文文档

规范地址：https://npmcn.com/package/%40griffel/vite-plugin/

版本：1\.0\.1
npm 元数据更新时间：2026-09-23T14:44:16.788Z
中文译文更新时间：2026-11-17T00:43:02.559Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40griffel/vite-plugin
原文对照：https://npmcn.com/package/%40griffel/vite-plugin/?lang=original
项目主页：https://github.com/microsoft/griffel#readme
源码仓库：https://github.com/microsoft/griffel

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：30.2 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：vite ^8\.0\.0
- 首次发布：2024-01-23T11:03:13.883Z
- 最新版本发布：2026-09-23T14:44:16.617Z
- 近 30 天下载量：15510（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 4 个）

## 中文简介

为 Griffel 进行 CSS 提取的虚拟插件

## 安装

```sh
npm install @griffel/vite-plugin
```

也可以使用：`pnpm add @griffel/vite-plugin`、`yarn add @griffel/vite-plugin`、`bun add @griffel/vite-plugin`

## README

# 在 Griffel 中执行 CSS 提取的 Vite 插件

用于执行 CSS 提取的 Vite 插件 [`@griffel/react`](https://npmcn.com/package/%40griffel/react)。 。 。 .

-   [安装](https://npmcn.com/package/%40griffel/vite-plugin/#readme-install)
-   [使用量](https://npmcn.com/package/%40griffel/vite-plugin/#readme-usage)
-   [选项](https://npmcn.com/package/%40griffel/vite-plugin/#readme-options)
-   [如何运作](https://npmcn.com/package/%40griffel/vite-plugin/#readme-how-it-works)
    -   [开发模式](https://npmcn.com/package/%40griffel/vite-plugin/#readme-development-mode)
-   [洞穴](https://npmcn.com/package/%40griffel/vite-plugin/#readme-caveats)

## 安装

```bash
yarn add --dev @griffel/vite-plugin
# or
npm install --save-dev @griffel/vite-plugin
```

> ++ 插件需要 Vite 8 或以上 和 `@griffel/react` 1.7.7或以上 (中文(简体) ).

## 使用量

在您的 Vite 配置中, 添加插件 :

```js
import { defineConfig } from 'vite';
import { griffel } from '@griffel/vite-plugin';

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

自动插件 :

-   变换 `makeStyles()`, (中文(简体) ), `makeResetStyles()`,以及 `makeStaticStyles()` 构建时的呼叫
-   从这些调用中提取 CSS 到 Vite 处理的样式表
-   按特异性桶、媒体查询和容器查询排序 CSS 规则

不需要额外的配置: CSS 由 Vite 自己处理, 所以 `<link>` 生产中的标签照常使用。 单位 开发插件不会做任何事情, Griffel 在运行时处理样式.

## 选项

```js
griffel({
  // Files to process (default: /\.[cm]?[jt]sx?$/)
  include: /\.[cm]?[jt]sx?$/,
  // Files to skip, nothing is excluded by default as dependencies may also use Griffel
  exclude: undefined,

  // Compare function for sorting media queries (default: @griffel/core's defaultCompareMediaQueries)
  compareMediaQueries: myCompareFunction,

  // Compare function for sorting container queries (default: same comparator as compareMediaQueries)
  compareContainerQueries: myCompareFunction,

  // Override the resolver used to resolve imports inside evaluated modules
  resolverFactory: myResolverFactory,

  // A salt that is added to generated class names
  classNameHashSalt: '',

  // Modules that export Griffel functions (default: ["@griffel/core", "@griffel/react", "@fluentui/react-components"])
  importsToTransform: ['@griffel/react'],

  // Functions that should be treated as Griffel style calls
  functionsToTransform: ['makeStyles', 'makeResetStyles', 'makeStaticStyles'],

  // Rules that define how matched files are transformed during the evaluation
  evaluationRules: undefined,

  // Collect and log timing stats once a build is finished
  collectStats: false,

  // Collect and log dependencies that slow down evaluation (CJS modules, "export *" barrels)
  collectPerfIssues: false,
});
```

## 如何运作

插件是一对 Vite 插件 :

-   `griffel:transform` 运行于其他变换之前( e)`enforce: 'pre'`)并用评估结果取代Griffel的电话 结果。 取取的CSS是从一个被转换出的文件所导入的虚拟CSS模块得到的.
-   `griffel:extract` 在生产CSS资产后运行(`enforce: 'post'`)并将所有块的 CSS 合并为 输入点的资产,排序和删除途中的规则.

两者仅适用于生产建筑.

Griffel依赖于 CSS 规则的顺序:规则按照样式桶组合,只能被规则从 同一桶或一个后桶。 随着每个块的Vite发布样式表,懒惰加载块的规则将会被应用 在申请规则之后 插件通过将所有 Griffel 规则移动到单个样式表来避免它, this 匹配指定的行为 `griffel` 块入 `@griffel/webpack-plugin`。 。 。 .

### 开发模式

插件仅适用于生产构建( E)`apply: 'build'`) (中文(简体) ). Dev 服务器没有捆绑步骤,所以没有 样式表可以将规则提取到其中,而Griffel在运行时处理样式,因为它没有插件.

## 洞穴

-   不是ES模块的文件被跳过,其中的Griffel呼叫会由运行时间处理.
-   如果一个项目有多个切入点,每个切入点都会得到所有提取出Griffel CSS的副本.

## 常见问题

### @griffel/vite-plugin 是什么？

为 Griffel 进行 CSS 提取的虚拟插件

### 如何安装 @griffel/vite-plugin？

在项目目录运行 npm install @griffel/vite-plugin，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vite（^8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @griffel/vite-plugin 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @griffel/vite-plugin 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @griffel/vite-plugin 可以商用吗？

@griffel/vite-plugin 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @griffel/vite-plugin 的下载量有多少？

根据 npm 官方下载统计，@griffel/vite-plugin 在 2026/10/17 – 2026/11/15 这 30 天内被下载 15,510 次，日均约 517 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @griffel/vite-plugin 还在维护吗？

最新版本 1\.0\.1 发布于 2026/09/23（1 个月前）；至今共发布 19 个版本，其中过去 12 个月发布了 4 个；首次发布于 2024/01/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

