# @griffel/babel-preset 中文文档

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

版本：1\.9\.2
npm 元数据更新时间：2026-09-23T14:46:06.712Z
中文译文更新时间：2026-11-17T01:46:12.912Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：78.8 kB，39 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2022-01-24T09:32:18.675Z
- 最新版本发布：2026-09-23T14:46:06.491Z
- 近 30 天下载量：9896（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 10 个）

## 中文简介

Babel 预设了 Griffel 的构建时间变换

## 安装

```sh
npm install @griffel/babel-preset
```

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

## README

# Griffel 的 Babel 预设

用于构建时间转换的 Babel 预设 [`@griffel/react`](https://npmcn.com/package/%40griffel/react)。 。 。 .

-   [安装](https://npmcn.com/package/%40griffel/babel-preset/#readme-install)
-   [使用量](https://npmcn.com/package/%40griffel/babel-preset/#readme-usage)
    -   [从自定义包导入 Griffel](https://npmcn.com/package/%40griffel/babel-preset/#readme-importing-griffel-from-custom-packages)
    -   [配置 Babel 设置](https://npmcn.com/package/%40griffel/babel-preset/#readme-configuring-babel-settings)
    -   [配置模块评价](https://npmcn.com/package/%40griffel/babel-preset/#readme-configuring-module-evaluation)
-   [变换](https://npmcn.com/package/%40griffel/babel-preset/#readme-transforms)
-   [示例](https://npmcn.com/package/%40griffel/babel-preset/#readme-example)
-   [从代码访问 CSS 输出](https://npmcn.com/package/%40griffel/babel-preset/#readme-access-css-output-from-code)
-   [解决问题](https://npmcn.com/package/%40griffel/babel-preset/#readme-troubleshooting)
    -   [模块评价](https://npmcn.com/package/%40griffel/babel-preset/#readme-module-evaluation)

> \[叹息\] 我们不建议直接使用这个预设,它打算被其他工具使用,比如: [网络包装加载器](https://npmcn.com/package/%40griffel/webpack-loader)。 。 。 .

## 安装

```bash
yarn add --dev @griffel/babel-preset
# or
npm install --save-dev @griffel/babel-preset
```

## 使用量

`.babelrc`

```json
{
  "presets": ["@griffel"]
}
```

### 从自定义包导入 Griffel

```js
import { makeStyles } from 'custom-package';
// 👇 custom import names are also supported
import { createStyles } from 'custom-package';
```

默认情况下,预设处理从 `@griffel/react` 打开 `@fluentui/react-components`,用于处理自定义包设置的导入,应当被调整:

```json
{
  "presets": [
    [
      "@griffel",
      {
        "modules": [{ "moduleSource": "custom-package", "importName": "makeStyles" }]
      }
    ]
  ]
}
```

> **说明**:"海关包装"应再出口 `__styles` 函数从 `@griffel/react`

### 配置 Babel 设置

如果您需要指定自定义的 Babel 配置, 您可以将它们传递给 `babelOptions`。这些选项将被预设在解析和评价模块时使用.

```json
{
  "presets": [
    [
      "@griffel",
      {
        "babelOptions": {
          "plugins": ["@babel/plugin-proposal-class-static-block"],
          "presets": ["@babel/preset-typescript"]
        }
      }
    ]
  ]
}
```

### 配置模块评价

```json
{
  "presets": [
    [
      "@griffel",
      {
        "evaluationRules": []
      }
    ]
  ]
}
```

一套规则,定义了匹配的文件在评价期间将如何被转换. `EvalRule` 是一个具有两个字段的天体:

-   测试是正则表达式或函数 `(path: string) => boolean`
-   动作是 `Evaluator` 函数,“ignore”或导出模块的名称 `Evaluator` 函数为 **默认** 导出

_若为 `test` 规则适用于所有文件._

最后匹配的规则用于转换. 如果一个文件的最后一个匹配动作是“ ignoore ” , 该文件将按原样被评估, 因此文件不得包含任何无法在节点环境中执行的 js 代码( 对于任何 lib 中通常都是真实的) `node_modules`) (中文(简体) ).

如果您需要编辑某些模块 `/node_modules/` (可以在单列波项目中出现这种情况),建议在模块基础上逐个模块进行,以进行更快的转换,例如忽略: `/node_modules[\/\\](?!some-module|other-module)/`。 。 。 .

默认设置为:

```js
module.exports = {
  presets: [
    [
      '@griffel',
      {
        evaluationRules: [
          {
            action: require('@griffel/babel-preset').shakerEvaluator,
          },
          {
            test: /[/\\]node_modules[/\\]/,
            action: 'ignore',
          },
        ],
      },
    ],
  ],
};
```

## 变换

此预设旨在为 `@griffel/react`,它同时支持ES模块和CommonJS,因此可以在TypeScript之后的后处理中使用.

此预设所应用的变换允许剥离运行时间部分 `makeStyles()` 并改进业绩.

## 示例

变换

```js
import { makeStyles } from '@griffel/react';

const useStyles = makeStyles({
  root: { color: 'red' },
});
```

大约是

```js
import { __styles } from '@griffel/react';

const useStyles = __styles(/* resolved styles */);
```

## 从代码访问 CSS 输出

可以配置预设以返回文件的所有评价样式. 这个 元数据外观如下:

```ts
const output = {
  // makeStyles
  cssEntries: {
    // by each hook
    useStyles1: {
      // by each slot
      root: [".fxxxxx { color: 'red' }"],
    },
    useStyles2: {
      root: [".fxxxxx { color: 'red' }"],
    },
  },
  // makeResetStyles
  cssResetEntries: {
    // by each hook
    useResetStyles1: [".fxxxxx { color: 'red' }"],
    useResetStyles2: [".fxxxxx { color: 'red' }"],
  },
};
```

用于代码中的程序转换,以便其他工具可以重新使用,而无需额外步骤来确定 输出样式

```ts
import { griffelPreset, BabelPluginMetadata } from '@griffel/babel-preset';

const babelFileResult = Babel.transformFromAstSync(babelAST, sourceCode, {
  babelrc: false,
  configFile: false,
  presets: [[griffelPreset, { generateMetadata: true }]],

  filename: options.filename,

  sourceMaps: options.enableSourceMaps,
  sourceFileName: options.filename,
  inputSourceMap: options.inputSourceMap,
});

// metadata
console.log(babelFileResult.metadata as unknown as BabelPluginMetadata);
```

## 解决问题

本节主要介绍如何排除这首预设在 [微软/流体](https://github.com/microsoft/fluentui) 复发. 然而,这些概念并没有与重新布置相结合.

### 模块评价

预设使用来自 [林纳利亚](https://github.com/callstack/linaria) 评价运行时间 `makeStyles`。 。 。 . [Linaria 调试文档可以帮助这里](https://github.com/callstack/linaria/blob/master/CONTRIBUTING.md#debugging-and-deep-dive-into-babel-plugin)。 。 。 .

可用以下环境变量激活调试输出 :

```sh
$ DEBUG=linaria\* LINARIA_LOG=debug yarn build
```

在Windows上,需要设置环境变量通过 [`set`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) 或您可以使用 `cross-env`,例如:

```sh
$ cross-env DEBUG=linaria\* LINARIA_LOG=debug yarn build
```

调试输出将包括:

-   编译代码
-   评估代码
-   显示代码被震动的 AST `@linaria/shaker`

## 常见问题

### @griffel/babel-preset 是什么？

Babel 预设了 Griffel 的构建时间变换

### 如何安装 @griffel/babel-preset？

在项目目录运行 npm install @griffel/babel-preset，或使用 pnpm add / yarn add / bun add。

### @griffel/babel-preset 支持 TypeScript 吗？

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

### @griffel/babel-preset 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @griffel/babel-preset 可以商用吗？

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

### @griffel/babel-preset 的下载量有多少？

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

### @griffel/babel-preset 还在维护吗？

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

