我对 CSS Modules 的深度思考

1. .module.css 文件匹配是默认行为吗？如何修改规则？

默认行为差异

• Webpack：不是默认行为，需通过 css-loader 显式启用 CSS Modules。
• Vite：是默认行为，所有以 .module.css 结尾的文件自动启用 CSS Modules。

如何自定义文件匹配规则？

以 Webpack 为例，修改 webpack.config.js：

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/, // 匹配所有 .css 文件
        use: [
          'style-loader',
          {
            loader: 'css-loader',
            options: {
              modules: {
                auto: (resourcePath) => {
                  // 自定义规则：文件名包含 .module.css 或路径在 /components/ 下时启用
                  return resourcePath.includes('.module.css') || 
                         resourcePath.includes('/components/');
                },
                localIdentName: '[hash:base64:8]' // 哈希配置
              }
            }
          }
        ]
      }
    ]
  }
};

• 关键配置：modules.auto 函数返回 true 时启用 CSS Modules。
• Vite 配置：在 vite.config.js 中通过 css.modules 字段调整：

  // vite.config.js
  export default {
    css: {
      modules: {
        // 所有 .css 文件都启用 CSS Modules（覆盖默认行为）
        auto: true, 
        // 自定义生成规则
        generateScopedName: '[name]__[local]--[hash:6]'
      }
    }
  }
  

---

2. localIdentName 配置规则详解

占位符含义

占位符	含义
[name]	原文件名（不含后缀），如 Button.module.css → Button
[local]	原始 CSS 类名（开发者编写的类名，如 .btn）
[hash]	基于文件内容生成的哈希字符串（默认 base64 编码）
[folder]	文件所在文件夹名称（部分构建工具支持）
[path]	文件相对路径（如 src/components/Button.module.css → src-components-Button）

哈希控制参数

参数格式	效果	示例
[hash]	默认生成 20 位 base64 字符串	_1x2y3z4
[hash:length]	指定哈希字符串长度	[hash:5] → 1x2y3
[hash:base64:length]	显式指定 base64 编码和长度	[hash:base64:5]
[hash:hex:length]	使用十六进制编码（更短但碰撞概率略高）	[hash:hex:4] → a1b2

经典配置示例

// Webpack 配置
localIdentName: '[name]__[local]___[hash:base64:5]'

// 编译结果
// 原始类名 .btn → Button__btn___1x2y3

最佳实践

• 开发环境：使用 [local] 保留原始类名方便调试：

  localIdentName: '[local]--[hash:base64:5]' // .btn → btn--1x2y3
  

• 生产环境：缩短哈希长度提升性能：

  localIdentName: '[hash:base64:6]' // .btn → _1x2y3
  

---

总结

通过灵活配置 CSS Modules，开发者可以：

1. 精准控制作用域：避免样式污染
2. 平衡可读性与性能：开发时保留类名可读性，生产环境优化哈希长度
3. 适配不同架构：根据项目结构自定义文件匹配规则