Vite多页面配置问题：HTML类名未与CSS哈希类名匹配

你遇到的核心问题是：CSS Modules生成的哈希类名与Twig模板中硬编码的原始类名不匹配。原因在于Vite的CSS Modules仅对JS/TS中导入的样式模块生效，会自动生成哈希类名并通过变量提供引用，但Twig模板里的硬编码类名不在Vite的替换流程中，导致构建后CSS类名已哈希，模板里的类名却保持原样。

以下是针对性的解决方案：

方案1：通过JS/TS绑定映射后的类名（推荐） #

如果你的页面是前端驱动（如React），不要在Twig模板中直接写类名，改为在TS/JS组件中导入样式模块，用导出的变量绑定类名：

// scripts/index.ts
import styles from '../styles/your-styles.module.scss';

// React组件示例
function PageComponent() {
  return <div className={styles.Block_element}>页面内容</div>;
}

这种方式下，Vite会自动将类名替换为哈希后的版本，完全无需手动处理模板。

方案2：禁用CSS Modules哈希（放弃局部作用域） #

如果不需要类名哈希和局部作用域，仅需保持类名一致，修改css.modules配置：

css: {
  modules: {
    scopeBehaviour: 'global', // 全局模式，不生成哈希类名
    // 移除generateScopedName配置
  },
  // ...其他PostCSS配置
}

此方案会让CSS类名与模板中的原始类名完全匹配，但失去了CSS Modules的局部作用域和缓存优化能力。

方案3：PostCSS+Twig自定义函数映射类名 #

若必须在Twig模板中写类名，可通过postcss-modules生成类名映射文件，再用Twig自定义函数读取映射替换类名：

1. 安装依赖：

npm install postcss-modules --save-dev

2. 修改PostCSS配置，生成类名映射文件：

css: {
  postcss: {
    syntax: postcssScss,
    plugins: [
      postcssImport(),
      autoprefixer(),
      require('postcss-modules')({
        getJSON: (cssFileName, json) => {
          const fs = require('fs');
          const path = require('path');
          // 生成映射文件到临时目录
          const outputDir = path.resolve(__dirname, './.tmp/class-maps');
          fs.mkdirSync(outputDir, { recursive: true });
          fs.writeFileSync(
            path.join(outputDir, `${path.basename(cssFileName)}.json`),
            JSON.stringify(json)
          );
        },
        generateScopedName: '[hash:base64:2]'
      })
    ],
  },
}

3. 在Twig插件中添加自定义函数，读取映射返回哈希类名：

twig({
  // ...现有root、namespaces等配置
  functions: [
    {
      name: 'cssClass',
      func: (className) => {
        const fs = require('fs');
        const path = require('path');
        // 读取对应样式文件的映射
        const mapPath = path.resolve(__dirname, './.tmp/class-maps/your-styles.scss.json');
        if (!fs.existsSync(mapPath)) return className;
        const classMap = JSON.parse(fs.readFileSync(mapPath, 'utf8'));
        return classMap[className] || className;
      }
    }
  ]
})

4. 在Twig模板中使用自定义函数：

<div class="{{ cssClass('Block_element') }}">页面内容</div>

你的配置需修正的细节 #

1. scopeBehaviour: 'global'与generateScopedName冲突：全局模式下CSS Modules不会生成哈希类名，若需启用哈希，应将scopeBehaviour改为默认的'local'。
2. publicDir设置为dist会导致Vite将dist目录视为静态资源目录，构建时重复复制文件引发混乱，建议改为public目录。

内容的提问来源于stack exchange，提问作者Дмитрий Люлекин