Windi CSS的content配置必须显式列出文件后缀，如"./src/*/.{vue,html,ts}"，漏写.vue等后缀则对应模板类名无法扫描；插件未正确加载、路径错误或配置文件导出异常均会导致扫描静默失效。
Windi CSS 的 content 配置必须显式匹配文件后缀
Windi CSS 和 Tailwind 一样，只在构建时静态扫描 content 列表里明确列出的文件路径。它不会自动推断你用了什么扩展名，漏写一个就扫不到整类文件。
-
content必须包含实际组件所在路径 + 显式后缀，例如：["./src/**/*.{js,jsx,ts,tsx,svelte,vue}"] - 用 Svelte？
.svelte不会被*.{js,ts}匹配，必须加进去 - 用 Vue 单文件组件？
.vue同理，不加就等于没扫描任何模板里的类名 - Vite 项目中若把组件放在
public/（比如静态 landing 页面），得单独加："./public/**/*.html" - 路径写成
"src/**/*"（缺./）或"../src/**/*"，Windi 会直接跳过，不报错也不警告
Windi CSS 插件未正确加载会导致扫描完全失效
即使 content 写对了，如果 Windi CSS 插件没被构建工具真正调用，所有扫描都只是空转——你看到的类名根本没进 CSS 文件。
- Vite 用户：确认
vite.config.js中已import WindiCSS from 'vite-plugin-windicss'并加入plugins: [WindiCSS()] - Webpack 用户：检查
webpack.config.js是否在module.rules里配置了windicss-webpack-plugin - 插件版本冲突很常见：如果你同时装了
tailwindcss和windicss相关包，删掉tailwindcss及其 PostCSS 插件，避免接管 CSS 编译流程 - 运行
npx windi --help能执行，不代表它已接入项目；关键看构建输出日志里有没有[windi] scanning...这类提示
动态类名（如 class="text-${size}-sm"）Windi 默认不处理
Windi 的扫描机制和 Tailwind JIT 一致：只认源码中完整、静态、无插值的类名字符串。带 ${} 的模板字面量，它直接跳过，不会展开也不会猜测取值。
- 现象：DOM 上
class属性显示正常（如text-lg-sm），但开发者工具查不到对应 CSS 规则 - Windi 不支持运行时解析，所以
class="text-${size}-sm"和:class="'text-' + size + '-sm'"全部失效 - 两种可行解法：
- 预定义映射：
const sizeClasses = { sm: 'text-sm', lg: 'text-lg' }，然后用className={sizeClasses[size]} - 用
safelist（Windi 支持）：在windi.config.ts里写safelist: ['text-sm', 'text-lg', /^text-[a-z]+$/]
- 预定义映射：
- 注意：
safelist正则必须用斜杠包裹（/^text-[a-z]+$/），写成字符串（'/^text-[a-z]+$/'）就无效
Windi 配置文件未被识别或导出错误
Windi 读取配置靠的是标准 Node 模块加载机制，任何语法、路径或导出问题都会导致静默降级为默认配置——你改了 theme.extend 或 content，它其实根本没读到。
立即学习“前端免费学习笔记（深入）”；
- 配置文件必须叫
windi.config.ts或windi.config.js，且放在项目根目录（即package.json所在层） - 导出必须是
module.exports = { ... }；用export default仅当package.json有"type": "module"且 Node ≥14.18 - 配置里不能有同步阻塞操作，比如
fs.readFileSync('missing.conf')，否则插件加载失败但不报错 - 如果配置文件在子目录（如
config/windi.config.ts），需在vite.config.js中显式传入：WindiCSS({ configFiles: ['./config/windi.config.ts'] })
