UnoCSS 样式提取机制深度解析

UnoCSS 样式提取机制深度解析

unocss The instant on-demand atomic CSS engine. 项目地址: https://gitcode.com/gh_mirrors/un/unocss

什么是样式提取

UnoCSS 的核心工作原理是通过扫描代码库中的工具类使用情况，按需生成对应的 CSS 样式。这一过程我们称之为样式提取。与传统 CSS 框架不同，UnoCSS 采用静态分析的方式，只生成你实际使用到的样式，从而实现了极致的按需加载。

样式提取的三种来源

UnoCSS 支持从多个来源提取工具类使用情况：

1. 构建工具管道提取

这是 Vite 和 Webpack 等现代构建工具集成中最推荐的方式。UnoCSS 会直接分析流经构建管道的文件内容，从中提取工具类使用情况。这种方式具有以下优势：

• 高效准确：只分析实际被使用的文件
• 零额外 I/O 开销：直接利用构建流程中的文件内容
• 智能检测：自动跟踪文件变化

默认情况下，UnoCSS 会扫描以下扩展名的文件： .jsx, .tsx, .vue, .md, .html, .svelte, .astro

如果需要包含 .js 和 .ts 文件，需要在配置中显式声明：

export default defineConfig({
  content: {
    pipeline: {
      include: [
        'src/**/*.{js,ts}',
        // 其他默认包含的文件类型
      ]
    }
  }
})

特殊注释指令

UnoCSS 提供了一些特殊注释来实现更精细的控制：

• @unocss-include：强制扫描当前文件
• @unocss-ignore：跳过当前文件的扫描
• @unocss-skip-start/@unocss-skip-end：跳过代码块的扫描（必须成对使用）

2. 文件系统提取

对于无法通过构建管道访问的情况（如 PostCSS 插件或后端框架集成），可以直接指定文件路径进行扫描：

export default defineConfig({
  content: {
    filesystem: [
      'src/**/*.php',
      'public/*.html'
    ]
  }
})

这种方式会直接从文件系统读取文件内容，并在开发模式下监听文件变化。

3. 内联文本提取

对于从其他来源获取的内容，可以直接以内联文本形式提供：

export default defineConfig({
  content: {
    inline: [
      '<div class="p-4 text-red">内联内容</div>',
      async () => {
        const res = await fetch('https://example.com')
        return res.text()
      }
    ]
  }
})

动态类名的处理方案

由于 UnoCSS 在构建时工作，动态拼接的类名无法被正确识别。以下是几种解决方案：

安全列表 (safelist)

预先声明可能用到的所有类名组合：

safelist: [
  'p-1', 'p-2', 'p-3', 'p-4',
  // 或使用动态生成
  ...Array.from({ length: 4 }, (_, i) => `p-${i+1}`)
]

静态组合模式

将动态值映射到静态定义的类名组合：

const colorClasses = {
  red: 'text-red border-red',
  blue: 'text-blue border-blue'
}

// 模板中使用
<div class="${colorClasses[color]}"></div>

运行时模式

对于真正的动态需求，可以考虑使用 UnoCSS 的运行时包。

黑名单 (blocklist) 配置

与安全列表相反，黑名单用于排除特定类名的生成：

blocklist: [
  'p-1',          // 精确匹配
  /^p-[2-4]$/     // 正则匹配
]

最佳实践建议

1. 优先使用构建管道提取：这是最高效的方式
2. 合理使用安全列表：为已知的动态模式提供保障
3. 避免过度动态化：尽可能使用静态类名组合
4. 注意文件包含范围：确保所有需要扫描的文件类型都已配置

通过合理配置提取策略，可以充分发挥 UnoCSS 按需生成的性能优势，同时满足各种复杂场景的需求。

unocss The instant on-demand atomic CSS engine. 项目地址: https://gitcode.com/gh_mirrors/un/unocss