Vite插件

Vite 插件 unocss包.

安装

pnpmyarnnpm

bash

pnpm add -D unocss

bash

yarn add -D unocss

bash

npm install -D unocss

安装插件:

// vite.config.ts
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS(),
  ],
})

创建一个uno.config.ts文件:

// uno.config.ts
import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSS选项
})

添加 virtual:uno.css 到main入口:

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

模式

Vite插件提供了一组模式，可以实现不同的行为。

`global`（默认）

这是插件的默认模式：在这种模式下，您需要在入口点添加 uno.css的导入。

此模式为build和dev启用了一组Vite插件，并支持HMR。

生成的css将是在index.html上注入的全局样式表。

`vue-scoped`

此模式将生成的CSS注入Vue SFCs<style scoped>以进行隔离。

`svelte-scoped`

svelte-scoped 模式已移至其自己的包，请参见 @unocss/svelte-scoped/vite。

`shadow-dom`

由于Web Components使用Shadow DOM，因此无法直接从全局样式表对内容进行样式设置（除非使用CSS自定义属性，否则这些属性将穿透Shadow DOM），因此需要将插件生成的CSS内联到Shadow DOM样式中。

要内联生成的CSS，您只需要将插件模式配置为shadow-dom，并在每个web组件样式的CSS块上包含@unocss-placeholder。如果您在VueSFC中定义Web组件，并希望在UnoCSS旁边定义自定义样式，则可以将占位符包装在CSS注释中，以避免IDE中出现语法错误。

`per-module`（实验性）

此模式将为每个模块生成一个CSS表，可以确定范围。

`dist-chunk`（实验性）

这种模式将为构建时的每个代码块生成一个CSS表，非常适合MPA。

在DevTools中编辑类

因为"按需"的限制，DevTools不知道那些你还没有在源代码中使用过的东西。因此，如果你想通过直接更改DevTools中的类来尝试如何工作，只需在主条目中添加以下行即可。

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

警告

请谨慎使用，在底层我们使用 MutationObserver 来检测类的变化。这意味着不仅是你的手动更改，还包括脚本标签中逻辑所做的更改也将被检测并包含在样式表中。这可能会导致开发和生产构建之间的一些不一致，当你根据脚本标签中的某些逻辑添加动态类时。我们建议将动态部分添加到安全列表，或者尽可能为生产构建设置 UI 回归测试。

框架

一些UI/App框架有一些必须解决的注意事项，如果您使用以下框架之一，请应用这些建议。

VanillaJS / TypeScript

使用 VanillaJS 或 TypeScript 时，需要添加 js 和 ts 文件扩展名以允许 UnoCSS 读取和解析内容，默认情况下 js 和 ts 文件被排除，请查看从构建工具管道中提取部分。

React

如果你使用 @vitejs/plugin-react：

// vite.config.js
import UnoCSS from 'unocss/vite'
import React from '@vitejs/plugin-react'

export default {
  plugins: [
    React(),
    UnoCSS(),
  ],
}

如果你使用 @unocss/preset-attributify，应该从 build 脚本中删除 tsc。

如果你使用 @vitejs/plugin-react 和 @unocss/preset-attributify，必须在 @vitejs/plugin-react 之前添加插件。

// vite.config.js
import UnoCSS from 'unocss/vite'
import React from '@vitejs/plugin-react'

export default {
  plugins: [
    UnoCSS(),
    React(),
  ],
}

你可以在 examples/vite-react 目录中找到一个使用这两个插件的 React 示例项目，请查看 package.json 中的脚本和 Vite 配置文件。

Preact

如果你使用 @preact/preset-vite：

// vite.config.js
import Preact from '@preact/preset-vite'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    Preact(),
  ],
}

或者如果你使用 @prefresh/vite：

// vite.config.js
import Prefresh from '@prefresh/vite'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    Prefresh(),
  ],
}

如果你使用 @unocss/preset-attributify，应该从 build 脚本中删除 tsc。

你可以在 examples/vite-preact 目录中找到一个使用这两个插件的 Preact 示例项目，请查看 package.json 中的脚本和 Vite 配置文件。

Svelte

必须在 @sveltejs/vite-plugin-svelte 之前添加插件。

要支持 class:foo 和 class:foo={bar}，请添加插件并在 extractors 选项中配置 extractorSvelte。

你可以对 class: 使用简单规则，例如 class:bg-red-500={foo} 或使用 shortcuts 包含多个规则，请参见下面链接的示例项目中的 src/App.svelte。

