自定义规则须写入 uno.config.ts 的 rules 数组，theme 中带--前缀的变量需显式声明在 colors/spacing 等顶层字段，预设顺序决定覆盖逻辑，提取器需适配 uni-app/.ux 等非标准文件。
自定义规则必须写在 rules 数组里，不能靠 CSS 文件注入
UnoCSS 不会扫描 main.css 或 <style></style> 标签里的声明去生成原子类。所有自定义规则必须显式写进 uno.config.ts 的 rules 字段中，否则哪怕你写了 .text-foo { color: red }，text-foo 也不会被识别为有效类名。
常见错误现象：在组件里写 class="text-foo"，浏览器里没效果，控制台也无报错——本质是 UnoCSS 根本没把它当规则处理。
-
rules是一个数组，每个元素是[matcher, handler, options?]三元组 -
matcher可以是正则（如/^text-(.+)$/）或字符串前缀（如'text-'） -
handler返回一个对象，键为 CSS 属性，值为最终生成的 CSS 值（支持函数动态计算） - 别漏掉
options?.layer，否则可能被默认 layer 覆盖导致不生效
theme 里注册变量才能用 --xxx 自定义属性语法
像 bg-[--bg-card]、text-[--text-primary] 这类写法，不是“读取 :root 里的变量”，而是 UnoCSS 在编译期查 theme 配置。如果 --bg-card 没在 theme.colors 或 theme.spacing 等子项里显式声明，它就不会生成对应样式规则。
错误配置示例：theme: { colors: { primary: '#3b82f6' } } —— 这样 text-[--primary] 依然无效，因为 --primary 并未注册；必须写成：theme: { colors: { '--primary': '#3b82f6' } }。
- 所有带
--前缀的变量名，都得作为 key 显式出现在theme的某个子对象里 - 不能嵌套在
theme.extend或其他非顶层字段下，必须直属于theme.colors/theme.spacing等预设接受的字段 - 值可以是字符串、函数、甚至
undefined（用于占位，配合运行时 JS 设置）
预设（preset）是可组合的，但顺序影响覆盖逻辑
UnoCSS 允许同时使用多个预设，比如 presetWind() + presetIcons() + 自定义 presetMyDesign()。但它们的执行顺序就是 presets 数组的顺序，后写的预设会覆盖前面同名规则。
典型问题：你写了 presetWind() 再写自己的 presetMyDesign()，但发现 bg-red-500 被你预设里同名规则改掉了——不是 bug，是设计如此。
- 想保留 Wind 预设行为，就把自定义预设放在它前面
- 想覆盖 Wind 的某类规则（比如改掉所有
px单位为rpx），就在自定义预设里重写对应rules，并放它后面 - 预设本身可导出为函数，方便复用和参数化（如
presetMyDesign({ prefix: 'u-' })）
自定义提取器（extractors）要适配文件类型，尤其 uni-app / 小程序
UnoCSS 默认只从 .vue、.tsx、.html 等标准文件里提取 class 名。但在 uni-app 或 UniappX 中，.vue 里可能有 <template lang="wxml"></template>，或存在 .ux 文件，这些内容不会被默认提取器识别。
结果就是：你在 .ux 里写了 class="flex gap-4"，但编译后没生成对应 CSS 规则。
- 必须手动加
extractors，用正则或 AST 工具提取目标文件中的 class 字符串 - uni-app 推荐用
@uni-helper/unocss-preset-uni，它内置了适配.vue和小程序模板的 extractor - 自己写 extractor 时，注意返回的是字符串数组（如
['flex', 'gap-4']），不是 AST 节点
rules、变量没进 theme、预设顺序搞反、或者提取器根本没扫到你的文件——这四点，检查一遍基本就定位到问题了。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
