Slidev 的 UnoCSS 配置指南：默认预设、内置快捷键与扩展机制

本文以 Slidev 官方文档 配置 UnoCSS 为主体，系统讲解 UnoCSS 作为 Slidev 默认 CSS 框架的工作方式：开箱即用的预设与转换器、内置的 shortcuts 与自定义变体，以及如何通过 uno.config.ts 扩展配置。读完本文，你能够独立为幻灯片定制原子化样式、覆盖主题颜色，并理解 Slidev 在 Vite 插件层是如何合并你的配置与内置配置的。

UnoCSS 是 Slidev 的默认 CSS 框架

自 v0.42.0 起，UnoCSS 取代了此前的 CSS 方案，成为 Slidev 的默认 CSS 框架。UnoCSS 是一个快速、完全可扩展的原子化 CSS 引擎，它默认支持了 Tailwind CSS 的大多数类名，因此你在 Slidev 的 Markdown 幻灯片中写 Tailwind 风格类名时，无需任何额外配置即可生效。

根据官方文档，Slidev 默认启用以下能力：

• @unocss/preset-wind3 — Tailwind / Windi CSS 兼容的实用类
• @unocss/preset-attributify — Attributify 模式（将类拆分为属性书写）
• @unocss/preset-icons — 将任意图标作为 class 使用
• @unocss/transformer-directives — 在 CSS 中使用 @apply

对照当前仓库的源码 packages/client/uno.config.ts，客户端配置中实际启用的预设与转换器为：

presets: [
  presetWind3(),
  presetAttributify(),
  presetTypography(),
  /* Preset Icons is added in ../node/setups/unocss.ts */
],
transformers: [
  transformerDirectives({ enforce: 'pre' }),
  transformerVariantGroup(),
],
extractors: [
  extractorMdc(),
],

其中有两点值得注意：

• 图标预设 presetIcons 不在客户端配置里，而是由 Node 端的 packages/slidev/node/setups/unocss.ts 单独注入（见下文「图标预设与主题令牌」一节）；
• extractorMdc 是专为 Markdown 内容定制的类名提取器，保证类名能从 .md 幻灯片中被正确扫描出来。

有了这些预设，你可以像示例中这样直接在幻灯片里排版内容：

<div class="grid pt-4 gap-4 grid-cols-[100px,1fr]">

### Name

- Item 1
- Item 2

</div>

内置 Shortcuts：Slidev 自带的一组"魔法类"

官方文档指出，Slidev 在内置配置中额外添加了一系列 shortcuts。它们的完整定义位于 packages/client/uno.config.ts，可以归纳为四类：

1. 主题颜色与背景

