用途:诊断 Tailwind 构建成功但样式不生效的问题,覆盖编译 CSS 为空、部分缺失、过期,以及类名在标记中存在却未渲染的情况。核心前提是 Tailwind 只输出能在源文件中检测到的完整类名字符串。
主要能力:提供 60 秒快速诊断流程,先用 grep "p-4" dist/output.css 检查编译产物,再按决策树区分扫描器漏检与缓存过期。扫描器侧覆盖 v3 content 数组与 v4 @source 指令的配置排查;缓存侧给出 Vite、Next.js、Webpack、Astro 与 CLI watch 的清理命令,如 rm -rf node_modules/.vite、rm -rf .next、rm -rf .astro dist node_modules/.vite。
必要用法:坚持静态类名纪律,避免 bg-${color}-500 这类插值,改用完整字符串映射表;无法避免动态类时,v3 用 safelist,v4 用 @source inline 配合花括号展开。v3 入口用 @tailwind base; @tailwind components; @tailwind utilities;,v4 用 @import "tailwindcss";,混用会导致空 CSS 或部分输出。
适用场景:monorepo 兄弟包、node_modules 包、CMS 渲染 HTML、MDX 文件中的类名缺失,以及新增目录未被监听。
限制:不覆盖类名已在 CSS 但被优先级覆盖的情况(见 tailwind-errors-runtime)、v3 到 v4 迁移破坏、插件类缺失与 tailwind-merge 问题。已知回归包括 Turbopack 任意值类漏检与 Astro v4.0.8 样式丢失,资料给出对应规避方式。