不能覆盖内置色名，v3会跳过theme.extend.colors中blue、gray等同名扩展而不报错；必须用brand、accent等新命名空间，且灰阶应改用neutral。
tailwind.config.js 中 colors 扩展是否覆盖内置色名
不能覆盖。v3 对 theme.extend.colors 的校验更严格：若你试图复写 blue、gray 等内置色名，整个扩展会被跳过，不报错也不生效。这是最常被忽略的兼容性断裂点。
常见错误现象：bg-blue-500 样式突然失效，但检查配置发现 theme.extend.colors.blue 看似已定义；实际是 v3 拒绝了该覆盖，仍使用默认 blue 调色板，而你的自定义值未注入。
- 正确做法：用新命名空间，如
brand、accent、ui，避免与内置色名冲突 - 灰阶必须改用
neutral：v3 已将gray语义收窄为“文字/边框中性色”，而neutral成为通用中性调色板（尤其在 Nuxt UI v3 等上层库中强制要求） - 检查是否误删了
colors下的transparent或current—— 它们仍是合法基础值，但不再归入色阶序列
透明度语法从 bg-opacity-* 迁移到 / 后缀
bg-opacity-30 bg-red-500 必须改为 bg-red-500/30，否则透明度完全不生效。这不是可选升级，而是 v3 的 CSS 生成逻辑变更：/ 语法由 JIT 引擎直接解析为 background-color: color-mix(in srgb, var(--color-red-500), transparent 70%)（或降级为 rgba）。
容易踩的坑：
立即学习“前端免费学习笔记（深入）”；
- JSX 中用
clsx拼接类名时，bg-red-500/${opacity}不会被 JIT 识别——任意值必须是静态字符串，如bg-red-500/30 - PostCSS 插件（如
@tailwindcss/typography）若版本过低，可能未适配 / 语法，导致富文本内嵌样式失效 -
text-red-500/30和border-red-500/30均有效，但placeholder-red-500/30需确保浏览器支持::placeholder伪元素的透明度继承
色阶数量与 HSL 支持带来的渲染差异
v3 默认提供 25 级色阶（50–950），比 v2 的 10 级（50–900）更细密；更重要的是底层改用 HSL 模型计算中间色阶，视觉过渡更均匀，尤其在深色模式下 slate、zinc 等新色系表现更稳定。
但这也意味着：
- 旧项目若依赖 v2 的
gray-800具体 RGB 值（比如用于 canvas 绘图或 SVG fill），迁移到 v3 的slate-800后颜色会偏移——不是 bug，是模型重算结果 -
rose、violet、fuchsia等新色系无 v2 对应项，直接使用不会触发警告，但需确认设计系统是否已纳入这些色名 - 自定义色阶（如
brand: { 100: '#f0f9ff', 900: '#0c4a6e' }）仍走 HSL 插值，若起止色不在同一色相环区域，中间色可能出现意外偏色
JIT 扫描 content 路径对颜色类名生效的影响
v3 的 JIT 引擎只扫描 content 字段列出的路径。如果你在 src/utils/colors.ts 里定义了 const primary = 'blue-500'，又在 JSX 中写 className={primary}，JIT 不会提取这个类名——它只认静态字符串字面量。
这意味着：
- 所有动态颜色类名（
text-${color}-500、bg-[${hex}]）必须显式加入safelist，否则生产构建后缺失 -
@apply中引用的颜色工具类，若未在任何 HTML/JSX 文件中以字面量形式出现过，JIT 不会生成其对应规则 - 使用
tailwind-merge时，确保版本 ≥v2.5，否则twMerge('bg-blue-500/30', 'hover:bg-blue-500/50')会因无法解析 / 语法而退化为字符串拼接
真正麻烦的不是改写法，而是那些没报错却悄悄失效的类名——它们藏在模板字符串、工具函数、甚至第三方组件的 className prop 里，靠搜索替换根本清不完。
