企业官网建设流程全解析

• AI 技能
• 人工智能

本文以 UnoCSS 官方 Nuxt 模块@unocss/nuxt为主线，系统讲解在 Nuxt 应用中接入 UnoCSS 的完整流程：依赖安装、uno.config.ts配置文件组织、nuxtLayers配置合并机制，以及开发态 Inspector 的使用方法。读完后你将能够在 Nuxt 2/3 项目中落地一套包含 preset、transformer 与 shortcut 的原子化 CSS 方案，并理解其与纯 Vite 集成方式的关键差异。

一、为什么选择 @unocss/nuxt 模块

UnoCSS 是一个即时原子化 CSS 引擎，核心不绑定任何具体 CSS 规则——所有工具类都由 preset 提供，是 Tailwind CSS 的超集，可以直接复用 Tailwind 的语法知识。在 Nuxt 应用中，UnoCSS 提供了官方 Nuxt 模块@unocss/nuxt，相比手动配置 Vite 插件，模块的最大价值在于：

• 自动注入uno.css入口：无需手动import 'virtual:uno.css'，模块会自动完成样式入口的注入；
• 配置文件发现机制一致：与 Vite 集成方式相同，UnoCSS 会自动查找项目根目录下的uno.config.{js,ts,mjs,mts}或unocss.config.{js,ts,mjs,mts}（详见 core-config 参考）；
• 继承 Vite 插件的全部能力：所有 Vite 插件提供的功能在 Nuxt 模块中均可用；
• 支持 Nuxt Layers 配置合并：可将多个 Nuxt layer 中的 UnoCSS 配置自动合并到根配置中，这是 Nuxt 生态独有的增强能力。

一个来自仓库 skill 约定（skills/unocss/SKILL.md）的实用提示：在编写 UnoCSS 代码之前，应先检查项目根目录是否存在uno.config.*或unocss.config.*文件，了解项目已启用的 presets、rules 与 shortcuts。如果项目配置不明，应避免使用 attributify 等高级特性，坚持基础class用法。

二、安装与最小化配置

2.1 安装依赖

以 pnpm 为例安装两个依赖：unocss本体与 Nuxt 模块：

pnpm add -D unocss @unocss/nuxt

2.2 注册模块

在nuxt.config.ts的modules中注册@unocss/nuxt：

// nuxt.config.ts export default defineNuxtConfig({ modules: [ '@unocss/nuxt', ], })

2.3 创建 uno.config.ts

在项目根目录创建独立的 UnoCSS 配置文件，这是官方推荐的组织方式（对 IDE 支持和 HMR 最友好）：

// uno.config.ts import { defineConfig, presetWind3 } from 'unocss' export default defineConfig({ presets: [ presetWind3(), ], })

注意：模块会自动注入uno.css入口，Nuxt 项目中不需要（也不应该）手动引入虚拟样式文件。

三、构建工具支持矩阵

不同 Nuxt 版本对 Webpack 与 Vite 两种构建器的支持情况如下：

从该矩阵可以看出：Nuxt 3 已全面转向 Vite/Rspack 生态，Webpack Dev 模式尚在完善（🚧 标记）；Nuxt 2 与 Nuxt Bridge 则同时兼容 Webpack 与 Vite 两条链路。选型时应以当前项目的 Nuxt 版本与构建器组合为准。

四、推荐的配置组织方式

4.1 使用独立 uno.config.ts（推荐）

将 UnoCSS 配置放在独立的uno.config.ts中，而不是内联到nuxt.config.ts，可以获得完整的类型推导与 IDE 支持。在最小配置基础上加入图标 preset 与 shortcut：

// uno.config.ts import { defineConfig, presetWind3, presetIcons } from 'unocss' export default defineConfig({ presets: [ presetWind3(), presetIcons(), ], shortcuts: { 'btn': 'py-2 px-4 font-semibold rounded-lg', }, })

其中：

• presetWind3()提供与 Tailwind CSS v3 兼容的工具类集合，是最常用的基础 preset（详见 preset-wind3 参考）；
• presetIcons()基于 Iconify 将任意图标集合渲染为纯 CSS 类，例如class="i-mdi-alarm text-orange-400"，可配合scale选项调整相对字号的缩放比例（详见 preset-icons 参考）；
• shortcuts把多个工具类合并为单个语义化简写，如btn，在模板中以class="btn"使用（详见 core-shortcuts 参考）。

4.2 Nuxt Layers 支持：自动合并多层配置

这是@unocss/nuxt模块相较纯 Vite 集成的核心增强。在nuxt.config.ts中开启nuxtLayers：

// nuxt.config.ts export default defineNuxtConfig({ unocss: { nuxtLayers: true, }, })

开启后，模块会收集各 Nuxt layer（通过extends引入的共享层，参考 Nuxt Layers 文档）中声明的 UnoCSS 配置并自动合并。在根配置中直接引用合并产物：

// uno.config.ts import config from './.nuxt/uno.config.mjs' export default config

如果需要在合并结果之上做本地覆盖，用@unocss/core导出的mergeConfigs将本地配置追加在后（后者优先）：

