直接修改 theme.colors 会清空默认色盘导致样式崩坏，必须用 theme.extend.colors 安全扩展；自定义含连字符色名需加引号；十六进制值须带#且色阶需手动完整声明字符串键；JIT 编译仅生成模板中实际使用的 class，修改配置后需重启服务。
直接改 theme.colors 会清空所有默认色
你写 theme.colors = { brand: '#3b82f6' }，bg-blue-500、text-gray-700 全部失效——Tailwind 不再加载内置色盘。它不是“覆盖 blue”，而是“扔掉整个 colors 对象”。默认色被大量工具类隐式依赖，比如 hover:bg-blue-600 或 ring-blue-500，一旦消失，样式大面积崩坏。
真正安全的做法只有一条：始终走 theme.extend.colors。它和默认色盘合并后参与构建，bg-blue-500 照常工作，同时新增的 bg-brand-500 也能用。
- ✅ 正确：
extend: { colors: { brand: '#3b82f6' } } - ❌ 错误：
colors: { brand: '#3b82f6' }（顶层直接写colors） - ⚠️ 高危：
extend: { colors: { blue: '#1a56db' } }—— 这不会覆盖默认 blue，只会新增一个同名 key，但 JIT 编译时优先读内置 blue，你的配置实际被忽略
自定义色名含连字符必须加引号
Tailwind 解析配置时把 dark-blue 当作减法运算（dark - blue），不加引号会导致语法错误或颜色丢失。哪怕嵌套结构里也一样，比如 brand: { 'light-blue': '#bfdbfe' } 中的 light-blue 必须引起来。
- ✅ 正确：
'dark-blue': '#1e3a8a'或['dark-blue']: '#1e3a8a' - ❌ 错误：
dark-blue: '#1e3a8a'（解析失败，控制台报错或静默丢弃） - ⚠️ 注意：
brandBlue、primary500这类驼峰/数字结尾的键名不用引号，但可读性差，不推荐
十六进制值必须带 #，且变体要手动声明完整色阶
写 brand: '#3b82f6' 只生成 bg-brand、text-brand 这类基础类；bg-brand-500 会报错——因为没声明色阶。Tailwind 不会为单值自动推导明暗梯度，这和内置 blue 的行为完全不同。
立即学习“前端免费学习笔记（深入）”；
想拥有完整色阶体验，必须显式定义对象，键为字符串数字（'50'、'100'…'900'），值为合法十六进制（支持 3/4/6/8 位）：
brand: {
'50': '#dbeafe',
'100': '#bfdbfe',
'500': '#3b82f6',
'700': '#1d4ed8',
'900': '#1e3a8a'
}- ✅ 正确：键是字符串
'50'，不是数字50，也不是'light' - ❌ 错误：
50: '#dbeafe'（JIT 编译跳过该档）、light: '#dbeafe'（bg-brand-light不生效） - ⚠️ 注意：灰阶重定义更危险——写
gray: { '50': '#fafafa', '100': '#f4f4f5' }会让gray-200到gray-900全部消失，不是 Tailwind 懒，是它按你写的精确输出
修改后 class 不生效？先查 JIT 是否扫描到使用位置
Tailwind v3+ 默认启用 JIT 编译，只生成你在模板中实际写过的 class。你在 tailwind.config.js 加了 brand，但 HTML 里没出现过 bg-brand-500，那这个 CSS 规则根本不会生成——浏览器开发者工具里搜不到，不是配置错，是压根没触发编译。
- ✅ 快速验证：在任意模板里临时加一行
<div class="bg-brand-500"></div>，保存后看是否生效 - ✅ 检查
content配置路径是否覆盖你的文件，比如src/**/*.{js,jsx,ts,tsx,html} - ⚠️ 修改配置后必须重启开发服务器——Tailwind 启动时静态读取
tailwind.config.js，运行中改文件不会热更新
最易被忽略的是灰阶重定义和 JIT 扫描范围——前者导致整组 gray- 类消失，后者让新颜色“看起来配了却用不了”，这两个点卡住的人最多。
