Vite项目中Sass遗留API弃用警告的解决

当从Create React App迁移到Vite时，你可能会在开发控制台看到以下弃用警告：

Deprecation [legacy-js-api]: The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0.

问题原因

图: Vite开发控制台中的弃用警告

该警告表明你当前使用的Vite配置中，Sass编译器使用的是即将被移除的遗留JS API（如sass.render()）。随着Dart Sass 2.0.0的发布，这些API将被完全移除，可能导致构建失败。主要有两个触发原因：

1. Vite默认使用旧版Sass API
2. 项目中存在使用@import的Sass文件（未升级到现代模块系统）

推荐解决方案

1. 更新Vite配置（首选方法）

修改vite.config.js/ts文件，启用现代Sass API模式：

import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler', // 或者 'modern'
      }
    }
  }
});

参数值解释：

• modern-compiler(推荐)：完全启用现代编译器功能
• modern：仅启用现代API但不支持编译
• legacy(默认)：使用即将废弃的旧API

2. 迁移项目中的Sass文件

升级到现代Sass模块系统（推荐使用官方迁移工具）：

# 安装迁移工具
npm install -g sass-migrator

# 迁移特定文件
sass-migrator module --migrate-deps ./src/styles/main.scss

# 迁移目录下所有文件
find . -name "*.scss" -exec sass-migrator module --migrate-deps {} \;

迁移工具会自动：

1. 将@import替换为现代@use语法
2. 将@import替换为@forward（在index文件中）
3. 移除弃用的全局函数调用

WARNING

迁移后需要验证样式是否完整，某些作用域变化可能需要手动调整

3. 处理全局变量和别名

迁移后可能需要更新全局变量导入方式：

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        additionalData: `@use "@/styles/variables.scss" as *;`
      }
    }
  },
  resolve: {
    alias: {
      '@': '/src' // 确保路径别名正确
    }
  }
})

// 弃用旧语法
@import '~@/styles/variables';

// 改用现代语法
@use '@/styles/variables' as vars;

.element {
  color: vars.$primary-color;
}

4. 更新依赖库（Quasar等）

如果使用第三方UI库如Quasar：

// 弃用
- import 'quasar/src/css/index.sass'

// 改用预编译的CSS
+ import 'quasar/dist/quasar.css'

潜在陷阱与检查项

1. Node版本兼容性

   nvm use 18 # 某些项目在Node 18下表现最佳

2. 验证Sass版本

   npm list sass # 应显示>=1.79.1

3. 避免仅隐藏警告（不推荐）

   // ⚠️ 此方案不解决根本问题
   scss: {
     silenceDeprecations: ["legacy-js-api"],
   }

迁移后的语法优势

现代@use系统提供：
✅ 更清晰的命名空间
✅ 避免CSS全局污染
✅ 通过as *保留全局变量访问
✅ 更好的依赖管理

完整示例配置

import { defineConfig } from 'vite';
import path from 'path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        additionalData: `
          @use "@/styles/_variables.scss" as *;
          @use "@/styles/_mixins.scss" as *;
        `,
      },
    },
  },
});

后续维护建议

1. 定期更新依赖

   npm update sass vite

2. 在新组件中使用模块化SCSS语法
3. 使用Sass Linter检查过时代码
4. 持续监测官方弃用通知：
   Dart Sass Changelog

遵循以上步骤可彻底解决弃用警告并实现面向未来的Sass配置。