Vite系列课程 | 11. Vite 配置文件中 CSS 配置（Modules 模块化篇）

11. Vite 配置文件中 CSS 配置（Modules 模块化篇）

由于课程讲的是 vite2 版本，所以我阅读了 vite6 中的文档，下面将结合 css.modules 的接口进行讲解

CSSModulesOptions 接口文档

interface CSSModulesOptions {
  /**
   * 用户可以自定义一个回调函数，来处理生成的 JSON 文件。
   * 该回调函数接受三个参数：
   *  - cssFileName: 当前处理的 CSS 文件名
   *  - json: 生成的类名与哈希值的映射对象
   *  - outputFileName: 生成的 CSS 文件的输出路径
   */
  getJSON?: (
    cssFileName: string,
    json: Record<string, string>,
    outputFileName: string,
  ) => void;

  /**
   * 定义 CSS Modules 的作用域行为
   * - 'local'：启用 CSS Modules，生成的类名会进行哈希化并作用于当前模块。
   * - 'global'：禁用 CSS Modules，所有类名都将是全局的，不会进行哈希化。
   */
  scopeBehaviour?: 'global' | 'local';

  /**
   * 定义哪些 CSS 文件路径需要被视为全局样式，不应用 CSS Modules。
   * 可以传入一个正则表达式数组，匹配路径中符合规则的文件。
   */
  globalModulePaths?: RegExp[];

  /**
   * 如果为 `true`，会导出所有的全局类名，即使在使用 CSS Modules 时，也会把它们暴露为全局类。
   * 默认为 `false`，不会导出全局类名。
   */
  exportGlobals?: boolean;

  /**
   * 定义生成的 CSS 类名的格式，可以是一个字符串模板，也可以是一个函数。
   * 字符串模板的格式通常为 `[name]__[local]___[hash:base64:5]`，其中：
   * - `[name]` 是文件名（不含扩展名）
   * - `[local]` 是原始的 CSS 类名
   * - `[hash:base64:5]` 是文件内容的哈希值，长度为 5
   *
   * 如果传入函数，它接受三个参数，允许你根据文件名、类名及 CSS 内容来生成类名。
   */
  generateScopedName?:
    | string
    | ((name: string, filename: string, css: string) => string);

  /**
   * 为生成的类名哈希值添加一个前缀，用于避免不同项目之间的哈希冲突。
   */
  hashPrefix?: string;

  /**
   * 控制类名在 JS 对象中的转换方式：
   * - 'camelCase'：将 CSS 类名转为 camelCase 格式（例如 `my-class` 转为 `myClass`）
   * - 'camelCaseOnly'：与 'camelCase' 类似，但如果类名原本就是 camelCase 格式，则保持不变。
   * - 'dashes'：将 CSS 类名保持为短横线分隔格式（例如 `my-class` 转为 `my-class`）
   * - 'dashesOnly'：与 'dashes' 类似，但如果类名已经是短横线格式，则保持不变。
   * 
   * 还可以传入一个函数，允许你自定义转换规则，函数接收三个参数：
   * - `originalClassName`: 原始 CSS 类名
   * - `generatedClassName`: 生成的类名
   * - `inputFile`: 当前处理的文件路径
   */
  localsConvention?:
    | 'camelCase'
    | 'camelCaseOnly'
    | 'dashes'
    | 'dashesOnly'
    | (
        originalClassName: string,
        generatedClassName: string,
        inputFile: string,
      ) => string;
}

完整配置示例：

export default {
  css: {
    modules: {
      getJSON(cssFileName, json, outputFileName) {
        console.log('Generated CSS JSON:', json)
      },
      scopeBehaviour: 'local', // 使用 CSS Modules
      globalModulePaths: [/\.global\.css$/], // 匹配全局 CSS 文件
      exportGlobals: true, // 导出全局类名
      generateScopedName: '[name]__[local]__[hash:base64:5]', // 类名格式
      hashPrefix: 'viteApp_', // 哈希前缀
      localsConvention: 'camelCase' // 驼峰命名类名
    }
  }
}

vite6 中 css modules 最新配置共享选项

11.1.1. 总结

Vite 提供了灵活的 CSS 模块化配置选项，可以帮助开发者在处理 CSS 时避免样式冲突，并根据项目的需求定制类名生成规则。同时，Vite 还支持对外部库（如 node_modules）的样式进行处理，确保项目中的样式兼容性和可维护性。

---