# @dr\.pogodin/babel-plugin-react-css-modules 中文文档
规范地址：https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/
版本：8\.0\.0
npm 元数据更新时间：2026-10-10T22:54:41.894Z
中文译文更新时间：2026-11-12T18:37:46.630Z
软件包许可：BSD-3-Clause
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40dr.pogodin/babel-plugin-react-css-modules
原文对照：https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/?lang=original
项目主页：https://dr.pogodin.studio/docs/babel-plugin-react-css-modules
源码仓库：https://github.com/birdofpreyru/babel-plugin-react-css-modules
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：179 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：13 个
- peer 依赖：postcss 8，webpack \>=5\.108
- 首次发布：2020-08-08T22:31:20.582Z
- 最新版本发布：2026-10-10T22:54:41.741Z
- 近 30 天下载量：29012（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 18 个）
## 中文简介
使用编译时间 CSS 模块分辨率将样式Name 转换为类Name .
## 安装
```sh
npm install @dr.pogodin/babel-plugin-react-css-modules
```
也可以使用：`pnpm add @dr.pogodin/babel-plugin-react-css-modules`、`yarn add @dr.pogodin/babel-plugin-react-css-modules`、`bun add @dr.pogodin/babel-plugin-react-css-modules`
## README
# Babel 插件: 反应 CSS 模块
[](https://www.npmjs.com/package/@dr.pogodin/babel-plugin-react-css-modules) [](https://www.npmjs.com/package/@dr.pogodin/babel-plugin-react-css-modules) [](https://app.circleci.com/pipelines/github/birdofpreyru/babel-plugin-react-css-modules) [](https://github.com/birdofpreyru/babel-plugin-react-css-modules) [](https://dr.pogodin.studio/docs/babel-plugin-react-css-modules)
[宝贝](https://babeljs.io/) 高级插件 [CSS 模块](https://github.com/css-modules/css-modules) 支持在 [反应](https://reactjs.org/)数字 :
- 变了 `styleName` jSX 组件的属性 `className` 使用 编译时间 CSS 模块分辨率,允许更清洁地使用 CSS 模块 在反应.
- 对于服务器侧渲染( SSR) 可以替换命名的样式表导入 名称映射对象,并删除匿名样式表导入.
此插件是原版的分叉和进一步发展 [bail-plugin-react-cs-module 组合键](https://www.npmjs.com/package/babel-plugin-react-css-modules) (原始内容 `babel-plugin-react-css-modules` 从2019年起,它就被所有者抛弃了,它不与现代人合作 Webpack 版本).
[](https://github.com/sponsors/birdofpreyru)
### [贡献者](https://github.com/birdofpreyru/babel-plugin-react-css-modules/graphs/contributors)
[](https://github.com/praveenpuglia) [](https://github.com/d-oliveros) [](https://github.com/moonlitusun) [](https://github.com/pturchik) [](https://github.com/birdofpreyru)
## 内容
- [用法实例](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-usage-examples)
- [安装](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-installation)
- [反应](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-react)
- [原生反应](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-react-native)
- [迁移 v7 ⇒ v8](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-migration-v7--v8)
- [配置](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-configuration)
- [插件选项](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-plugin-options)
- [配置语法加载器](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-configurate-syntax-loaders)
- [自定义属性映射](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-custom-attribute)
- [在车盖下](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-under-the-hood)
- [怎么会这样?](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-how-does-it-work)
- [项目历史](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-project-history)
- [`css-loader` 兼容性](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-css-loader-compatibility)
## 用法实例
假设 `style.css` ,在以下示例中编译为CSS模块.
**没有这个插件**
```jsx
import S from './styles.css';
export default function Component() {
return (
Example
Sample text paragraph.
Sample text paragraph with special style.
);
}
```
**使用此插件**
```jsx
import './styles.css';
export default function Component() {
return (
Example
Sample text paragraph.
Sample text paragraph with special style.
);
}
```
**使用此插件和多个样式表**
假设:
- 样式 `container`, (中文(简体) ), `title`,以及 `text` 定义在 `styles-01.css`。 。 。 .
- 样式 `special` 定义于 `styles-02.css`。 。 。 .
- 该插件的 `autoResolveMultipleImports` 选项被启用(默认).
```jsx
import './styles-01.css';
import './styles-02.css';
export default function Component() {
return (
Example
Sample text paragraph.
Sample text paragraph with special style.
);
}
```
如果两个文件, `styles-01.css` 财务报告和审定财务报表 `styles-02.css` 包含相同样式 名称,因此无法自动解析,此插件允许明确 样式表前缀 :
```jsx
import S1 from './styles-01.css';
import S2 from './styles-02.css';
export default function Component() {
return (
Example
Sample text paragraph.
Sample text paragraph with special style.
);
}
```
**使用此插件和运行时间解析**
```jsx
import './styles-01.css';
import './styles-02.css';
export default function Component({ special }) {
let textStyle = 'text';
if (special) textStyle += ' special';
return (
Example
Sample text paragraph.
Sample text paragraph with special style.
);
}
```
如果在编译时没有确切的样式值, 如 此示例,插件将输入必要的代码以正确解决 `styleName` 运行时间(运行时间稍有减少,但否则有效) 精细.
**安全部门改革设想**
考虑此组件, 它使用命名样式表导入以使用 在其他一些方面, 除了简单的造型, _譬如说._ 还显示类名 映射 :
```jsx
import S from './style.css';
export default function Component() {
return (
{JSON.stringify(S)}
)
}
```
默认情况下, 此插件会将其转换为以下代码( 退出) 转到 Webpack 处理 `./style.scss` 用于实际CSS捆绑, 并产生正确的联署材料产出:
```jsx
import S from './style.css';
export default function Component() {
return (
{JSON.stringify(S)}
)
}
```
对于服务器侧环境,如果你不编译服务器侧代码与Webpack, 你需要替换 `./style.css` 与有效的JS代码。 就是这个 此插件使用 `replaceImport` 选项,其输出:
```jsx
const S = {
container: '12345',
// Other stylesheet keys, if any.
};
export default function Component() {
return (
{JSON.stringify(S)}
)
}
```
**普通JS 需要( ) 支持**
插件工作方式相同 `require('./style.css')` CSS进口.
## 安装
### 反应
- 核心CSS模块功能应在其他地方启用和配置 在您的反应项目中 :
- 赤裸的Webpack看到 [本地 CSS 软件](https://webpack.js.org/guides/native-css)。 。 。 .
- 其他框架则参考其相应的文件.
- 将此插件安装为直接依赖( 在边框中 ,), 当编译时间 `styleName` 解析不可能, 此插件会掉落 返回运行时解析 .
```sh
npm install --save @dr.pogodin/babel-plugin-react-css-modules
```
- 安装 Webpack 至少作为开发依赖:
```sh
npm install --save-dev webpack
```
- 将此插件添加到 Babel 配置 :
```json
{
"plugins": [
["@dr.pogodin/react-css-modules", {
"context": "/your/webpack/compilation/context",
"localIdentName": "[fullhash:base64:6]",
"uniqueName": "output.uniqueName used by Webpack",
}]
]
}
```
**比利时**数字 :
- 这个 `localIdentName` 选项值必须匹配 `localIdentName` 选项 webpack的CSS发电机。 默认情况下, Webpack 使用 `[uniqueName]-[id]-[local]` 促进发展 `[fullhash]` 用于生产建筑 (见: [https://webpack.js.org/guides/native-css/#generator-options 页面存档备份,存于互联网档案馆](https://webpack.js.org/guides/native-css/#generator-options)(三); 我们建议在此明确设定相同的、匹配的数值 插件和 Webpack 生成器的配置,包括 散列摘要类型和长度( l)_譬如说._ `[fullhash:base64:6]`) (中文(简体) ).
- 这个 `fullhash` 由 Webpack 计算,包括 CSS 文件的路径, 相对于 Webpack 的汇编 `context`,则 [输出. 独一无二Name](https://webpack.js.org/configuration/output/#outputuniquename) 数值。 确定设置 `context` 财务报告和审定财务报表 `uniqueName` 此插件的设置 ,并双重检查 Webpack,并通过此插件进行匹配.
- 或者,此插件提供简化而稳定的执行 页:1 `getLocalIdent` 函数(取自选中的旧版本) [装弹机](https://www.npmjs.com/package/css-loader)) (中文(简体) ). 它只支持类名占位符 页:1 [插值Name ()](https://github.com/webpack/loader-utils#interpolatename) 函数 `loader-utils`,但它解决了 CSS 文件路径相对于 离这里最近的 `package.json` 文件,它不因数 `uniqueName` 入于草丛, 它支持增加一个 `package` 占位符,以 页:1 `name` 从最近的值 `package.json` 这些是有用的 图书馆汇编.
你可以用这个 `getLocalIdent` 函数(其工厂,精确地说) 这个:
**在 Webpack 配置内**
```ts
import { localIdentNameFactory } from '@dr.pogodin/babel-plugin-react-css-modules/utils';
export {
module: {
generator: {
'css/module': {
localIdentName: localIdentNameFactory('[fullhash:base64:6]'),
},
},
},
};
```
**在 Babel 配置内**
```ts
import { localIdentNameFactory } from '@dr.pogodin/babel-plugin-react-css-modules/utils';
export {
plugins: [
["@dr.pogodin/react-css-modules", {
localIdentName: localIdentNameFactory('[fullhash:base64:6]'),
// NOTE: No need for `context` and `uniqueName` settings here.
}]
]
};
```
### 原生反应
如果你想让这个工作 在反应土著,你必须允许 自定义导入扩展名,通过 `rn-cli.config.js` 文件 :
```js
module.exports = {
getAssetExts() {
return ["scss"];
}
}
```
也记住,捆绑者会缓存插件和预设等东西. 狦 想要改变你的 `.babelrc` (要添加此插件) 然后您想要添加 `--reset-cache` 旗帜到软件包命令的末尾.
### 迁移 v7 ⇒ v8
[页:1](https://github.com/birdofpreyru/babel-plugin-react-css-modules/releases/tag/v8.0.0) 此插件的版本与现在已贬值的兼容性下降 [装弹机](https://www.npmjs.com/package/css-loader) (用Webpack处理CSS的旧方法),并旨在兼容 [本地 CSS 软件](https://webpack.js.org/guides/native-css) 处理。 迁移:
- 切换到 [本地 CSS 软件](https://webpack.js.org/guides/native-css) 在您的 Webpack 配置中.
- 将此插件升级到 [页:1](https://github.com/birdofpreyru/babel-plugin-react-css-modules/releases/tag/v8.0.0) 版本,并更新其配置:
- 替换 `generateScopedName` 选项 `localIdentName`。 。 。 .
如果您使用字符串值, 请确定设置 `context` 财务报告和审定财务报表 `uniqueName` 此插件的选项 `context` 财务报告和审定财务报表 [输出. 独一无二Name](https://webpack.js.org/configuration/output/#outputuniquename) 数值 由 Webpack 使用.
如果你用过 `getLocalIdent()` 打开 `generateScopedName()` 导出函数 此插件, 替换为新 `localIdentNameFactory()` 输出.
- 请检查webpack和这个生成的类名 插件相互匹配 。 特别是,Webpack包括进入散列 cSS 文件相对于上下文的路径,以及 [输出. 独一无二Name](https://webpack.js.org/configuration/output/#outputuniquename) 值,很容易犯错,最后会用Webpack和这个 插件获取这些参数的不同值 .
## 配置
### 插件选项
这些是有效的插件选项 。 所有都是可选的,但总体配置 默认值可能不起作用 你吗.
- `context` —— 说 **字符串** - 必须匹配Web包装 [`context`](https://webpack.js.org/configuration/entry-context/#context)。 。 。 . 默认 `process.cwd()`。 。 。 .
- `exclude` —— 说 **字符串** - 排除其他情形的备注 包含文件 _譬如说._,将所有样式排除在 `node_modules`数字 : `exclude: 'node_modules'`。 。 。 .
- `filetypes` —— 说 [配置语法加载器](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-configurate-syntax-loaders) 像糖, 低温和SCSS, 和额外的插件.
- `localIdentName` —— 说 **函数 qq 字符串** ——允许自定义精确 `styleName` 改为 `className` 转换算法。 详情见 [生成范围化名称](https://github.com/css-modules/postcss-modules#generating-scoped-names)。 。 。 . 默认 `[file]__[local]__[hash:base64:6]`。 。 。 .
- `replaceImport` —— 说 **布尔** — 替换/删除样式表 用于服务器侧渲染目的导入. [详见下文](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-server-side-rendering)。 。 。 . 默认 _虚假_。 。 。 .
- `handleMissingStyleName` —— 说 `ignore` | `throw` | `warn` —— 说 确定未定义 CSS 模块(使用 `styleName` 没有定义 CSS 模块). 默认 `"throw"`。 。 。 .
- `attributeNames` —— 说 [自定义属性映射](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-custom-attribute)
- `skip` —— 说 **布尔** - 如果没有匹配, 是否应用插件 `attributeNames` 在文件中找到。 默认 _虚假_。 。 。 .
- [转换](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/#readme-transform) —— 说 **函数** - 如果提供,则每个 CSS 源由 插件将随其路径通过此函数, 并使用此插件的选项, 以及此函数的输出 取代原来的CSS.
- `autoResolveMultipleImports` —— 说 **布尔** ——允许多个 匿名导入,如果`styleName` 只存在于其中之一。 默认 _真实_。 。 。 .
### 配置语法加载器
添加对不同 CSS 语法( 如 SCSS) 的支持, 执行以下功能 两个步骤:
1. 添加数据 [posts 语法加载器](https://github.com/postcss/postcss#syntaxes) 作为一种发展依赖:
```bash
npm install postcss-scss --save-dev
```
2. 添加一个 `filetypes` 语法映射到 Babel 插件配置 . 例如,常设委员会:
```json
"filetypes": {
".scss": {
"syntax": "postcss-scss"
}
}
```
可选指定额外插件 :
```json
"filetypes": {
".scss": {
"syntax": "postcss-scss",
"plugins": [
"postcss-nested"
]
}
}
```
> 注: [`postcss-nested`](https://github.com/postcss/postcss-nested) 添加为仅用于演示目的的额外插件。 这不是 所需时间 [`postcss-scss`](https://github.com/postcss/postcss-scss) 因为SCSS已经支持筑巢.
Postcs 插件可以通过在配置内的数组中将名称和选项对象包裹来指定选项 :
```json
"plugins": [
["postcss-import-sync2", {
"path": ["src/styles", "shared/styles"]
}],
"postcss-nested"
]
```
### 转换
```ts
function transform(cssSource, cssSourceFilePath, pluginOptions): string
```
转换功能,如果提供作为 `transform` 此插件的选项, 每个装入的 CSS 源将调用三个参数:
- `cssSource` —— 说 **字符串** - 装入CSS的密码.
- `cssSourceFilePath` —— 说 **字符串** — 加载 CSS 文件的路径 .
- `pluginOptions` —— 说 **对象** —— 此插件的选项 .
它应该返回一个字符串,即实际使用的CSS代码.
### 自定义属性
您可以使用 `attributeNames` 选项.
这是一个对象, 其中密钥是源属性名称, 值是目的地 属性名称.
例如 [< 纳夫林克>](https://github.com/ReactTraining/react-router/blob/master/packages/react-router-dom/docs/api/NavLink.md) 构成部分从 [反应路由器](https://github.com/ReactTraining/react-router) 有一个 `activeClassName` 属性以接受额外的类名。 你们可以 设定 `"attributeNames": { "activeStyleName": "activeClassName" }` 来改变它.
默认 `styleName` ⇒ `className` 转变 **不会** 受影响 由一个 `attributeNames` 无值 `styleName` 键。 当然可以 `{ "styleName": "somethingOther" }` 更改,或使用 `{ "styleName": null }` 来禁用它.
### 服务器系统渲染
若为 `replaceImport` 设置了旗帜, 此插件将删除或替换原始 样式表导入, 用于服务器侧渲染 :
```js
// Anonymous imports are removed from the code:
import 'path/to/style.css';
// Default and named imports are replaced in the following manner:
// Before:
import styles, {
className,
otherClassName as alias,
} from 'path/to/style.css';
// After:
const styles = {
className: 'generatedClassName',
otherClassName: 'otherGeneratedClassName',
},
className = 'generatedClassName',
alias = 'otherGeneratedClassName';
// Also this kind of import:
import * as style from 'path/to/style.css';
// is replaced by:
const style = {
className: 'generatedClassName',
otherClassName: 'otherGeneratedClassName',
};
```
## 在车盖下
### 怎么会这样?
此插件执行以下操作 :
1. 构建每个文件所有样式表导入的索引(文件导入 `.css`,以及其它配置的 CSS 扩展名.
2. 用途 [员额](https://github.com/postcss/postcss) 来解析匹配 CSS文件进入CSS模块引用查询.
3. 横穿所有 [联合来文十](https://facebook.github.io/react/docs/jsx-in-depth.html) 要素声明.
4. 解析 `styleName` (和/或其他配置的)属性值输入 匿名并命名为 CSS 模块引用.
5. 查找匹配 CSS 模块引用的 CSS 类名称 :
- 若为 `styleName` 值为字符串字元,生成字符串字元值.
- 若为 `styleName` 值是一个 [`jSXExpressionContainer`](https://babeljs.io/docs/en/next/babel-types.html#jsxexpressioncontainer), (中文(简体) ), 使用帮助函数( e)[`getClassName`](https://npmcn.com/package/%40dr.pogodin/babel-plugin-react-css-modules/src/getClassName.js)(中文(简体) ) 用于构建 `className` 运行时值.
6. 删除 `styleName` 属性.
7. 附加结果 `className` 改为现有 `className` 价值 (创建) `className` 属性,如果不存在.
8. 与 `replaceImport` 特性启用,它也删除匿名 样式导入,并用相应的 不断申报.
### 项目历史
此插件是原版的分叉和进一步发展 [bail-plugin-react-cs-module 组合键](https://www.npmjs.com/package/babel-plugin-react-css-modules)。 。 。 .
- 原插件自2019年起被所有者废弃, 并且自2020年起不与现代Webpack版本合作.
- 这个于2020年创建的叉子接受定期维护, 与最新的Webpack版本合作,并获得必要的新功能.
原插件寄存器中没有提及此分叉, 因为 原插件的所有者从他的 并禁止这个叉子的作者在其中发表进一步的评论—— 他没有时间去关心他那破烂的插件, 但他找到一个时间去破坏 用户找到工作选择的机会.
### `css-loader` 兼容性
原始插件, 及其 v8 之前的版本 与现在已贬值的兼容性 [装弹机](https://www.npmjs.com/package/css-loader) (处理CSS的遗留方式) 由 Webpack 替换为 [本地 CSS 软件](https://webpack.js.org/guides/native-css)) (中文(简体) ). 如果你还需要工作 `css-loader` 在您的项目中,请咨询 页:1 [`css-loader` 兼容性](https://github.com/birdofpreyru/babel-plugin-react-css-modules/tree/v7.1.0#css-loader-compatibility) 用于插件版本的表格.
## 常见问题
### @dr\.pogodin/babel-plugin-react-css-modules 是什么？
使用编译时间 CSS 模块分辨率将样式Name 转换为类Name \.
### 如何安装 @dr\.pogodin/babel-plugin-react-css-modules？
在项目目录运行 npm install @dr\.pogodin/babel-plugin-react-css-modules，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：postcss（8）、webpack（\>=5\.108）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @dr\.pogodin/babel-plugin-react-css-modules 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @dr\.pogodin/babel-plugin-react-css-modules 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @dr\.pogodin/babel-plugin-react-css-modules 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @dr\.pogodin/babel-plugin-react-css-modules 可以商用吗？
@dr\.pogodin/babel-plugin-react-css-modules 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。
### @dr\.pogodin/babel-plugin-react-css-modules 的下载量有多少？
根据 npm 官方下载统计，@dr\.pogodin/babel-plugin-react-css-modules 在 2026/10/13 – 2026/11/11 这 30 天内被下载 29,012 次，日均约 967 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @dr\.pogodin/babel-plugin-react-css-modules 还在维护吗？
最新版本 8\.0\.0 发布于 2026/10/11（1 个月前）；至今共发布 66 个版本，其中过去 12 个月发布了 18 个；首次发布于 2020/08/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。