T3 App 项目中 Pages Router 与 Tailwind 默认字体问题解析

问题背景

在 T3 App 项目中，当开发者选择使用 Pages Router 架构而非 App Router 时，会遇到一个关于字体加载的兼容性问题。这个问题源于 Tailwind CSS 配置与 Next.js 字体加载机制之间的不匹配。

技术细节分析

Tailwind CSS 的默认配置文件中将 var(--font-sans) 设置为首选字体。然而，这个 CSS 变量 --font-sans 原本是为 App Router 模板设计的，由 next/font 提供的 Inter 字体自动注入。

在 Pages Router 架构下，由于缺少相应的字体注入机制，导致浏览器无法识别 --font-sans 变量。更严重的是，当这个无效变量作为字体堆栈中的第一个选项时，某些浏览器（如 Chrome 和 Firefox）会直接跳过整个字体声明，而不是回退到后续的备用字体。

问题表现

开发者会观察到页面字体没有按照预期渲染，而是直接使用了浏览器的默认字体。通过开发者工具检查，可以看到字体声明被标记为无效。

解决方案

对于使用 Pages Router 的项目，需要在 _app.tsx 文件中手动添加 Inter 字体的加载逻辑：

1. 首先导入 next/font/google 中的 Inter 字体
2. 配置字体选项，包括子集和 CSS 变量名
3. 将字体类应用到应用的主容器上

具体实现代码如下：

import { Inter } from "next/font/google";

const inter = Inter({
  subsets: ["latin"],
  variable: "--font-sans",
});

const MyApp: AppType = ({ Component, pageProps }) => {
  return (
    <main className={`font-sans ${inter.variable}`}>
      <Component {...pageProps} />
    </main>
  );
};

最佳实践建议

1. 统一字体加载方式：无论使用哪种路由架构，都应确保字体加载机制的一致性
2. CSS 变量验证：在使用 CSS 变量前，确保它们已被正确定义
3. 字体回退策略：在字体堆栈中设置合理的备用字体，避免因主字体加载失败导致样式问题
4. 浏览器兼容性测试：在不同浏览器中测试字体渲染效果，确保一致的用户体验

总结

这个问题的本质是框架配置与路由架构之间的不匹配。通过理解 Next.js 的字体加载机制和 Tailwind 的配置方式，开发者可以灵活地调整实现方案，确保在各种架构下都能获得一致的字体渲染效果。这也提醒我们在使用现代前端工具链时，需要注意不同模块间的协同工作方式。