如何在React中使用CSS Modules并将样式写在同个.jsx文件中？

算力阿峰

2026-8-28

现成可用方案

最匹配你需求的成熟方案是astroturf，这是一个零运行时的CSS-in-JS实现，完全支持你示例中的标签模板写法，编译阶段会把内联写的样式抽离为独立CSS资源，类名按CSS Modules规则做哈希隔离，没有运行时样式注入的开销，也不存在styled-components常见的类名冲突、样式优先级错乱、SSR注水不一致的问题。你示例里的???直接替换为它导出的css标签即可，标签返回值就是和原生CSS Modules完全一致的类名映射对象：

// Cmp.jsx
import { css } from 'astroturf';

const styles = css`
  .wrapper {
    display: flex;
      
    .name {
      color: blue;
    }
  }
`

export default function Cmp() {
  return (
    <div className={styles.wrapper}>
      <div className={styles.name}>Bob</div>
    </div>
  )
}

同类型备选是vanilla-extract，但它默认要求样式写在独立的.css.ts文件中，要支持jsx文件内联编写需要额外配置插件，适配成本高于astroturf。
不建议直接引入CSS Modules对应的webpack loader内部函数实现：webpack loader的执行逻辑和构建上下文、资源路径、loader执行管道强绑定，本身是设计用来处理独立磁盘文件的，没有暴露可直接处理内联模板字符串的独立调用接口，硬引内部函数会出现上下文缺失、依赖路径不稳定的问题，后续构建工具升级会直接导致功能失效。

自行实现的入手方向

如果要从零实现这个能力，核心是做编译期转换，不要把逻辑放到浏览器运行时，整体可以拆为4个核心模块：

自定义Babel插件：遍历JSX文件的AST，匹配你指定的标签模板调用（比如自定义名为cssModule的标签），提取模板内的原始CSS文本，同时记录当前模板所在的代码位置。
CSS Modules转换：把提取到的原始CSS传入PostCSS，调用postcss-modules完成核心转换，这一步会输出两个结果：一是类名替换为带哈希标识的最终CSS内容，二是原始类名到哈希类名的键值对映射对象。
AST节点替换：把源码中原来的标签模板表达式节点，直接替换为上一步生成的类名映射对象的字面量，这一步做完之后源码里就没有任何标签模板相关的运行时代码了，和你直接写普通CSS Modules导入语句的编译结果完全一致。
构建工具适配插件：写对应webpack/vite的配套插件，收集Babel处理阶段生成的最终CSS内容，把这些内容注入到构建工具的CSS处理管道里，后续走和普通CSS文件一致的压缩、抽离、内容哈希、缓存逻辑即可。

实现注意点：所有CSS解析、类名转换的逻辑必须放在编译阶段完成，不要把PostCSS或者CSS Modules的逻辑打包到前端运行时里，否则会带来额外的包体积开销，也无法复用构建工具自带的CSS优化、缓存能力。

内容的提问来源于stack exchange，提问作者grabantot