React+Vite+Metronic模板：Sass文件导入CSS依赖报错

问题背景 #

将基于Metronic模板的React项目从Create React App（CRA）迁移到Vite后，遇到Sass文件相关报错。已安装sass包，但Vite无法解析Sass文件中带~前缀的第三方CSS文件导入。

项目依赖 #

"dependencies": {
    "@fortawesome/fontawesome-free": "^6.2.1",
    "animate.css": "^4.1.1",
    "bootstrap-icons": "^1.10.3",
    "prism-themes": "^1.9.0",
    "sass": "^1.57.1",
    // other dependencies...
}

报错信息 #

[vite] Internal server error: [postcss] Failed to find '~@fortawesome/fontawesome-free/css/all.min.css'

触发场景 #

在Sass文件中使用如下方式导入外部库时出现报错：

@import '~socicon/css/socicon.css';
@import '~@fortawesome/fontawesome-free/css/all.min.css';
// other imports...

已确认这些包存在于node_modules中，但Vite仍无法找到，注释掉一行后下一个导入会抛出类似错误。

解决方案 #

原因 #

CRA的Webpack配置会将~前缀解析为node_modules目录，但Vite遵循ES模块规范，默认不支持这种前缀写法。

方法1：直接移除~前缀 #

修改Sass文件中的导入语句，去掉~：

@import 'socicon/css/socicon.css';
@import '@fortawesome/fontawesome-free/css/all.min.css';

Vite会自动从node_modules目录中查找这些第三方包，符合ES模块的解析规则。

方法2：配置Vite别名兼容~前缀 #

如果不想修改大量导入代码，可以在vite.config.js（或vite.config.ts）中添加别名配置，将~映射到node_modules：

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

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '~': path.resolve(__dirname, 'node_modules')
    }
  }
});

配置完成后，原有带~的导入语句即可正常被Vite解析。

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