如何为Tailwind CSS项目配置CSS字体映射？-css教程-PHP中文网

font-sans 失效是因为直接覆盖 theme.fontfamily 而非使用 extend.fontfamily，导致 tailwind 原生字体映射丢失；正确做法是通过 extend.fontfamily 安全扩展，并确保 @font-face 字体名与配置严格一致、中文字体前置、@layer base 全局接管 html 节点。

如何为tailwind css项目配置css字体映射？

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 声明。

必须改成：

Wechat HTML Publisher

直接上传HTML富文本到微信公众号草稿箱。支持完整的HTML格式,无需Markdown转换。

下载

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 提供的跨平台兜底链。