Tailwind CSS v3自定义字体不生效的配置解决方案

先说一个核心结论：在Tailwind CSS v3中自定义字体不生效，绝大多数情况下并非字体文件损坏或浏览器兼容性问题，而是@font-face声明与tailwind.config.js配置之间未能对齐。字体名称、文件路径、声明顺序、配置方式——只要任意一个环节出现偏差，Tailwind就会静默回退到系统默认字体，并且控制台连任何错误提示都不会输出。

为什么 font-sans 或 font-heading 类完全没有生成对应的CSS规则？

根本原因很简单——你直接使用了theme.fontFamily，而非theme.extend.fontFamily。Tailwind v3的默认字体族组合（sans、serif、mono）只存在于初始 theme 对象中。一旦你用 fontFamily: { sans: [...] } 覆盖整个对象，这些默认键就会被彻底移除。结果就是：font-sans 这个类依然写在HTML里，但编译后的CSS中根本没有对应的样式规则。

• ✅ 正确写法：extend: { fontFamily: { sans: ['"Inter"', 'ui-sans-serif', 'sans-serif'] } }
• ✅ 新增自定义字体族：extend: { fontFamily: { heading: ['"Clash Display"', 'serif'] } } → 对应的实用类名为 font-heading
• ❌ 错误写法：fontFamily: { heading: ['"Clash Display"', 'serif'] } → 会清空所有默认字体族，导致其他字体类失效

@font-face 声明的位置与路径——为什么总是报错？

@font-face 必须写在项目的主CSS入口文件（例如 src/styles.css）中，并且严格来说，应该放在 @tailwind base 之前。否则，Tailwind 的基础重置样式会干扰字体继承，浏览器也无法正确读取字体注册信息。

• ✅ 正确的声明顺序：@font-face → @tailwind base → @tailwind components → @tailwind utilities
• ✅ 路径必须相对于CSS文件本身：假设CSS文件位于 src/styles.css，字体文件位于 public/fonts/roboto.woff2，那么路径应写为 url("../public/fonts/roboto.woff2")