企业官网建设流程全解析

• AI 技能
• 人工智能

本篇指南覆盖 UnoCSS 在 Vite 体系下的完整集成方案：从unocss/vite插件的安装与配置入手，详解 global、vue-scoped、shadow-dom 等五种渲染模式的工作方式与适用场景，并给出 React、Vue、Svelte、Solid、Preact、Elm 等框架的插件组合顺序、提取器配置与遗留浏览器兼容写法。读完本文，你可以在任意 Vite 前端项目中正确接入 UnoCSS，并按需选择提取范围、CSS 作用域策略与 Inspector 调试方式。

该指南内容整理自本仓库为 Agent 生成的 UnoCSS 技能文档（基于 UnoCSS v66.10.5，生成于 2026-09-25，见 生成信息），原始技能文件位于 integrations-vite.md，技能索引见 SKILL.md。

安装与基础接入

UnoCSS 的核心是不带任何主观约定的原子化 CSS 引擎，所有工具类均由 preset 提供，因此 Vite 插件是它最常见的使用入口。接入分三步：安装依赖、注册 Vite 插件、创建配置文件并在入口注入生成的 CSS。

pnpm add -D unocss

在vite.config.ts中注册插件：

// vite.config.ts import UnoCSS from 'unocss/vite' import { defineConfig } from 'vite' export default defineConfig({ plugins: [ UnoCSS(), ], })

创建配置文件（UnoCSS 会自动在项目根目录查找uno.config.{js,ts,mjs,mts}或unocss.config.{js,ts,mjs,mts}，推荐使用独立的uno.config.ts以获得更好的 IDE 支持与 HMR 体验）：

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

最后在入口文件中注入虚拟样式模块：

// main.ts import 'virtual:uno.css'

virtual:uno.css是 Vite 插件提供的虚拟模块：构建时它会把 UnoCSS 根据源码中实际扫描到的工具类按需生成的 CSS 注入进来。这意味着你无需手写任何 CSS 文件，样式完全由代码中的类名驱动。配置项的完整语义（rules、shortcuts、theme、transformers、layers等）详见 配置参考。

提示：如果你正在为 Agent 编写技能或协作指令，建议先检查项目根目录是否存在uno.config.*或unocss.config.*，以了解当前项目可用的 preset、rules 与 shortcuts；在未弄清项目配置前，优先使用基础class用法，避免贸然使用 attributify 等进阶特性（见 技能说明）。

五种渲染模式：CSS 如何进入你的应用

UnoCSS 通过插件的mode选项控制生成 CSS 的注入位置。不同渲染策略决定了样式的作用域、注入时机以及是否依赖@unocss-placeholder占位符。

global（默认模式）

标准模式：生成一份全局 CSS，通过uno.css导入注入整个应用。这是绝大多数项目的默认选择：

import 'virtual:uno.css'

生成的样式是无作用域限制的，任何模块里出现的工具类都会参与提取与输出。

vue-scoped

将生成的 CSS 直接注入到 Vue SFC 的<style scoped>块中，使工具类天然享有 Vue 组件的作用域隔离能力：

UnoCSS({ mode: 'vue-scoped', })

适用于希望原子类遵循 Vue scoped 语义（避免跨组件样式泄漏）的 Vue 项目。

shadow-dom

面向使用 Shadow DOM 的 Web Components：由于全局 CSS 无法穿透 Shadow DOM 边界，此模式下 UnoCSS 将生成的样式注入到组件的<style>占位符处：

UnoCSS({ mode: 'shadow-dom', })

在组件模板风格中放置占位注释，构建时它会被替换为实际生成的 CSS：

const template = document.createElement('template') template.innerHTML = ` <style> :host { ... } @unocss-placeholder </style> <div class="m-1em">...</div> `

per-module（实验性）

按模块粒度生成 CSS，并支持可选的作用域隔离，适合需要按模块拆分样式的场景。

dist-chunk（实验性）

在构建（build）时按 chunk 粒度生成 CSS，面向 MPA（多页应用）这类每页独立产物、希望样式随 chunk 切分的场景。

后两种模式目前标记为实验性，接入生产项目前应先在非关键路径验证。

DevTools 支持：在浏览器中直接改类

引入 DevTools 虚拟模块后，可以直接在浏览器开发者工具的 Elements 面板里编辑 class 名，UnoCSS 会实时把新增的工具类加入生成集合：

import 'virtual:uno.css' import 'virtual:unocss-devtools'

需要注意的限制：该功能基于MutationObserver检测 DOM 变化，因此脚本动态添加的类名也会被一并收录进最终产物。如果项目中存在大量运行时动态类，评估其对产物体积的影响后再决定是否启用。

各框架接入要点

以下配置均沿用原文档给出的插件写法，重点在于插件顺序与提取器——它们决定了工具类能否被正确扫描。

React

// vite.config.ts import React from '@vitejs/plugin-react' import UnoCSS from 'unocss/vite' export default { plugins: [ UnoCSS(), // 使用 attributify 时必须放在 React 之前 React(), ], }

两个关键约束：

• 若启用了@unocss/preset-attributify（以属性形式分组工具类的 preset，参考 preset-attributify），UnoCSS 插件必须排在 React 插件之前，以便在 JSX 转换前完成提取与转换；
• 同样使用 attributify 时，需把tsc从 build 脚本中移除，否则类型检查会因 JSX 中的属性化类名报错。

Vue