// vite.config.js
import { svelte } from '@sveltejs/vite-plugin-svelte'
import UnoCSS from 'unocss/vite'
import extractorSvelte from '@unocss/extractor-svelte'

export default {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* 更多选项 */
    }),
    svelte(),
  ],
}

Sveltekit

要支持 class:foo 和 class:foo={bar}，请添加插件并在 extractors 选项中配置 extractorSvelte。

你可以对 class: 使用简单规则，例如 class:bg-red-500={foo} 或使用 shortcuts 包含多个规则，请参见下面链接的示例项目中的 src/routes/+layout.svelte。

// vite.config.js
import { sveltekit } from '@sveltejs/kit/vite'
import UnoCSS from 'unocss/vite'
import extractorSvelte from '@unocss/extractor-svelte'

/** @type {import('vite').UserConfig} */
const config = {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* 更多选项 */
    }),
    sveltekit(),
  ],
}

Web Components

要与 web components 一起工作，你需要在插件上启用 shadow-dom 模式。

不要忘记删除 uno.css 的导入，因为 shadow-dom 模式不会暴露它，应用程序将无法工作。

// vite.config.js
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
    }),
  ],
}

示例

基本示例

你可以在 examples/vite-basic 目录中找到一个基本的 Vite 示例项目。

框架示例

我们为不同的框架提供了示例项目：

性能

缓存

为了提高性能，UnoCSS 使用了一个内存缓存。在大多数情况下，这是自动处理的。但是，如果你想禁用缓存或自定义缓存行为，你可以在配置中进行设置：

// uno.config.ts
export default defineConfig({
  // 禁用缓存
  cacheDisabled: true,
  
  // 自定义缓存大小（默认为 0，表示无限制）
  cachePrefixKey: 'my-custom-prefix',
  
  // 自定义缓存失效时间（默认为 0，表示永不过期）
  cacheExpireTime: 60 * 60 * 1000, // 1小时
})

性能提示

尽可能使用 shortcuts 来减少生成的 CSS 大小
避免使用过于复杂的动态类
使用 safelist 预生成频繁使用的类

故障排除

类未生成

如果某些类没有被生成，请检查：

确保类名完全匹配
检查 uno.config.ts 中的提取器配置
使用 safelist 强制生成特定类

// uno.config.ts
export default defineConfig({
  safelist: [
    'font-bold',
    'text-lg',
    // 其他需要强制生成的类
  ],
})

开发模式性能问题

如果在大型项目中遇到性能问题，可以尝试：

限制提取的文件范围
优化提取器配置
使用更具体的类名选择器

高级用法

动态类生成

你可以使用函数动态生成类：

// uno.config.ts
export default defineConfig({
  rules: [
    [/^custom-(\d+)$/, ([, d]) => ({ 'padding-top': `${Number(d) * 10}px` })],
  ],
})

条件变体

创建基于条件的变体：

// uno.config.ts
export default defineConfig({
  variants: [
    (matcher) => {
      if (matcher.startsWith('admin:')) {
        return {
          matcher: matcher.slice(6),
          selector: s => `body.admin ${s}`,
        }
      }
    },
  ],
})

使用示例：

html

<div class="admin:text-red-500">仅在管理员模式下显示红色文本</div>

Vite插件 ​

安装 ​

模式 ​

global（默认） ​

vue-scoped ​

svelte-scoped ​

shadow-dom ​

per-module（实验性） ​

dist-chunk（实验性） ​

在DevTools中编辑类 ​

框架 ​

VanillaJS / TypeScript ​

React ​

Preact ​

Svelte ​

Sveltekit ​

Web Components ​

示例 ​

基本示例 ​

框架示例 ​

性能 ​

缓存 ​

性能提示 ​

故障排除 ​

类未生成 ​

开发模式性能问题 ​

高级用法 ​

动态类生成 ​

条件变体 ​

License ​

Vite插件

安装

模式

`global`（默认）

`vue-scoped`

`svelte-scoped`

`shadow-dom`

`per-module`（实验性）

`dist-chunk`（实验性）

在DevTools中编辑类

框架

VanillaJS / TypeScript

React

Preact

Svelte

Sveltekit

Web Components

示例

基本示例

框架示例

性能

缓存

性能提示

故障排除

类未生成

开发模式性能问题

高级用法

动态类生成

条件变体

License