首页
/ Nuxt 样式指南：css 配置、预处理器、PostCSS 与 SFC 样式的完整解析

Nuxt 样式指南：css 配置、预处理器、PostCSS 与 SFC 样式的完整解析

2026-09-06 14:11:42作者：俞予舒Fleming
nuxt
the full-stack Vue framework
项目地址：https://gitcode.com/GitHub_Trending/nu/nuxt

Nuxt 对样式方案保持"不持立场"的开放态度：你可以手写本地样式表、引入 npm 分发的 CSS 库、加载外部 CDN 样式，也可以自由使用 SCSS/Less/Stylus 等预处理器和 PostCSS。本篇以 Nuxt 官方文档的 Styling 章节为骨架，逐条覆盖其全部实操路径，并结合本仓库中 Vite 构建插件与配置 schema 的源码，解释 css 配置项、PostCSS 插件排序、样式内联（inline styles）等机制在 Nuxt 4 源码中的真实实现，帮助你在实际项目中既会用、也懂其底层。

本地样式表（Local Stylesheets）

如果你在编写本地样式表，按约定应放在 app/assets/ 目录下。Nuxt 提供两种引入方式：

在组件内直接引入

可以在页面、布局和组件中直接用 JavaScript import 或 CSS @import 语句引入样式表：

<script>
// 静态 import：服务端渲染（SSR）兼容
import '~/assets/css/first.css'

// 注意：动态 import 不兼容服务端渲染
import('~/assets/css/first.css')
</script>

<style>
@import url("~/assets/css/second.css");
</style>

官方文档在此处给出了一条重要提示：这些样式表会被内联到 Nuxt 渲染的 HTML 中。这一点在源码中可以得到印证——应用入口 entry.ts 会导入 #build/css，该虚拟模块由 templates.ts 中的 cssTemplate 生成，内容就是 nuxt.options.css 中每一项的 import 语句拼接：

export const cssTemplate: NuxtTemplate = {
  filename: 'css.mjs',
  dependsOn: [],
  getContents: ctx => ctx.nuxt.options.css.map(i => genImport(i)).join('\n'),
}

而在构建阶段，Vite 插件 SSRStylesPlugin 会在生产构建时将组件样式以 <style> 标签内联进 SSR 响应，并在样式已内联时安全地从 HTML 中移除对应的 <link>，避免样式重复加载。

通过 css 配置属性全局引入

除了组件内引入，还可以用 Nuxt 配置中的 css 属性声明全局样式表——同样建议放在 app/assets/ 目录：

export default defineNuxtConfig({
  css: ['~/assets/css/main.css'],
})

同样地，这些样式表会被内联进 Nuxt 渲染的 HTML，并作为全局样式注入，出现在所有页面中。

css 属性在源码中的处理细节值得注意：

  • 配置解析：schema 定义见 app.ts 中的 css 字段，$resolve 会把非数组输入归一化为空数组，且只保留字符串类型的条目。
  • 去重：模块加载完成后，Nuxt 会对 nuxt.options.css 去重（见 nuxt.ts 中 modules:done 钩子之后执行的 filter 逻辑）。由于模块和多层（layers）都会向 css 追加条目，去重能保证同一张样式表不被重复引入。
  • 不可解析路径的告警：nuxt.ts 中的 warnUnresolvableGlobalCss 会检查每个 css 条目——相对路径条目（以 ./ 或 ../ 开头）会直接报错诊断并提示改用 ~/ 别名；别名解析后不存在于文件系统的条目也会触发诊断。注释明确说明了原因：这类错误在其他情况下是"静默失败"的——开发服务器会发出一个没有任何服务承载的 <link> URL，而生产构建则会把样式整个丢掉。

因此，配置 css 时请使用 ~/assets/... 这类可解析的别名路径，并留意启动日志中的相关诊断。

字体文件（Fonts）

将本地字体文件放入 public/ 目录（例如 public/fonts），然后在样式表中用 url() 引用：

