Gatsby 默认不支持 CSS Modules，需安装并配置 gatsby-plugin-css-modules 插件，且须确保文件名含 .module.css、使用解构导入、JSX 中通过 styles.xxx 引用类名，并在 SSR 阶段同步配置以避免样式闪动。
为什么直接 import "./styles.module.css" 有时不生效
不是文件路径写错，也不是组件没重载——根本原因是 Gatsby 默认不处理 .module.css 后缀的模块化 CSS，除非你明确启用了对应插件。Webpack 本身不会自动识别并启用 CSS Modules，Gatsby 也不在默认配置里打开它。你 import 的文件会被当成普通 CSS 加载，类名不会哈希化，className={styles.xxx} 解构出来的变量是空对象或 undefined。
必须安装并启用 gatsby-plugin-css-modules
这是最轻量、最直接的方案，无需改构建链路，只补一层声明式开关：
- 运行
npm install gatsby-plugin-css-modules（或yarn add gatsby-plugin-css-modules） - 在
gatsby-config.js的plugins数组中添加该插件：module.exports = { plugins: [ `gatsby-plugin-css-modules`, // 其他插件... ] } - 插件默认匹配所有
*.module.css和*.module.scss文件，无需额外配置
import 语句和类名使用必须严格匹配规则
插件启用后，CSS Modules 行为才真正激活，但写法稍有不慎就会失效：
- 文件名必须含
.module.css（如button.module.css），.css或.scss不会启用模块化 - 导入时必须用解构或命名导入：
import styles from "./button.module.css"，不能用import "./button.module.css"（后者只是全局注入） - JSX 中必须通过
className={styles.primary}使用，不能写死className="primary" - 如果同时用了 Sass，确保
gatsby-plugin-sass和gatsby-plugin-css-modules共存——前者处理语法，后者接管模块化逻辑
容易被忽略的 SSR 一致性陷阱
即使插件装了、写法对了，服务端渲染（SSR）阶段仍可能丢失样式类名映射——因为 gatsby-plugin-css-modules 默认只作用于客户端。解决方法是在 gatsby-ssr.js 中手动导出同名插件配置：
立即学习“前端免费学习笔记（深入）”；
创建或编辑 gatsby-ssr.js，加入：
exports.onCreateWebpackConfig = ({ actions }) => {
actions.setWebpackConfig({
module: {
rules: [
{
test: /\.module\.(css|sass|scss)$/,
use: [
{ loader: "style-loader" },
{
loader: "css-loader",
options: { modules: true }
}
]
}
]
}
})
}或者更稳妥的做法：直接在 gatsby-config.js 中给插件传 options，让它同时影响 SSR 阶段（部分版本需显式指定）。
否则，首屏 HTML 中 class 名可能是原始字符串，而客户端 hydration 后变成哈希名，导致样式闪动或错位——这不是 bug，是模块化 CSS 在 SSR 场景下未对齐的典型表现。
