Tailwind 不会自动读取 theme.colors 顶层的自定义色值，必须使用 extend.colors 配置才能生效；颜色名会标准化为中划线格式，数字开头或非法标识符将被忽略，修改配置后需重启构建服务。
tailwind.config.js 里没加 extend.colors，颜色就根本不会进生成的 CSS
Tailwind 不会自动读取你写在 theme.colors 或 colors 对象顶层的自定义色值——它只认 extend.colors 下的配置。很多人直接往 theme.colors 里塞新键，比如：
module.exports = {
theme: {
colors: {
'my-blue': '#1e40af', // ❌ 这样写无效
}
}
}
结果构建后，text-my-blue 或 bg-my-blue 完全不生效，控制台也没报错，纯静默失败。
- 必须用
extend.colors，而不是直接覆盖theme.colors -
extend是合并逻辑，不影响默认色（如blue.500）保留 - 如果真想替换全部颜色体系，才该用
theme.colors，但那是重写，不是“扩展”
颜色名含短横线或大写字母时，class 名会自动转为中划线格式
Tailwind 把对象 key 转成 class 名时，会做标准化：首字母小写、驼峰转中划线、去除非法字符。比如：
extend: {
colors: {
'primary-dark': '#1e3a8a', // → class: text-primary-dark
'MyRed': '#ef4444', // → class: text-my-red
'bg-900': '#111827' // → class: text-bg-900（⚠️易误以为是 bg 颜色，实际是 color 名）
}
}
常见陷阱：
立即学习“前端免费学习笔记（深入）”；
- 写了
'bg-blue-900'当颜色名，结果生成text-bg-blue-900，不是你想设置背景色的那个类 - 用数字开头（如
'900-blue'），会被 Tailwind 忽略（key 必须合法 JS 标识符） - 颜色名和已有的层级冲突，比如
'blue.600'已存在，再在extend里写同名，不会覆盖，而是跳过
开发时改了 tailwind.config.js 但样式没更新？重启构建服务或清除缓存
Tailwind CLI 和大多数打包器（Vite、Next.js、Webpack）都会缓存 config 解析结果。改完 tailwind.config.js 后：
- Vite 项目：必须
Ctrl+C停掉vite，再重新npx vite（热更新不感知 config 变更） - Next.js：改 config 后需重启
next dev，否则bg-my-green永远找不到 - 使用
tailwindcss -i ./src/input.css -o ./dist/output.css --watch的，也要手动中断并重跑 - 极少数情况缓存残留，可删掉
.tailwindcache文件再试
用 @layer utilities 手动加颜色 class 是临时解法，但绕过了 Tailwind 的响应式/变体支持
如果只是急着让某个色快点用上，可以这样硬写：
@layer utilities {
.bg-custom-red { background-color: #ef4444; }
.text-custom-red { color: #ef4444; }
}
但它没法自动获得 hover:bg-custom-red、md:text-custom-red 或 dark:bg-custom-red ——这些都得你一条条补。真正需要多场景使用的颜色，还是得走 extend.colors 流程。
最常被忽略的一点：Tailwind 的颜色系统本质是「键→值」映射 + 「键→class 名」规则，中间没有运行时解析；config 一旦加载完成，就固化为静态 class 表。所以拼写错误、缩进问题、JS 语法错误（比如 config 末尾多逗号），都会导致整个 extend.colors 段被跳过，且无提示。
