升级后样式失效主因是框架移除旧类名或变更默认行为，需查Changelog的Breaking Changes、检查DevTools中类名加载状态、验证content配置路径覆盖新目录、更新safelist匹配动态类名。
查 Changelog 里的 Breaking Changes
升级后样式失效，八成是框架主动删了旧类名或改了默认行为。别急着改代码，先去官网或 GitHub 翻 CHANGELOG.md，用浏览器搜索 Breaking Changes 或 Deprecated。
比如 Tailwind v3 升 v4 可能移除了 bg-gradient-to-r，改成 bg-gradient-to-r；或者 text-sm 的行高默认值从 1.25 改成 1.125，导致文字“变挤”——这种改动不报错，但视觉直接偏移。
重点看三类内容：
• 被移除的工具类（尤其是带前缀如 sm:、hover: 的）
• 默认值变更（spacing、fontSize、lineHeight）
• 组件类名重构（如 btn 相关类被拆进插件，主包里没了）
用 DevTools 确认类名是否被加载
打开浏览器开发者工具，选中异常元素，在 Styles 面板里观察：
• 如果某个类名显示灰色、带删除线，或压根没出现在规则列表里，说明它没进最终 CSS 文件
• 如果类名存在但样式没生效，点开旁边的 :hov、:act 看伪类是否触发正常
• 右键该类名 → “Show all related rules”，确认有没有被更高优先级的 CSS 覆盖（比如自定义 CSS 里写了 .text-red-500 { color: black !important; }）
立即学习“前端免费学习笔记（深入）”；
快速验证法：
• 在 Elements 面板手动删掉疑似失效的类（如 flex-col），看布局是否恢复预期
• 在 Console 里运行 getComputedStyle(document.querySelector('.your-class')).color，看返回值是不是空字符串或意外值
检查 content 配置是否覆盖新路径
Tailwind v3+ 不再扫描整个项目，只按 content 数组里写的 glob 路径读源码字符串。升级后如果目录结构变了（比如新增 app/(auth) 路由组、或把组件抽到 shared/），旧 content 就会漏扫。
常见遗漏点：
• Next.js App Router 新增的 app/**/*.{ts,tsx} 没加进去
• 使用了 MDX、Astro、Qwik 等非标准模板，但 content 还只写 **/*.jsx
• 第三方 UI 库（如 @headlessui/react）内部用了 Tailwind 类，但 node_modules 路径没显式列入 content
CLI 构建时必须显式传 --content 参数：
• 错误写法：npx tailwindcss -i input.css -o output.css（v3+ 不自动读 config）
• 正确写法：npx tailwindcss -i input.css -o output.css --content "./src/**/*.{js,jsx,ts,tsx}" --content "./app/**/*.{js,ts,jsx,tsx}"
safelist 是否覆盖动态类名的变体
升级后某些正则匹配逻辑可能变严格。比如旧版 /^text-[a-z]+-[0-9]+$/ 在 v4 里可能不匹配 text-emerald-500（因为 emerald 是新增颜色名，不在原始字母范围内）。
动态类名要重新校验：
• 响应式前缀（md:text-red-500）必须显式写进 safelist，不能只写 text-red-500
• 颜色/尺寸等变量扩展，建议用函数式写法：{ pattern: /text-(red|blue|emerald|amber)-[0-9]+/ }
• 避免 .* 结尾，比如 /text-.*/ 会意外保留 text-clip 这类原生属性
临时验证手段：
• 在 tailwind.config.js 里设 debug: true，构建时看控制台输出哪些 class 被 discarded
• 注释掉 content 字段跑一次 build，如果样式全回来，就是 Purge 扫描范围问题
最常被忽略的是：升级不单是换版本号，而是整套扫描逻辑、默认配置、甚至 PostCSS 插件链的协同变更。哪怕 tailwind.config.js 没动，只要 content 路径没随项目结构调整，或 safelist 没同步新增颜色/断点，就一定会丢样式。
