用途:面向 Tailwind CSS 的调试与故障排查,帮助定位样式不生效、JIT 未识别类名、v4 迁移报错、类名被覆盖、插件异常等问题。
主要能力:
- 样式不生效排查:检查内容检测,必要时用 @source 显式指定来源;确认类名为完整字符串而非动态拼接;重启开发服务器或清理缓存(如 rm -rf node_modules/.vite、rm -rf .next)。
- v4 迁移:PostCSS 插件改为 @tailwindcss/postcss;配置从 JS 迁到 CSS,使用 @theme 定义变量;选择器策略下需加 @custom-variant dark (&:where(.dark, .dark *))。
- 类名被覆盖:用 DevTools 查看被划掉的样式,必要时用 !important 或 [&] 提升优先级;自定义 CSS 应放在 @import "tailwindcss" 之后。
- 插件问题:typography 需 @plugin "@tailwindcss/typography",可用 prose-h1:text-4xl 等元素修饰符或 not-prose 隔离;forms 只作用于带 type 属性的输入,可用 strategy: class 改为显式 opt-in。
- 调试工具:VS Code 扩展 code --install-extension bradlc.vscode-tailwindcss;@tailwindcss/debug-screens 显示当前断点;浏览器 DevTools 查看计算样式;npx tailwindcss -o output.css --content './src/**/.{html,js}' 输出 CSS 检查;DEBUG=tailwindcss: npm run build 查看日志。
- 常见错误:缺少 @tailwindcss/postcss 时安装;@theme 未知说明 v3 工具链配 v4 语法,需升级;动态类名改为映射表;开发中样式不更新则重启并清缓存。
- 性能:检查 CSS 体积与构建耗时,排查动态类、多余 safelist 与未用插件。
使用方式:按清单逐项核对导入、PostCSS/Vite 插件、内容路径、缓存与优先级;复现问题时创建最小项目(如 npm create vite@latest repro -- --template react-ts)便于求助。
适用场景:Tailwind 项目开发、v4 升级、插件集成与生产构建排错。
限制:资料未提供具体版本兼容范围、各框架完整配置示例及官方支持渠道细节,部分内容需结合项目实际验证。