Shortcut	展开为
bg-main	bg-white dark:bg-[#121212]
bg-active	bg-gray-400/10
border-main	border-gray/20
text-main	text-[#181818] dark:text-[#ddd]
text-primary / bg-primary / border-primary	对应 color-$slidev-theme-primary / bg-$slidev-theme-primary / border-$slidev-theme-primary

其中 *-primary 系列引用了 CSS 变量 $slidev-theme-primary，也就是当前主题的主色，这使它们能随主题自动换色。

2. 绝对定位缩写：abs-tl、abs-tr、abs-b、abs-bl、abs-br，分别对应 absolute top-0 left-0 等组合，方便在幻灯片中把元素钉在四角或底边。

3. 层级 z-index 规范：从 z-drawing（z-10）到 z-camera（z-15）、z-dragging（z-18）、z-menu（z-20）、z-label（z-40）、z-nav（z-50）、z-context-menu（z-60）、z-modal（z-70），直到 z-focus-indicator（z-200）。这套命名保证了 Slidev 内部 UI 层级的稳定排序。

4. 玻璃拟态效果：slidev-glass-effect 展开为 shadow-xl backdrop-blur-8 border border-main bg-main bg-opacity-75!，一行类即可做出毛玻璃面板。

此外，客户端配置还维护了一份 safelist（!opacity-0、prose、grid-rows-[1fr_max-content] 等）。由于 UnoCSS 只生成"被扫描到"的类，这些类即便只出现在 Slidev 客户端组件中、未出现在你的幻灯片里，也必须被预先生成——所以被显式列入 safelist。更彻底的做法见 packages/client/scripts/unocss-scan.ts：它用 UnoCSS 生成器扫描所有 packages/client/**/*.vue 文件，把命中的令牌写入 .generated/unocss-tokens.ts 作为 safelist 供运行时加载（在 packages/slidev/node/setups/unocss.ts 中通过 safelist: await loadModule(resolve(clientRoot, '.generated/unocss-tokens.ts')) 注入）。

自定义变体：forward: 与 backward:

内置配置还注册了两个 Slidev 专属变体（packages/client/uno.config.ts 第 47–52 行）：

variants: [
  variantMatcher('forward', input => ({ prefix: `.slidev-nav-go-forward ${input.prefix}` })),
  variantMatcher('backward', input => ({ prefix: `.slidev-nav-go-backward ${input.prefix}` })),
],

导航前进时，Slidev 会给幻灯片容器加上 .slidev-nav-go-forward，后退时加上 .slidev-nav-go-backward。利用这两个变体，你可以让同一元素在两个方向上表现不同，例如：

<div v-click class="transition forward:delay-300">Element</div>

上面的过渡延迟只在"前进"方向生效，后退时立即完成。该功能的完整用法见 导航方向变体。

扩展内置配置：在你的项目中创建 uno.config.ts

这是官方文档给出的核心操作：在项目根目录创建 uno.config.ts 文件来扩展内置配置。官方示例——自定义默认背景：

import { defineConfig } from 'unocss'

export default defineConfig({
  shortcuts: {
    // custom the default background
    'bg-main': 'bg-white text-[#181818] dark:(bg-[#121212] text-[#ddd])',
  },
  // ...
})

这里的 bg-main 恰好覆盖了内置 shortcut 的同名定义，从而改变全局默认背景。由于 shortcuts、rules、theme 等都是可合并的字段，你也可以在 rules 里定义全新的原子类、在 theme 里改字体族与颜色板、或用 presets 追加自己的预设。

配置是如何被加载和合并的

从源码可以确认，用户配置并非简单"覆盖"，而是按固定顺序被合并。核心逻辑在 packages/slidev/node/setups/unocss.ts：

1. 候选文件名：根目录下的 uno.config.ts 与 unocss.config.ts 都会被检查（loadFileConfigs 中两者均存在则均被加载），因此两个文件名都可用；
2. 合并顺序：mergeConfigs 依次合并——内置的图标预设配置 → 客户端 uno.config.ts → 各根目录（项目、主题等）通过 loadSetups 加载的 setup/unocss.ts 与根配置文件。后者在前，意味着你的配置优先级更高，同名字段会覆盖内置值；
3. 字体自动注入：合并完成后，Slidev 还会从 frontmatter 的字体配置中读取 sans / mono / serif 字体栈，写入 config.theme.fontFamily（若未被显式设置），因此你在 uno.config.ts 中不需要手动配置字体族即可使用 font-sans、font-mono 等类。

最终这份配置经由 packages/slidev/node/vite/unocss.ts 交给 UnoCSS 的 Vite 插件：

return UnoCSS({
  configFile: false,
  ...await setupUnocss(options),
  ...pluginOptions.unocss,
})

注意 configFile: false——UnoCSS 不会自己去猜测配置文件，而是完全采用上面构建好的合并结果，保证行为确定可控。

另外两种扩展入口

除根目录配置文件外，源码结构还揭示了两个扩展点：

• setup/unocss.ts：packages/slidev/node/setups/load.ts 会加载每个根目录下 setup/unocss.ts 中的默认导出函数，返回一个 Partial<UnoCssConfig>。其类型 UnoSetup 与辅助函数 defineUnoSetup 定义在 packages/types/src/setups.ts（第 87 行与第 113 行）。相比静态配置文件，函数形式允许你根据主题、命令行参数等运行时信息动态返回配置，是主题作者定制样式的推荐方式；
• vite.config.ts 中的高级选项：packages/types/src/vite.ts 中 SlidevPluginOptions 暴露了 unocss 字段（类型即 UnoCSS Vite 插件的完整配置）。在 createUnocssPlugin 里它位于展开顺序的最后，因此是优先级最高的一层，适合需要精细控制插件行为的场景。

图标预设与主题令牌

packages/slidev/node/setups/unocss.ts 中注入的 presetIcons 配置了两样东西：

• collectionsNodeResolvePath: utils.iconsResolvePath：让图标集合的解析路径对齐项目的 Node 解析环境，从而可以使用 @iconify-json 系列任意图标集；
• 名为 slidev 的内置集合，仅含一个 logo 图标，内容是客户端资源 packages/client/assets/logo.svg 的文本。

配合 attributify 与 icons 预设，你就可以直接写出 i-slidev-logo、i-carbon-sun 这类类名来使用图标，无需引入图标组件。

在 CSS 中使用 @apply

由于启用了 transformerDirectives({ enforce: 'pre' })，你可以在任意 <style> 或 CSS 文件中使用 UnoCSS 原子类。仓库内部就有典型用例，例如 packages/client/internals/CodeRunner.vue 中：

@apply px-5 py-3 flex-grow text-xs leading-[.8rem] font-$slidev-code-font-family select-text;

@apply 后面跟的正是原子类与主题变量，这让"组件级样式"与"行内原子类"可以混用而不失一致性。

小结与验证路径

回到官方文档的主线：UnoCSS 是 Slidev 自 v0.42.0 起的默认 CSS 框架，默认启用 wind3 / attributify / icons / typography 预设与 directives 转换器；你想改样式时，在项目根目录建一个 uno.config.ts（unocss.config.ts 亦可）用 defineConfig 扩展即可。结合源码可以补充三点实操认知：

1. 你的配置按"你的配置优先"的顺序与内置配置合并，覆盖内置 shortcut（如 bg-main）是最常见的定制方式；
2. 主题作者建议用 setup/unocss.ts + defineUnoSetup 的函数式入口，而不是硬编码配置文件；
3. 若自定义类"写了却不生效"，先确认类名出现在被扫描的源码中——对仅在客户端组件使用的类，参考 safelist 机制（packages/client/scripts/unocss-scan.ts）的原理，在 uno.config.ts 中显式加入 safelist。

相关入口文件：packages/client/uno.config.ts、packages/slidev/node/setups/unocss.ts、packages/slidev/node/vite/unocss.ts、packages/types/src/setups.ts。