根本原因是直接覆盖 theme 顶层字段会清空 Tailwind 所有内置预设；正确做法是使用 theme.extend 进行叠加扩展，且需配合 @layer utilities 显式生成工具类。
根本原因不是配置写错了，而是你直接改了 theme 顶层字段——这会清空 Tailwind 所有内置颜色、间距、字体等预设，bg-gray-100、text-blue-500 全部失效。
为什么直接写 theme: { colors: { ... } } 会导致样式消失
Tailwind 的默认主题是硬编码在源码里的，它只在你使用 theme.extend 时做“叠加”，而不是“合并”。一旦你把 colors 写在 theme 根对象下，整个内置 colors 对象就被替换成你的对象，没有 fallback，也没有继承。
- 错误写法：
module.exports = { theme: { colors: { primary: '#3b82f6' } } }→ 所有gray、blue、indigo等全没了 - 正确写法：
module.exports = { theme: { extend: { colors: { primary: '#3b82f6' } } } }→ 保留全部默认色，仅新增primary -
extend支持的字段包括：colors、spacing、fontSize、screens、borderRadius等，但不包括fontFamily这类需完整定义的项（它本身就没有默认 fallback）
扩展后 theme('colors.primary') 仍报错或返回 undefined
这是因为 theme() 函数只能读取静态配置值，且必须在 @layer 或 CSS 规则内部使用；它不支持动态键（如 theme('colors.' + name)），也不支持函数式值（比如用 plugin() 注入的运行时计算值）。
- 确保你在
tailwind.config.js的theme.extend.colors中明确定义了primary，例如：primary: { DEFAULT: '#3b82f6', 50: '#eff6ff', ... } - 在 CSS 文件中使用时，必须写成
theme('colors.primary.DEFAULT')，不能省略DEFAULT键（除非你只定义了一个字符串值） - 若在
@layer base外、或未声明@layer的普通 CSS 规则里调用theme()，PostCSS 会静默忽略或报错
@apply 调用自定义颜色类却提示 “unknown utility”
这不是配置问题，而是 @apply 查找机制的限制：它只认 @layer utilities 中已生成的工具类，不认 theme.extend 里定义的原始配置。
立即学习“前端免费学习笔记（深入）”；
- 你加了
theme.extend.colors.primary，只是让theme('colors.primary.DEFAULT')可用，并不会自动创建bg-primary或text-primary工具类 - 要生成对应工具类，得手动写：
@layer utilities { .bg-primary { @apply bg-[#3b82f6]; } }或更稳妥地用theme()：.bg-primary { background-color: theme('colors.primary.DEFAULT'); } - 别在
@layer base里@apply text-primary——因为text-primary不是 Tailwind 原生工具类，也未在utilities层声明，必然失败
最容易被忽略的一点：所有 theme.extend 定义的颜色、尺寸等，都只是“配置数据”，它们不会自动映射成可用的工具类。你需要显式用 @layer utilities + theme() 或硬编码来落地，否则再完整的配置也只是一堆 JS 对象，进不了最终 CSS。
