必须用 theme.extend.fontFamily 添加自定义字体，否则会覆盖默认 sans/serif/mono 导致 font-sans 失效；键名决定 class 名，字体名需单引号包裹且与 @font-face 完全一致，fallback 必须含通用族名，修改后须重启开发服务器。
必须用 theme.extend.fontFamily 添加，不能直接写 theme.fontFamily —— 否则会清空 Tailwind 原生的 sans、serif、mono 等默认字体别名，导致 font-sans 失效。
为什么 font-[name] 类不生成？检查配置位置和结构
Tailwind 只读取 theme.extend.fontFamily 下的键值对来生成工具类。常见错误是把自定义字体写在 theme.fontFamily 根对象里，例如：
theme: {
fontFamily: { // ❌ 错误：这会覆盖整个默认 fontFamily 对象
sans: ['Inter', 'sans-serif'],
heading: ['Clash Display', 'sans-serif']
}
}
正确做法是只扩展现有结构：
theme: {
extend: {
fontFamily: { // ✅ 正确：仅新增或重写某一项
heading: ['"Clash Display"', 'sans-serif'],
mono: ['"Fira Code"', 'ui-monospace', 'monospace']
}
}
}
- 键名（如
heading）决定最终 class 名：font-heading - 键名只能含 ASCII 字母、数字、短横线；
my-font→font-my-font，但My Font会被忽略 - 所有含空格或特殊字符的字体名（如
Clash Display）必须用单引号包裹，否则 PostCSS 解析失败
字体名大小写、引号、空格必须和 @font-face 完全一致
Tailwind 不加载字体文件，它只生成 CSS 规则。如果 @font-face 声明的是 font-family: "robotoMono"，那么 tailwind.config.js 中也必须写 robotoMono: ["robotoMono", ...] —— 大小写、下划线、引号一个都不能差。
立即学习“前端免费学习笔记（深入）”；
-
@font-face必须放在@tailwind base之前，否则被重置 - 推荐加
font-display: swap，避免 FOIT（空白文本阻塞） - 本地字体路径需相对于 CSS 文件位置计算，
../fonts/xxx.woff2比./fonts/xxx.woff2更易出错
fallback 字体栈末尾必须带通用族名
浏览器需要明确知道这是什么类型字体，否则可能完全不渲染或回退异常。例如：
- 无衬线字体栈结尾必须是
'sans-serif'（不是'system-ui'） - 衬线字体栈结尾必须是
'serif' - 等宽字体栈结尾必须是
'monospace'
错误示例：['Inter', 'system-ui'] → 缺少通用族名，某些浏览器（如旧版 Safari）可能降级为 Times New Roman；正确写法：['Inter', 'system-ui', 'sans-serif']。
修改后必须重启开发服务器
Tailwind 不监听 tailwind.config.js 的变更并热重载。改完配置后，要手动终止并重新运行 npm run dev 或 pnpm dev，否则新 class 根本不会出现在输出 CSS 中。
最容易被忽略的是：你写的 font-heading 看似没生效，其实只是构建缓存没刷新，或者开发服务没重启 —— 这比路径或引号错误更隐蔽。
