Tamagui项目中Next.js字体加载问题的解决方案

问题背景

在Tamagui项目中，当开发者尝试使用Next.js的next/font功能时，会遇到构建阶段报错的问题。具体表现为在执行yarn next build命令时，系统抛出TypeError: Cannot read properties of undefined (reading '0')错误。

问题分析

这个问题的根源在于Tamagui的配置方式与Next.js字体处理机制之间的冲突。Next.js的字体系统在构建时会执行特殊的转换逻辑，而Tamagui的withTamagui插件在构建过程中会先于Next.js的字体转换执行esbuild处理，导致两者时序上的冲突。

深入技术层面来看，next/font特别是next/font/local在内部会生成文件到.next的js缓存中，这些操作不适合在Tamagui配置的编译/构建周期中执行。

解决方案

1. 使用CSS变量间接引用

核心思路是将字体定义与Tamagui配置解耦，通过CSS变量作为中间层：

1. 首先定义字体变量映射：

export const fontVars = {
  body: '--font-body',
  heading: '--font-heading',
  mono: '--font-mono',
} as const

2. 在Tamagui配置中使用这些变量：

const headingFont = createFont({ 
  family: fontVars.heading,
  // 其他字体配置...
})

3. 单独处理Next.js字体定义：

import { GeistSans } from 'geist/font/sans'
import { GeistMono } from 'geist/font/mono'
import localFont from 'next/font/local'

const headingFont = localFont({
  // 字体配置...
})

export const fonts = {
  heading: headingFont.style.fontFamily,
  body: GeistMono.style.fontFamily,
  mono: GeistMono.style.fontFamily,
}

2. 全局样式注入

在应用入口文件(_app.tsx)中，通过全局样式将字体变量应用到根元素：

<style global jsx>
{`
  :root {
    ${Object.entries(fonts)
      .map(([varName, family]) => `${fontVars[varName]}: ${family};`)
      .join('\n')}
  }
  html {
    font-family: var(${fontVars.body});
  }
`}
</style>

技术要点

1. 变量隔离：通过CSS变量作为中间层，避免了Tamagui直接引用Next.js字体模块导致的构建时序问题。

2. 全局作用域：使用全局样式确保字体变量能够作用于整个应用，包括Radix等第三方组件挂载的根body元素。

3. 类型安全：通过TypeScript的satisfies关键字确保字体定义与变量映射的类型一致性。

注意事项

1. 对于使用Pages Router的项目，需要特别注意字体作用域问题，确保样式能正确应用到根元素。

2. 如果项目同时支持Web和Native平台，可以为Native平台创建单独的配置文件，直接使用字符串形式的字体定义。

3. 避免在Tamagui配置文件中直接导入next/font相关模块，这会导致构建失败。

总结

通过CSS变量中间层和全局样式注入的方案，我们成功解决了Tamagui与Next.js字体系统的集成问题。这种方法不仅解决了构建错误，还保持了代码的清晰结构和跨平台兼容性，是处理类似框架间集成问题的良好实践。