// uno.config.ts import { mergeConfigs } from '@unocss/core' import config from './.nuxt/uno.config.mjs' export default mergeConfigs([config, { // Your overrides shortcuts: { 'custom': 'text-red-500', }, }])

这种模式适合 monorepo 或团队共享 UI layer 的场景：基础层提供默认 preset 与主题 token，应用层只写差异化覆盖，避免配置复制。

五、一个完整的实战配置示例

以下是官方文档给出的常见完整配置，组合了 presetWind3、attributify、icons、typography、web fonts 以及两个 transformer：

// nuxt.config.ts export default defineNuxtConfig({ modules: [ '@unocss/nuxt', ], })

// uno.config.ts import { defineConfig, presetAttributify, presetIcons, presetTypography, presetWebFonts, presetWind3, transformerDirectives, transformerVariantGroup, } from 'unocss' export default defineConfig({ presets: [ presetWind3(), presetAttributify(), presetIcons({ scale: 1.2, }), presetTypography(), presetWebFonts({ fonts: { sans: 'DM Sans', mono: 'DM Mono', }, }), ], transformers: [ transformerDirectives(), transformerVariantGroup(), ], shortcuts: [ ['btn', 'px-4 py-1 rounded inline-block bg-teal-600 text-white cursor-pointer hover:bg-teal-700 disabled:cursor-default disabled:bg-gray-600 disabled:opacity-50'], ], })

各部分的作用可对照仓库内参考文档逐一理解：

• presetAttributify()：把工具类从class字符串迁移到独立 HTML 属性上，如<div p="4" text="center">，适合长 class 串的语义化场景（详见 preset-attributify 参考）；
• presetTypography()：提供prose等排版类，处理富文本/Markdown 渲染容器的默认排版；
• presetWebFonts()：声明sans/mono等字体族映射，自动拉取 Google Fonts 等网络字体；
• transformerDirectives()：在 CSS 中启用@apply、@screen、theme()、icon()指令，例如@apply py-2 px-4 font-semibold rounded-lg;（详见 transformer-directives 参考）；
• transformerVariantGroup()：启用变体分组简写，如hover:(bg-gray-400 font-medium)会被展开为hover:bg-gray-400 hover:font-medium（详见 transformer-variant-group 参考）。

六、在 Vue 组件中使用

配置完成后，直接在组件模板里书写工具类即可，UnoCSS 会自动从源码中提取类名并即时生成 CSS：

<template> <div class="p-4 text-center"> <h1 class="text-3xl font-bold text-blue-600"> Hello UnoCSS! </h1> <button class="btn mt-4"> Click me </button> </div> </template>

其中btn即上文shortcuts中定义的简写，会展开为完整的按钮样式串。

若已启用presetAttributify()，同一界面也可以写成属性分组形式：

<template> <div p="4" text="center"> <h1 text="3xl blue-600" font="bold"> Hello UnoCSS! </h1> </div> </template>

属性名对应前缀：p展开为 padding 系列、text展开为文字相关工具、font展开为字体工具。当属性名与 HTML 原生属性冲突时可用un-前缀（如un-text="red"）；对 TypeScript 严格检查的 Vue 3 项目，可按 preset-attributify 参考 中的html.d.ts声明放开自定义属性类型。

七、开发态 Inspector

在开发模式下，访问/_nuxt/__unocss即可打开 UnoCSS Inspector 面板，用于：

• 查看当前生成的 CSS 规则；
• 查看各个文件中实际应用了哪些类；
• 在 REPL 中试验新的工具类组合。

对比 Vite 集成方式（访问http://localhost:5173/__unocss，见 integrations-vite 参考），Nuxt 环境下 Inspector 的路径前缀是/_nuxt/，这是由 Nuxt 的构建产物路由规则决定的。

八、与 Vite 集成的关键差异

@unocss/nuxt本质上是 Vite 插件能力的 Nuxt 封装，两者的差异点值得明确：

另外，Vite 插件支持的注入模式（global / vue-scoped / shadow-dom 等，见 integrations-vite 参考）在 Nuxt 模块中同样可用；但 Nuxt 场景下默认 global 模式配合自动注入的uno.css入口已足够，无需额外调整。

九、落地检查清单

1. 执行pnpm add -D unocss @unocss/nuxt并在nuxt.config.ts的modules中注册；
2. 项目根目录创建uno.config.ts，至少声明presets: [presetWind3()]；
3. 确认不需要手动引入virtual:uno.css（模块自动注入）；
4. 如项目使用 Nuxt layers 且希望共享 UnoCSS 配置，开启unocss.nuxtLayers: true并引用.nuxt/uno.config.mjs；
5. 开发模式下访问/_nuxt/__unocss验证 Inspector 与生成的 CSS；
6. 按当前 Nuxt 版本与构建器组合核对第三节的支持矩阵，Nuxt 3 下优先使用 Vite/Rspack 链路。

以上所有配置项（rules、theme、variants、safelist、content、outputToCssLayers等）的完整说明可参考 core-config 参考，preset 与 transformer 的细节分别参见上文各链接指向的参考文档。

• AI 技能
• 人工智能