Vue 3 + Vite 项目 SCSS 配置指南

Vue 3 + Vite 项目 SCSS 配置指南

本文说明如何在 Vite + Vue 3 项目中正确配置 SCSS,包括全局样式、全局变量、入口文件模式,以及常见坑。

---

一、安装 sass

Vite 原生支持 SCSS,只需安装编译器即可,需改 vite.config.ts:

npm install -D sass

css: {
    //配置全局scss变量
    preprocessorOptions: {
      scss: {
        
        // 每个 scss 文件会自动注入这段内容
        additionalData: `@use "@/styles/variables.scss" as *;`
      }
    }

装完后 .scss 文件和 <style lang="scss"> 就能直接用了。

---

二、推荐的目录结构

src/styles/
├── reset.scss       # 清默认样式(真实 CSS,全局生效)
├── variables.scss   # SCSS 变量、mixin(供各文件按需 @use)
└── index.scss       # 入口文件:汇聚所有「全局 CSS」

---

三、配置全局样式(清默认样式)

1. 新建 src/styles/reset.scss

/* 清除浏览器默认样式 */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

ul, ol {
  list-style: none;
}

a {
  text-decoration: none;
  color: inherit;
}

img {
  display: block;
  max-width: 100%;
}

input, button, textarea {
  font: inherit;
}

2. 在入口文件 index.scss 中引入

// src/styles/index.scss —— 全局样式入口
@use "./reset.scss";

// 以后有其它通用样式,继续在这里 @use 或直接写

3. 在 main.ts 中引入 index(只需一次)

// main.ts
import '@/styles/index.scss'

@ 是配置好的路径别名,指向 src 目录,@/styles 即 src/styles。

---

四、配置全局 SCSS 变量

1. 新建 src/styles/variables.scss

// 主题变量
$primary-color: #409eff;
$font-size: 14px;

// 也可以定义 mixin
@mixin flex-center($gap: 10px) {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: $gap;
}

2. 在需要用到变量的文件中手动 @use

<style lang="scss">
@use "@/styles/variables.scss" as *;   // as * 表示不用命名空间,直接 $primary-color 这样用

.foo {
  color: $primary-color;
  font-size: $font-size;
}
</style>

变量是按文件隔离的——谁 @use 谁才能用,index.scss 里引入并不能让变量全局可用。

---

五、入口文件模式(index.scss)说明

东西	例子	通过 index.scss 统一引入后,其它组件能用吗?
全局 CSS	reset.scss 里的清默认样式	✅ 能,一次引入全局生效
SCSS 变量/mixin	variables.scss 里的 $primary-color	❌ 不能,变量只在 @use 它的文件内可见

结论:index.scss 负责统一「全局 CSS」;variables.scss 由各文件按需 @use。

---

六、常见坑与铁律

铁律 1:@use 只能写在 .scss 文件里

@use 是 SCSS 语法,不能写进 .ts / .vue 的 <script> 里:

// ❌ 错误 —— 会报语法错误
@use "@/styles/variables.scss"

铁律 2:引文件用 @use,别用 @import

@import 已废弃,未来 Dart Sass 3.0 会删除:

@import "./variables.scss";           // ❌ 废弃,会有警告
@use "./variables.scss" as *;         // ✅ 推荐

铁律 3:别用 additionalData 自动注入变量

在 vite.config.ts 里用 additionalData 想让变量「免 @use 全局可用」,两种写法都有坑:

写法	结果
additionalData + @use	❌ Module loop: this module is already being loaded
additionalData + @import	⚠️ 能用,但有「@import 已废弃」警告

正确做法:不用 additionalData,每个文件手动 @use。

---

七、速查总结

1. 装 sass:npm install -D sass
2. 全局样式:reset.scss → index.scss 里 @use "./reset.scss" → main.ts 里 import '@/styles/index.scss'
3. 全局变量:variables.scss → 需要用的文件顶部 @use "@/styles/variables.scss" as *;
4. 三条铁律:
   • @use 只能写在 .scss 里
   • 引文件用 @use,不用 @import
   • 不用 additionalData 注入变量