如何在Vite中为SCSS文件添加哈希？解决资源路径与命名异常

核心原因 #

Vite 对 JS 和 CSS/静态资源的默认处理逻辑存在差异，主要源于两点：

1. 资源归类规则：JS 文件作为入口依赖，默认会被打包到assets目录并添加哈希（用于缓存击穿）；但通过 JS 导入的 CSS、字体（.ttf）、图标（.svg）这类资源，Vite 默认会保留它们在源码中的相对路径结构（比如从src目录导入的文件，构建后会放到dist/src下），且默认不会给 CSS 文件添加哈希（除非配置相关规则）。
2. HTML 直接引入的资源处理：如果直接在index.html里引入 CSS，Vite 默认不会将其视为构建流程中的“打包资源”，而是作为静态资源原样复制，所以不会自动放入assets或添加哈希。

解决方案 #

要让 CSS、字体、图标和 JS 保持一致的输出结构（都放到assets目录并带哈希），只需在vite.config.ts中添加以下配置：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    // 统一所有资源的输出目录为 assets
    assetsDir: 'assets',
    rollupOptions: {
      output: {
        // 配置资源文件名规则：目录/名称-[哈希].[后缀]
        assetFileNames: (assetInfo) => {
          let extType = assetInfo.name.split('.').at(1);
          // 区分资源类型，统一放到 assets 下对应子目录（可选，也可全部放根 assets）
          if (/png|jpe?g|svg|gif|tiff|bmp|ico/i.test(extType)) {
            extType = 'images';
          } else if (/woff|woff2|eot|ttf|otf/i.test(extType)) {
            extType = 'fonts';
          } else if (/css/i.test(extType)) {
            extType = 'css';
          }
          return `assets/${extType}/[name]-[hash][extname]`;
        },
        // JS 文件的命名规则（可选，默认已带哈希）
        chunkFileNames: 'assets/js/[name]-[hash].js',
        entryFileNames: 'assets/js/[name]-[hash].js',
      },
    },
    // 确保 CSS 被提取为单独文件（默认已开启，可显式声明）
    cssCodeSplit: true,
  },
});

补充说明 #

• 配置后，所有通过 JS 导入的 CSS、字体、图标都会被打包到dist/assets下的对应子目录，文件名带有哈希值，和 JS 文件处理逻辑一致。
• 如果需要在index.html中直接引入 CSS，不要用普通<link>标签，要通过 Vite 的资源导入语法：

  <link rel="stylesheet" href="/src/index.scss?url" />
  

  加上?url后，Vite 会将其视为构建资源，按照配置的规则处理路径和哈希。

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