@font-face {
  font-family: 'FarAwayGalaxy';
  src: url('/fonts/FarAwayGalaxy.woff') format('woff');
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

之后在样式表、页面或组件中按字体名使用：

<style>
h1 {
  font-family: 'FarAwayGalaxy', sans-serif;
}
</style>

public/ 目录中的文件以原始文件名直接通过根 URL 提供（如 /fonts/xxx.woff），不经过构建工具处理；这与需要处理的 app/assets/ 目录形成对照（后者不会被暴露为静态 URL）。

通过 NPM 分发的样式表

也可以引用 npm 分发的样式表。以流行的 animate.css 为例，安装：

npm install animate.css   # 或 yarn add / pnpm install / bun install / deno install npm:animate.css

然后在页面、布局或组件中直接引用：

<script>
import 'animate.css'
</script>

<style>
@import url("animate.css");
</style>

也可以在 Nuxt 配置的 css 属性中以字符串形式引用包名：

export default defineNuxtConfig({
  css: ['animate.css'],
})

外部样式表（External Stylesheets）

外部样式表（包括本地样式表）还可以通过向 <head> 注入 <link> 元素的方式引入，最常用的方式是 Nuxt 配置的 app.head 属性：

export default defineNuxtConfig({
  app: {
    head: {
      link: [{ rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css' }],
    },
  },
})

动态添加样式表

在代码中可以使用 useHead composable 动态设置 head 内容：

useHead({
  link: [{ rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css' }],
})

Nuxt 底层使用的是 unhead，完整能力可参考其文档。

用 Nitro 插件修改渲染后的 Head

如果需要更精细的控制，可以用钩子拦截渲染后的 HTML 并编程式地修改 head。在 ~~/server/plugins/my-plugin.ts 中创建一个插件：

import { definePlugin } from 'nitro'

export default definePlugin((nitro) => {
  nitro.hooks.hook('render:html', (html) => {
    html.head.push('<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css">')
  })
})

需要记住的是：外部样式表是渲染阻塞（render-blocking）资源——浏览器必须加载并处理完它们才能渲染页面。含有不必要大型样式表的页面渲染会更慢，应尽量避免引入过大的外部 CSS。

使用预处理器（Preprocessors）

要使用 SCSS、Sass、Less 或 Stylus 等预处理器，先安装对应依赖：

npm install -D sass      # Sass & SCSS
npm install -D less      # Less
npm install -D stylus    # Stylus

样式表按约定写在 app/assets 目录，然后在 app.vue（或布局文件）中用预处理器语法引入源文件：

<style lang="scss">
@use "~/assets/scss/main.scss";
</style>

或者同样使用 Nuxt 配置的 css 属性：

export default defineNuxtConfig({
  css: ['~/assets/scss/main.scss'],
})

两种方式下，编译后的样式表都会内联进 Nuxt 渲染的 HTML。

向预处理文件注入代码（partial 变量）

如果需要向预处理文件注入代码（例如包含颜色变量的 Sass partial），可以在 Vite 的 preprocessorOptions 中配置。先在 app/assets 目录创建 partial：

$primary: #49240F;
$secondary: #E4A79D;

$primary: #49240F
$secondary: #E4A79D

然后在 nuxt.config 中配置 additionalData（SCSS 与 SASS 各自对应不同的键）：

// SCSS
export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: '@use "~/assets/_colors.scss" as *;',
        },
      },
    },
  },
})

// SASS
export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        sass: {
          additionalData: '@use "~/assets/_colors.sass" as *\n',
        },
      },
    },
  },
})

Nuxt 默认使用 Vite。如果改用 webpack，请参考各预处理器 loader 的文档自行配置。

预处理器 Worker（实验性）

Vite 提供了一个实验性选项 css.preprocessorMaxWorkers，可以为预处理器提速。可以在 nuxt.config 中开启：

export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorMaxWorkers: true, // number of CPUs minus 1
    },
  },
})

这是实验性选项，使用前建议查阅 Vite 官方文档并了解其反馈渠道。

单文件组件（SFC）样式

Vue SFC 天然擅长处理样式：可以直接在组件的 <style> 块中写 CSS 或预处理器代码，无需 CSS-in-JS 即可获得很好的开发体验；如果确实想使用 CSS-in-JS，也有第三方库和 Nuxt 模块可选。

Class 与 Style 绑定

可以利用 Vue SFC 的 class/style 绑定特性来动态控制组件样式。文档给出了三类写法：ref/reactive 对象绑定、computed 计算绑定、数组绑定，以及对象/数组形式的 :style 绑定：

<script setup lang="ts">
const isActive = ref(true)
const hasError = ref(false)
const classObject = reactive({
  'active': true,
  'text-danger': false,
})
</script>

<template>
  <div
    class="static"
    :class="{ 'active': isActive, 'text-danger': hasError }"
  />
  <div :class="classObject" />
