font-sans失效主因是直接覆盖theme.fontFamily而非用extend.fontFamily，导致默认字体族丢失；须确保@font-face与配置中字体名完全一致、置于@tailwind base前、中文字体前置且保留ui-sans-serif等内置别名。
font-sans 类没效果，或者自定义字体名如 font-robotoMono 完全不生成 CSS 规则——这基本不是字体文件坏了，而是配置链断在某个环节。Tailwind 不报错，只静默 fallback，得靠排查顺序和细节来定位。
为什么 font-sans 突然不生效了
最常见原因是直接写了 theme.fontFamily 覆盖整个对象，而不是用 extend.fontFamily。Tailwind v3 的默认字体族（sans、serif、mono）是硬编码在初始 theme 里的，一覆盖就全丢。
- ❌ 错误写法：
fontFamily: { sans: ['Inter', 'sans-serif'] }→font-serif、font-mono全失效 - ✅ 正确写法：
extend: { fontFamily: { sans: ['"Inter"', 'ui-sans-serif', 'sans-serif'] } } - 数组第一项必须是
@font-face中声明的精确字体名（含引号、大小写、空格），比如"Inter"就不能写成Inter或'Inter' -
ui-sans-serif这类内置别名不能删，它包含跨平台中文字体栈，中文用户靠它兜底
@font-face 声明位置和路径怎么才算对
@font-face 必须放在项目主 CSS 入口（如 src/styles.css）里，且严格位于 @tailwind base 之前。顺序错了，浏览器根本注册不上字体。
- ✅ 正确顺序：
@font-face→@tailwind base→@tailwind components→@tailwind utilities - 路径要相对于当前 CSS 文件计算：CSS 在
src/styles.css，字体在public/fonts/roboto.woff2，就得写url("../public/fonts/roboto.woff2") - 打开 DevTools Network 面板，过滤
woff2，看有没有 404；404 地址就是你该修正的路径 - 务必加
font-display: swap，否则首屏文字可能空白几秒（FOIT）
自定义字体类名为啥始终不生成
Tailwind 生成的类名完全由 fontFamily 配置里的键名决定：键名是 robotoMono，类名就是 font-robotoMono，大小写、连字符、下划线都必须一致。
立即学习“前端免费学习笔记（深入）”；
-
@font-face里写的是font-family: "robotoMono"，配置里就必须是robotoMono: ['"robotoMono"', 'monospace'] - 如果字体名含空格或连字符（如
"Source Sans Pro"），@font-face和配置里都得用双引号包裹，且配置中要用单引号套住：'"Source Sans Pro"' - 类名拼写错误（如
font-roboto写成font-robotomono）不会报错，但对应 CSS 规则压根不会生成 - 检查
content字段是否扫到了当前文件；没扫到，font-robotoMono就不会被提取进最终 CSS
中文字体优先级怎么调才真有效
单纯配 font-sans 不够。中文用户看到方块字或 SimSun，说明中文字体没排在 font stack 前面，或者没全局接管。
- 在
extend.fontFamily.sans数组里，把中文字体名（如"PingFang SC"、"Microsoft YaHei"）放在ui-sans-serif前面 - 用
@layer base在主 CSS 里给html或body设font-family: theme('fontFamily.sans')，确保全局生效 - 避免在组件级样式（如 styled-components、CSS-in-JS）里重写
font-family，容易被 Tailwind 的 base 层重置覆盖 - 验证方式：DevTools Elements 面板选中任意文本节点，看 Computed 栏里
font-family实际值，不是看 Styles 里有没有规则
真正卡住的地方往往不是字体文件本身，而是 @font-face 名字和 tailwind.config.js 键名之间那一个引号、一个空格、一个大小写的差异——浏览器认的是字符串字面量，不是“差不多”。
