手把手教你如何在Tailwind CSS中全局更改默认字体配置

在使用 Tailwind CSS 进行字体自定义时，最常见的困惑是什么？并非字体文件引用出错，也非配置项遗漏，而是耗费大量精力后，发现只有手动添加了 `font-*` 类的元素才生效，而绝大多数文本标签——比如 `

`、`

`、``——依然显示为默认的 font-sans 字体。 想彻底解决这个问题，核心原理其实非常直接：**Tailwind 的默认字体体系由 `theme.fontFamily.sans` 所定义**。该配置与 `font-sans` 工具类直接挂钩，而 `font-sans` 又通过 Tailwind 的基础样式层（`@tailwind base`）被自动应用到全局根元素及几乎所有组件上。所以，要让自定义字体成为全局默认，关键不在于新增一个 `font-iransans` 工具类，而在于**直接替换掉 `sans` 这个字体族本身**。 ### ✅ 推荐的正确配置方法（首选方案） 实现方式非常简洁，核心操作就是修改 `tailwind.config.ts`（或对应的 `.js` 配置文件）。无需定义新的字体名称，直接覆盖 `sans` 配置即可：

import defaultTheme from 'tailwindcss/defaultTheme'

module.exports = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  theme: {
    extend: {
      fontFamily: {
        // ✅ 正确做法：直接覆盖默认 sans 字体族
        sans: ['iransans', ...defaultTheme.fontFamily.sans],
        // 可选：同步更新 serif 和 mono（如需统一字体）
        serif: ['iransans', ...defaultTheme.fontFamily.serif],
        mono: ['iransans', ...defaultTheme.fontFamily.mono],
      }
    }
  },
  plugins: [],
}

请放心，Tailwind 的 `...defaultTheme.fontFamily.sans` 机制会完整保留系统原有的后备字体栈（例如 `-apple-system`、`Segoe UI` 等）。这意味着即使 IranSans 字体因某些原因未能成功加载，页面也不会直接降级为浏览器默认的宋体，而是能够实现优雅的字体回退，确保跨平台体验的一致性。 ### ✅ 同步确认字体资源可用 完成配置后，还需验证字体文件本身是否就绪。你的 `index.css` 中应已通过 `@import` 引入了字体，但需要重点确认以下两点： 1. `@import url(assets/font/iransans/index.css);` 这个路径是否真实有效且可访问。 2. 文件中定义的 `@font-face` 中，`font-family` 的名称**必须**与配置中的 `'iransans'` 完全一致（包括大小写和空格），否则一切配置都将无效。 一个规范的字体资源文件示例如下：

@font-face {
  font-family: 'iransans';
  src: url('./IranSans.woff2') format('woff2');
  font-weight: normal;
  font-style: normal;
}

### ✅ 验证配置效果 执行 `npm run build` 或重启开发服务器后，所有 HTML 标签将自动应用 IranSans 字体，无需添加任何额外的 className：

این متن به صورت پیش‌فرض با فونت ایران‌سنز نمایش داده می‌شود
دکمه‌ی استاندارد
این span هم خودبه‌خود ایران‌سنز دارد

### ❌ 常见误区与纠正 绕开正确的路径，一些典型错误在实际开发中相当普遍： * **错误做法**：仅声明了一个 `iransans: "iransans"` 别名，然后在各处使用 `font-iransans` 类。这确实提供了工具类，但并未触及默认行为，属于治标不治本。 * **错误做法**：直接在 `html` 或 `body` 标签上硬写 `font-family` 样式。请注意，Tailwind 的 base 层在渲染时会覆盖掉这些内联样式。除非使用 `!important`，但这完全背离了 Tailwind 的设计理念，属于杀鸡取卵。 * **错误做法**：遗漏了 `...defaultTheme.fontFamily.sans` 这一关键部分。一旦失去这个后备计划，字体加载失败时的体验将大打折扣，尤其在不同操作系统和设备上，这种影响尤为明显。 ###