</template>

<script setup lang="ts">
const isActive = ref(true)
const error = ref(null)

const classObject = computed(() => ({
  'active': isActive.value && !error.value,
  'text-danger': error.value && error.value.type === 'fatal',
}))
</script>

<template>
  <div :class="classObject" />
</template>

<script setup lang="ts">
const isActive = ref(true)
const errorClass = ref('text-danger')
</script>

<template>
  <div :class="[{ active: isActive }, errorClass]" />
</template>

<script setup lang="ts">
const activeColor = ref('red')
const fontSize = ref(30)
const styleObject = reactive({ color: 'red', fontSize: '13px' })
</script>

<template>
  <div :style="{ color: activeColor, fontSize: fontSize + 'px' }" />
  <div :style="[baseStyles, overridingStyles]" />
  <div :style="styleObject" />
</template>

用 v-bind 实现动态样式

在 <style> 块中可以用 v-bind 引用 JavaScript 变量和表达式，绑定是动态的——变量值变化时样式会随之更新：

<script setup lang="ts">
const color = ref('red')
</script>

<template>
  <div class="text">
    hello
  </div>
</template>

<style>
.text {
  color: v-bind(color);
}
</style>

Scoped 作用域样式

scoped 属性让你可以"隔离"地给组件写样式，声明只作用于当前组件：

<template>
  <div class="example">
    hi
  </div>
</template>

<style scoped>
.example {
  color: red;
}
</style>

CSS Modules

通过 module 属性使用 CSS Modules，通过注入的 $style 变量访问生成的类名：

<template>
  <p :class="$style.red">
    This should be red
  </p>
</template>

<style module>
.red {
  color: red;
}
</style>

SFC 中的预处理器支持

SFC 的 <style> 块支持预处理器语法。Vite 内置支持 .scss、.sass、.less、.styl 和 .stylus 文件，无需配置，安装依赖后即可直接在 SFC 中通过 lang 属性使用：

<style lang="scss">
  /* Write scss here */
</style>

<style lang="sass">
  /* Write sass here */
</style>

<style lang="less">
  /* Write less here */
</style>

<style lang="stylus">
  /* Write stylus here */
</style>

webpack 用户请参考 vue-loader 的文档。

使用 PostCSS

Nuxt 内置 PostCSS，可以在 nuxt.config 中配置：

export default defineNuxtConfig({
  postcss: {
    plugins: {
      'postcss-nested': {},
      'postcss-custom-media': {},
    },
  },
})

在 SFC 中可以使用 lang="postcss" 属性获得更好的语法高亮：

<style lang="postcss">
  /* Write postcss here */
</style>

Nuxt 默认预配置了以下 PostCSS 插件：

  • postcss-import：增强 @import 规则
  • postcss-url：转换 url() 语句
  • autoprefixer：自动添加厂商前缀
  • cssnano：压缩与 purge

源码层面，PostCSS 的解析与排序逻辑集中在 css.ts 的 resolveCSSOptions 中，并被 vite.ts 在创建 Vite 配置时调用（css: await resolveCSSOptions(nuxt)）。其关键行为有：

  • 插件排序：postcss.order 支持字符串预设名、数组或函数三种形态，定义见 postcss.ts。默认预设是 autoprefixerAndCssnanoLast，即强制 autoprefixer 和 cssnano 排在所有插件最后——这是刻意为之：autoprefixer 需要看到最终选择器，cssnano 作为压缩器必须最后执行。
  • 缺失插件的交互式安装：resolvePostcssPlugin 会尝试从 modulesDir 导入插件，导入失败时会调用 ensureDependencyInstalled 提示用户安装该依赖；若用户拒绝，则发出 NUXT_B7007 构建诊断（含安装命令），而不会让构建莫名失败。

这意味着在 postcss.plugins 中只需写插件名与选项对象，Nuxt 会替你完成"解析 → 排序 → 实例化"的整个流程。

用布局（Layouts）承载多套样式

如果应用的不同部分需要完全不同的风格，可以使用布局：为不同布局编写不同样式。

<template>
  <div class="default-layout">
    <h1>Default Layout</h1>
    <slot />
  </div>
</template>

<style>
.default-layout {
  color: red;
}
</style>

布局机制详见官方文档中 app/layouts 目录结构说明。

第三方库与模块

