Next.js自定义配置下组件级CSS Module样式不生效如何解决

优先修复现有代码语法错误 #

你的CSS文件存在基础语法问题，普通CSS属性值不需要加双引号，直接写属性值即可，错误写法会导致样式直接被浏览器忽略：

/* 错误写法 */
.test {
    color: "red";
}

/* 正确写法 */
.test {
    color: red;
}

不同文件的配置要求 #

1. 基础配置规则（Next.js 9.3+ 版本） #

Next.js 9.3及以上版本默认原生支持.module.css后缀的CSS Module，不需要额外安装css-loader、style-loader等依赖，只要文件名符合命名规则即可自动启用：

• 不要在next.config.js中手动添加CSS相关webpack规则覆盖内置配置，默认配置已经支持CSS Module，手动添加反而会导致类名哈希编译失效
• 不要将cssModules配置项设为false，该配置默认开启

2. _app.js 配置要求 #

自定义_app.js是Next.js加载全局样式和组件样式的入口，只需要保证文件结构符合官方规范即可，不需要额外加CSS相关配置：

// pages/_app.js 标准结构
export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

注意：全局非Module的CSS文件只能在_app.js中引入，组件级.module.css文件直接在对应组件文件内引入即可，不需要在_app.js重复引入。

3. _document.js 配置要求 #

_document.js仅负责服务端渲染的HTML文档结构，不需要在此文件内引入任何CSS文件，也不需要添加任何CSS加载相关配置，只要保证结构中包含必要的渲染节点即可：

// pages/_document.js 标准结构
import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html lang="zh-CN">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

禁止在_document.js中手动添加style标签、link标签引入CSS，也不要删除内置的NextScript节点，否则会导致编译后的样式无法正常注入页面。

4. 自定义server.js 配置要求 #

使用自定义server时，必须保证所有非自定义路由的请求都交给Next.js内置的请求处理器处理，不要自行配置静态资源路由拦截CSS等文件请求，否则会返回未编译的原始CSS文件，导致Module类名哈希失效：

// 自定义server.js 标准示例（以Express为例）
const express = require('express')
const next = require('next')

const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  const server = express()
  // 此处添加你的自定义路由逻辑
  // 所有未匹配自定义路由的请求统一交给Next处理
  server.all('*', (req, res) => {
    return handle(req, res)
  })

  server.listen(3000, (err) => {
    if (err) throw err
    console.log('> Service started on http://localhost:3000')
  })
})

• 不要通过express.static配置静态目录指向Next.js的项目源码目录，编译后的静态资源由Next.js自行路由处理

其他排查点 #

• 确认CSS Module文件名严格以.module.css结尾，大小写完全匹配，不要写成.Module.css、.module.CSS等格式，Next.js通过后缀名识别是否启用CSS Module编译
• 确认组件内引入CSS Module的相对路径正确，同目录下文件使用./xxx.module.css路径引入
• 打开浏览器开发者工具检查对应DOM节点的类名：如果类名是组件名_类名__哈希值格式（比如NavigationButtons_test__abc12），说明CSS Module编译正常，样式不生效是属性写法错误或者被其他样式覆盖；如果类名没有正确加上哈希格式，说明编译环节出问题，优先检查自定义server和webpack配置是否覆盖了内置规则

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