必须使用 theme.extend.colors 而非 theme.colors 直接添加，否则 Tailwind v3 会清空默认色盘导致 bg-blue-500 等失效；新增颜色需在 HTML 中真实使用（如 bg-brand-blue-500），且配置后须重启开发服务器。
自定义颜色不生效，基本可以确定是 tailwind.config.js 里没走对配置路径——Tailwind v3 不会读 theme.colors 顶层新增的键，必须用 extend.colors。
为什么直接写 theme.colors.my-blue 没用
Tailwind 的默认色板（blue、gray 等）是内置的，你往 theme.colors 里直接加新键，它压根不扫描也不合并。这不像某些 UI 库会递归合并对象，Tailwind 的 theme 是“覆盖式”逻辑：你写 theme.colors = { blue: ... } 就等于删掉所有默认色，只留你写的；而想保留默认色又加新色，只能走 extend.colors。
常见错误写法：
module.exports = {
theme: {
colors: {
'my-blue': '#1e40af', // ❌ 静默忽略，类名 <code>bg-my-blue</code> 完全不生成
}
}
}
正确写法：
立即学习“前端免费学习笔记（深入）”；
module.exports = {
theme: {
extend: {
colors: {
'my-blue': '#1e40af', // ✅ 生效，<code>bg-my-blue</code> 可用
}
}
}
}
bg-my-blue 写对了但还是没效果
颜色类名生成有规则，不是随便起名就能用：
- 颜色名会被标准化为 kebab-case：
'myBlue'→my-blue，'500blue'→500blue（但数字开头会被忽略） - 非法字符（如空格、点号、下划线）全被丢弃，
'my.blue'→myblue - 必须搭配深度值才生成完整类：
bg-my-blue不生效，要写bg-my-blue-500或text-my-blue-600 - 如果只配了
'my-blue': '#1e40af'，那bg-my-blue-500和bg-my-blue-600都指向同一个色值，不会自动推导深浅变体
修改配置后页面没变化
Tailwind v3 的构建服务（比如 npm run dev）不会自动监听 tailwind.config.js 变更并热重载 CSS，必须手动重启：
- 关掉当前 dev server
- 重新运行启动命令（如
npm run dev或pnpm dev） - 浏览器硬刷新（
Ctrl+Shift+R或Cmd+Shift+R），避免缓存旧 CSS
另外确认 content 字段已包含你写类名的文件路径，否则 PurgeCSS 会把未在代码中显式出现的类全删掉——比如你只在 config 里加了 my-blue，但 HTML/JSX 里还没用过 bg-my-blue-500，那它根本不会进最终 CSS。
检查 HTML 层有没有拼错 class
这是最隐蔽也最高频的问题：把 class="bg-my-blue-500" 写成 clas="bg-my-blue-500"（少一个 s）或 className（React 中没错，但纯 HTML 里无效）。浏览器完全忽略这个属性，所有 Tailwind 类都不解析。
快速验证方法：
- 临时加个原生类：
class="bg-red-500"，看背景是否变红 - 打开 DevTools → Elements 面板，确认元素上真有这个 class 名，且 computed 样式里出现了
background-color - 检查是否有更高优先级样式（比如
!important或内联style）覆盖了 Tailwind 规则
真正容易被忽略的是：Tailwind 颜色类生效依赖整条链路——config 正确、类名格式合法、HTML 属性拼写无误、构建服务重启、content 覆盖到位。漏掉任意一环，都是静默失败，没有报错提示。