Nuxt 对样式方案不持立场，可以使用任何工具，例如 UnoCSS、Tailwind CSS 等流行库。社区和 Nuxt 团队开发了大量 Nuxt 模块来简化集成，常见的有：

  • UnoCSS：即时的按需原子化 CSS 引擎
  • Tailwind CSS：原子优先（utility-first）CSS 框架
  • Fontaine：字体度量回退（font metric fallback），可减少 CLS
  • Pinceau：可适配的样式框架
  • Nuxt UI：面向现代 Web 应用的 UI 库
  • Panda CSS：构建时生成原子化 CSS 的 CSS-in-JS 引擎

Nuxt 模块开箱即用地提供了好的开发体验，但要记住：即使你偏好的工具没有现成模块，也完全可以用 Nuxt 插件、或自行编写模块的方式接入。如果自行做了集成，欢迎分享回社区。

便捷加载 Web 字体

  • 可以使用 Nuxt Google Fonts 模块加载 Google Fonts；
  • 如果使用 UnoCSS，它自带 web fonts preset，可从 Google Fonts 等常见字体提供商便捷加载字体。

进阶话题

过渡（Transitions）

Nuxt 拥有与 Vue 相同的 <Transition> 组件，并支持实验性的 View Transitions API。

字体高级优化

官方推荐使用 Fontaine 模块降低 CLS（累计布局偏移）；如需更高级的控制，可以考虑编写 Nuxt 模块来扩展构建流程或运行时。

LCP 高级优化

要加快全局 CSS 文件的下载，官方建议：

  • 使用 CDN，让文件在物理上更接近用户
  • 压缩资源，理想情况下使用 Brotli
  • 使用 HTTP2/HTTP3 传输
  • 将资源托管在同一域名下（不要使用不同的子域名）

如果使用 Cloudflare、Netlify 或 Vercel 等现代平台，上述大多数事情通常会自动完成。

如果所有 CSS 都已由 Nuxt 内联，还可以（实验性地）完全阻止渲染后的 HTML 中引用外部 CSS 文件——通过 build:manifest 钩子实现，钩子可以放在模块中，也可以直接写在 Nuxt 配置文件中：

export default defineNuxtConfig({
  hooks: {
    'build:manifest': (manifest) => {
      // find the app entry, css list
      const css = Object.values(manifest).find(options => options.isEntry)?.css
      if (css) {
        // start from the end of the array and go to the beginning
        for (let i = css.length - 1; i >= 0; i--) {
          // if it starts with 'entry', remove it from the list
          if (css[i].startsWith('entry')) {
            css.splice(i, 1)
          }
        }
      }
    },
  },
})

从源码结构看，这个钩子的存在与 features.inlineStyles 机制是一脉相承的：默认情况下 Nuxt 就会把组件与全局样式内联为 <style> 标签，SSRStylesPlugin 甚至会在"某个 CSS 文件的所有来源都已被内联"时自动从 client manifest 中丢弃对应的 <link>，并在渲染阶段按请求条件（ssrContext.modules 中实际渲染了哪些组件）决定某条样式链接是否可安全省略。手动操作 build:manifest 是对该自动化之外的进一步控制手段，使用前应确认内联范围确实覆盖了全部样式。

小结

Nuxt 的样式体系可以归纳为四层：

  1. 引入层：组件内 import / @import、css 配置全局引入、app.head / useHead 注入 <link>、Nitro render:html 钩子兜底；
  2. 处理层：Vite 内置预处理器支持、preprocessorOptions 注入 partial、PostCSS 插件（含默认排序与缺失提示）；
  3. 渲染层：样式内联进 SSR HTML（features.inlineStyles 与 SSRStylesPlugin 的去重逻辑）、外部样式表的渲染阻塞成本；
  4. 扩展层：布局隔离多套样式、第三方 CSS 框架/模块、字体加载与 LCP 优化手段。

掌握这些，你就能在 Nuxt 项目中按场景选择最合适的样式方案，并在需要时基于 packages/vite/src/css.ts、packages/vite/src/plugins/ssr-styles.ts 与 packages/schema/src/config/postcss.ts 等源码位置继续深挖其构建行为。

nuxt
the full-stack Vue framework
项目地址：https://gitcode.com/GitHub_Trending/nu/nuxt
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
856
1.35 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
529
593
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Markdown
77
23
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.13 K
2.74 K
docsdocs
暂无描述
Markdown
897
5.8 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.58 K
1.01 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
1.01 K
514
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
914
1.83 K
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
213
314