全局CSS不能靠additionalData注入，仅对.scss和<style lang="scss">生效；纯.css文件必须在main.ts或App.vue中显式import或@import。
全局CSS必须显式导入，不能靠additionalData注入
很多人误以为在 vite.config.ts 里配了 css.preprocessorOptions.sass.additionalData 就能一劳永逸地让所有 CSS 文件自动加载 reset 或 base 样式——这是错的。additionalData 只对 .scss 和 .vue 中 <style lang="scss"> 生效，对纯 .css 文件完全无效。
真正可靠的全局 CSS 引入方式只有两种：
- 在
main.ts（或main.js）中用import './assets/styles/reset.css'—— 顺序决定层叠优先级，建议放在最前 - 在
App.vue的顶层<style>中用@import "@/styles/reset.css";—— 注意路径要能被 Vite 解析（需已配resolve.alias） - 绝对不要在多个组件里各自
@import同一份reset.css，否则构建后会重复打包、样式覆盖顺序不可控
additionalData 是注入 SCSS 全局变量的唯一可靠方式
想让所有 .scss 文件（包括 <style lang="scss" scoped>）都能直接用 $primary-color 或 @include clearfix()，必须用 additionalData。它不是“运行时注入”，而是在 Sass 编译前把指定代码拼到每个 SCSS 文件开头，属于语法层面预处理。
正确写法（推荐）：
立即学习“前端免费学习笔记（深入）”；
css: {
preprocessorOptions: {
scss: {
additionalData: '@use "./src/styles/vars.scss" as *;\n'
}
}
}
- 路径必须是相对项目根目录的，
@/别名在additionalData字符串里不解析，硬写会报File to import not found - 末尾必须加
\n，否则最后一行可能和组件内样式连成一句，触发Invalid CSS after ... - 别在
vars.scss里写@debug或@warn，开发时会刷屏，甚至中断构建 - 如果用了
CSS Modules（如Button.module.scss），additionalData注入的变量仍可用，但仅限该模块内部
SCSS 全局混入（@mixin）必须集中定义，不能分散
构建时报 Undefined mixin，99% 是因为 @mixin 定义和调用不在同一个编译单元。Vite 构建阶段会把所有 SCSS 提取合并，但提取顺序不保证定义一定在调用之前。
解决办法只有一条：所有 @mixin、@function、$var 必须集中在一个入口文件（比如 src/styles/index.scss），再由它统一 @use 其他模块；组件级 SCSS 文件（如 Card.scss）只写选择器和规则，禁止定义新混入。
- 错误示范：
Card.scss里定义@mixin card-shadow()，又在Button.scss里调用它 - 正确结构：
index.scss@use "mixins"+@use "variables"，其他文件只@use "index.scss" as * - 若用
@import替代@use，确保被导入文件名以_开头（如_mixins.scss），否则 Sass 会尝试把它当作普通样式输出
批量导入 SCSS 目录需插件，vite 原生不支持 glob
Vite 默认不解析 @import "./styles/commons/**/*.scss" 这类通配符语法——这不是 bug，而是设计选择：它强调静态可分析的显式依赖，避免隐式引入破坏 HMR 精确性或构建稳定性。
要用 glob 导入，必须装插件：
pnpm add -D vite-plugin-sass-glob-import
并在 vite.config.ts 中启用（注意顺序，要放在其他影响 Sass 的插件之后）：
import sassGlobImport from 'vite-plugin-sass-glob-import'
export default defineConfig({
plugins: [
// 其他插件...
sassGlobImport()
]
})
- 导入顺序按字母升序排列（
_01-vars.scss→_02-mixins.scss），有依赖关系就靠命名控制 - 插件只作用于 Sass 编译阶段，不影响 Vite 模块图，HMR 正常工作
- 生产环境慎用 glob：它会让样式依赖变得模糊，排查问题困难；更推荐显式维护一个
index.scss入口
真正容易被忽略的是：全局 CSS 和全局 SCSS 变量走的是两套机制，混用会失效；additionalData 的换行、路径、别名限制看似琐碎，但任一出错都会导致静默失败或构建中断——这些细节没跑通前，别急着写业务样式。
