font-sans 失效是因为直接覆盖 theme.fontFamily 而非使用 extend.fontFamily，导致 Tailwind 原生字体映射丢失；正确做法是通过 extend.fontFamily 安全扩展，并确保 @font-face 字体名与配置严格一致、中文字体前置、@layer base 全局接管 html 节点。
font-sans 类不生效，大概率是因为你直接覆盖了 theme.fontFamily，而不是用 extend.fontFamily。Tailwind v3 的默认字体族（sans、serif、mono）是硬编码在初始 theme 里的，一覆盖就全丢，类名还在，但生成的 CSS 里根本没对应规则。
为什么 font-sans 突然失效？
常见错误是这样写配置：
theme: {
fontFamily: {
sans: ['Inter', 'sans-serif']
}
}
这会清空 Tailwind 原生的 sans/serif/mono 映射，导致 font-sans、font-serif 全部失效。浏览器直接 fallback 到 Times New Roman 或 SimSun，DevTools 里查不到任何 font-family 声明。
必须改成：
theme: {
extend: {
fontFamily: {
sans: ['Inter', 'ui-sans-serif', 'sans-serif']
}
}
}
-
extend.fontFamily是唯一安全的扩展方式，它只新增或重写某一项，不破坏默认结构 - 数组第一项必须是你引入的字体名（如
Inter），且大小写、空格、引号要和@font-face或@import中声明的完全一致 - 务必保留
ui-sans-serif这类 Tailwind 内置别名——它们包含跨平台中文字体栈，不是摆设
@font-face 和 tailwind.config.js 怎么对上？
Tailwind 不加载字体文件，它只输出 font-family 声明。如果 @font-face 没注册，或者名字对不上，font-sans 就永远卡在 fallback 上。
立即学习“前端免费学习笔记（深入）”；
-
@font-face必须放在@tailwind base之前，且在项目主 CSS 入口文件（如src/index.css）里，不能塞进组件级样式 - 假设你在
@font-face里写了font-family: "PingFang SC"，那tailwind.config.js里就得写'"PingFang SC"'（单引号包裹双引号字符串） - 本地字体路径要相对于当前 CSS 文件计算，Windows 下注意用正斜杠或双反斜杠，并加引号：
'"./fonts/Inter.woff2"' - 务必加
font-display: swap，否则首屏文字可能空白几秒（FOIT）
怎么支持中文字体优先？
单纯配 font-sans 不够，中文用户看到的可能是 SimSun 或方块字。关键是要让中文字体在 font stack 里靠前，且全局生效。
- 在
tailwind.config.js的extend.fontFamily.sans数组中，把中文字体放最前面：['"PingFang SC"', '"Microsoft YaHei"', '"Noto Sans CJK SC"', 'ui-sans-serif', 'sans-serif'] - 仅靠工具类不够，必须用
@layer base主动接管根节点：@layer base { html { font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; } } - 不要写
body { font-family: ... }—— iOS Safari 对body字体继承有 bug，html才是真正根节点
自定义类名（如 font-heading）怎么加？
键名决定 class 名后缀，比如 heading → font-heading，但必须走 extend.fontFamily，且字体名要严格匹配。
- 配置示例：
extend: { fontFamily: { heading: ['"Clash Display"', 'ui-sans-serif', 'sans-serif'] } } - 键名只能含 ASCII 字母、数字、短横线；
my-font→font-my-font，但My Font会被忽略 - 所有含空格或特殊字符的字体名（如
Clash Display）必须用单引号包裹：'"Clash Display"' - 修改后必须重启开发服务器，Tailwind 不热更新字体配置
@font-face 和配置中字体名的字符串字面量必须一字不差（引号、大小写、空格）；二是 @layer base 对 html 的全局接管比单靠工具类更可靠；三是中文字体必须前置，且不能省略 ui-sans-serif 这个 Tailwind 提供的跨平台兜底链。 