配合@vitejs/plugin-vue开箱即用，无需额外提取器——.vue文件默认就在 pipeline 提取范围内（见下文提取范围说明）。

Svelte

Svelte 的单文件组件不在默认提取列表内，需要显式注册 Svelte 提取器：

import { svelte } from '@sveltejs/vite-plugin-svelte' import extractorSvelte from '@unocss/extractor-svelte' import UnoCSS from 'unocss/vite' export default { plugins: [ UnoCSS({ extractors: [extractorSvelte()], }), svelte(), ], }

该提取器支持 Svelte 的class:foo与class:foo={bar}条件类语法，保证这类动态绑定中的工具类也能被提取。

SvelteKit

配置方式与 Svelte 相同，区别是插件使用@sveltejs/kit/vite导出的sveltekit()。另一个差异是 SvelteKit 默认全局模式下没有main.ts这样的应用入口，需要改为从根布局引入样式：

<!-- src/routes/+layout.svelte --> <script> import 'virtual:uno.css' </script>

Solid

import UnoCSS from 'unocss/vite' import solidPlugin from 'vite-plugin-solid' export default { plugins: [ UnoCSS(), solidPlugin(), ], }

Preact

import Preact from '@preact/preset-vite' import UnoCSS from 'unocss/vite' export default { plugins: [ UnoCSS(), Preact(), ], }

Elm

import Elm from 'vite-plugin-elm' import UnoCSS from 'unocss/vite' export default { plugins: [ Elm(), UnoCSS(), ], }

Web Components（Lit）

Lit 组件通过 Shadow DOM 封装样式，因此组合shadow-dom模式与 shortcuts，得到组件内部的原子类：

UnoCSS({ mode: 'shadow-dom', shortcuts: [ { 'cool-blue': 'bg-blue-500 text-white' }, ], })

// my-element.ts @customElement('my-element') export class MyElement extends LitElement { static styles = css` :host { ... } @unocss-placeholder ` }

@unocss-placeholder在 Lit 的static styles中同样生效。此外，shadow-dom 模式支持part-[<part-name>]:<utility>语法，用于针对元素的::part()选择器生成样式，从而从组件外部定制内部 part 的样式。

提取范围：为什么 .js/.ts 默认不扫描

Vite 集成下，UnoCSS 采用pipeline 提取——直接从构建管线中扫描经过的文件，这是最高效的方式。默认提取的文件类型为：.jsx、.tsx、.vue、.md、.html、.svelte、.astro、.marko；而.js和.ts默认不在提取范围内（因为普通 JS/TS 文件中极少出现类名，跳过它们可节省扫描成本）。

如果你的类名写在.js/.ts文件中（常见于封装 UI 库的样式常量），有两种解决办法：

方案一：在配置中扩展 pipeline 提取范围：

// uno.config.ts export default defineConfig({ content: { pipeline: { include: [ /\.(vue|svelte|[jt]sx|html)($|\?)/, 'src/**/*.{js,ts}', ], }, }, })

方案二：在文件顶部使用魔法注释@unocss-include强制扫描单个文件：

// @unocss-include export const classes = { active: 'bg-primary text-white', }

魔法注释体系还包括@unocss-ignore（跳过整个文件）与@unocss-skip-start/@unocss-skip-end（跳过指定代码块），完整的提取机制（文件系统提取、内联文本提取、自定义提取器、动态类名的局限性与 safelist 解法）参见 提取参考。

需要牢记的前提是：UnoCSS 工作在构建时，class="p-${size}"这类运行时拼接的类名不会被提取，需通过 safelist 预生成、静态映射表或运行时方案解决。

Inspector：可视化调试生成结果

开发模式下访问http://localhost:5173/__unocss（端口随 Vite dev server 实际端口而定）即可打开内置 Inspector，用于：

• 检视最终生成的 CSS 规则；
• 按文件查看每处应用了哪些类；
• 在 REPL 中试用任意工具类，即时查看其生成结果。

这是排查「类名为什么没生效」类问题的第一现场：先确认目标文件是否处于提取范围、类名是否被 blocklist 过滤、variant 前缀是否写对，再回头核对配置。

遗留浏览器兼容：配合 @vitejs/plugin-legacy

当使用@vitejs/plugin-legacy做降级构建时，需让 UnoCSS 与 legacy 插件的 chunk 渲染策略对齐，关闭现代 chunk 渲染：

import legacy from '@vitejs/plugin-legacy' import UnoCSS from 'unocss/vite' export default { plugins: [ UnoCSS({ legacy: { renderModernChunks: false, }, }), legacy({ targets: ['defaults', 'not IE 11'], renderModernChunks: false, }), ], }

即两边同时设置renderModernChunks: false，让 UnoCSS 只随 legacy chunk 输出样式，避免现代产物与降级产物之间的 CSS 不一致。

小结与延伸阅读

Vite 集成是 UnoCSS 的主战场：插件负责虚拟模块virtual:uno.css、pipeline 提取、Inspector 与 DevTools，mode选项决定样式注入位置（全局、Vue scoped、Shadow DOM 占位符或按模块/chunk 切分），框架差异主要体现为插件顺序与提取器的组合。配套技能文档可进一步深入：

• 配置参考：uno.config.ts全部选项（rules、shortcuts、theme、content、layers 等）；
• 提取机制：pipeline/filesystem/inline 三种提取源与魔法注释；
• Preset Wind3 与 Preset Attributify：最常用的两个 preset；
• Nuxt 集成：Nuxt 场景下对应的模块方案。

• AI 技能
• 人工智能