如何在Nuxt 3中配置全局CSS和预处理变量

作者：袖梨 2026-08-07

全局CSS文件需在nuxt.config.ts的css数组中以字符串路径引入（如'@/assets/css/global.css'），而SCSS/Less变量须通过vite.css.preprocessorOptions.additionalData配置导入变量文件，并确保安装sass与sass-loader、路径正确、分号完整、重启服务。

全局 CSS 文件直接引入就行

想让某个 CSS 文件在所有页面生效，比如重置样式或基础排版规则，直接写进 nuxt.config.ts 的 css 数组里就行。Nuxt 3 会自动把它注入到每个页面的 <head> 中。

  1. css 里填的是路径字符串，支持 @/ 别名（指向 src/ 或项目根），比如 '@/assets/css/global.css'
  2. 不能写成 import 或动态路径，Vite 不识别那种写法
  3. 如果用的是 .scss 或 .less，这里只负责加载，**不提供变量/函数作用域**——它走的是普通 CSS 编译流程，不是预处理器注入
  4. 别把变量文件（如 variables.scss）直接塞进 css 数组，否则会报错：Sass 编译器不接受纯声明文件当样式源

Scss/Less 全局变量必须走 vite.css.preprocessorOptions

真正让 $color-primary 或 @spacing-md 在所有 <style lang="scss"> 块里可用，只能靠 Vite 的预处理器配置。Nuxt 3 不再支持 @nuxtjs/style-resources 这类旧插件（它在 Nuxt 3 中无效）。

  1. 路径必须是字符串拼接形式：additionalData: '@import "@/assets/scss/variables.scss";' —— 注意末尾分号不能丢，漏了整个注入就失效
  2. @/ 可用，~/ 或 ~ 不行；相对路径要从项目根算起，比如 ../assets/scss/variables.scss
  3. 变量文件本身必须语法合法：每条声明后加分号，不能有未闭合的嵌套或非法字符
  4. 只对 <style lang="scss"> 或 <style lang="less"> 生效，<style scoped>（默认 CSS）完全不认这些变量

依赖版本不匹配会导致变量根本不出现在编译上下文

装了 sass 但没装 sass-loader，或者版本错配，additionalData 就像没写一样——开发服务器跑得起来，但变量一用就报 Undefined variable。

  1. 必须同时安装：pnpm add -D sass sass-loader（推荐 [email protected]+ + sass-loader@14+）
  2. 如果之前装过 sass-loader@10 或更低，先 pnpm remove sass-loader 再重装，旧版和 Vite 4+ 不兼容
  3. 检查 node_modules 下真有这两个包目录，别信 package.json 里写了就算装成功
  4. 改完 nuxt.config.ts 后必须重启 pnpm run dev，Vite 不热更新这个配置项

变量文件里写的不是“运行时值”，别试图在 <script setup> 里读取

Sass 变量只存在于样式编译阶段，打包完就没了。你在 <script> 里访问 $primary-color，TypeScript 会报错，JavaScript 运行时根本找不到这个符号。

  1. 想复用颜色值？把真实值（如 #3498db）单独抽成 const PRIMARY_COLOR = '#3498db' 放 JS 文件里，样式里用 @use 引入模块（需 Sass 1.70+）或双写一份
  2. 别指望 additionalData 能把变量“同步”到 JS 上下文，它只影响 CSS 构建流水线
  3. 验证是否生效，最直接方式：在任意 <style lang="scss"> 里写 body { color: $primary-color; }，看浏览器渲染结果和控制台有没有编译错误
变量文件路径拼错、依赖缺位、分号遗漏、重启忘记——这四点加起来占了 90% 的失败原因。动手前先盯住这四个地方，比反复查文档快得多。

相关文章

精彩推荐