Next.js中css-loader哈希类名与HTML类名不匹配问题

你的问题核心是css-loader的modules模式被全局应用到了所有CSS文件，包括Tailwind的全局工具类。Tailwind类是直接写在JSX/HTML中的，而css-loader的modules仅能处理通过import styles from './xxx.module.css'引入的类名映射，全局类名不会自动同步替换，导致CSS哈希类与HTML原始类无法匹配。

修复方案： #

1. 拆分CSS规则：区分全局样式与CSS模块

   • Tailwind基础样式、工具类属于全局CSS，不开启modules，保持类名原样；
   • 组件级自定义CSS采用[name].module.css/.module.scss命名，Next.js会自动识别为CSS模块，无需额外配置即可实现类名哈希。

2. 修改next.config.js配置
   移除对所有CSS文件启用modules的规则，拆分全局CSS和CSS模块的处理逻辑：

const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");

const nextConfig = {
    reactStrictMode: true,
    webpack: (config, { buildId, dev, isServer, defaultLoaders, webpack }) => {
        // 移除默认CSS规则避免冲突（Next.js已内置模块与全局CSS处理）
        config.module.rules = config.module.rules.filter(
            rule => !rule.test?.test('.css') && !rule.test?.test('.scss')
        );

        // 全局CSS规则：处理Tailwind等全局样式，不启用modules
        config.module.rules.push({
            test: /\.(css|s[ac]ss)$/i,
            exclude: /\.module\.(css|s[ac]ss)$/i,
            use: [
                !dev ? MiniCssExtractPlugin.loader : 'style-loader',
                'css-loader',
                'postcss-loader',
                'sass-loader',
            ]
        });

        // CSS模块规则：仅处理带.module后缀的文件，启用哈希
        config.module.rules.push({
            test: /\.module\.(css|s[ac]ss)$/i,
            use: [
                !dev ? MiniCssExtractPlugin.loader : 'style-loader',
                {
                    loader: 'css-loader',
                    options: {
                        modules: {
                            localIdentName: "_[hash:base64:5]",
                        },
                    }
                },
                'postcss-loader',
                'sass-loader',
            ]
        });

        config.optimization.minimizer.push(new CssMinimizerPlugin());
        
        config.plugins.push(
            new MiniCssExtractPlugin({
                filename: 'static/css/[contenthash].css'
            })
        );

        return config;
    },
    env: {
        WORDPRESS_BE: process.env.WORDPRESS_BE,
        API_URL: process.env.API_URL,
        ASSET_URL: process.env.ASSET_URL,
        CRYPTO_SECRET_KEY: process.env.CRYPTO_SECRET_KEY,
        API_SAMPLE: process.env.API_SAMPLE,
    },
};

module.exports = nextConfig;

3. 调整Tailwind引入方式
   在全局样式文件（如globals.css）中正常引入Tailwind：

@tailwind base;
@tailwind components;
@tailwind utilities;

然后在_app.js中全局导入该文件：

import '../styles/globals.css';

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

export default MyApp;

4. 组件级CSS使用模块
   自定义组件样式时，命名为ComponentName.module.css，在组件中导入使用：

import styles from './Button.module.css';

function Button() {
  return <button className={styles.button}>Click Me</button>;
}

这样Tailwind全局工具类会保持原始类名，CSS中不会对其哈希；自定义组件CSS模块会生成哈希类名，通过styles.xxx映射确保HTML与CSS类名匹配。

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