Panda CSS 中使用 Google Fonts 的正确方式

问题背景

在使用 Panda CSS 构建组件库时，开发者尝试通过 globalFontface 配置来引入 Google Fonts 的 Poppins 字体。虽然配置看似正确，字体文件也能正常加载，但实际应用时字体并未生效。

错误分析

开发者使用了以下配置方式：

globalFontface: {
  Poppins: [
    {
      src: 'url(https://fonts.googleapis.com/css2?family=Poppins&display=swap)',
      fontWeight: '400',
      fontStyle: 'normal',
      fontDisplay: 'swap',
    },
    // 其他字重配置...
  ],
}

这种配置方式存在两个主要问题：

1. URL 使用错误：Google Fonts 提供的 URL 实际上是一个 CSS 文件，而不是直接的字体文件
2. 方法选择不当：globalFontface 用于生成 @font-face 规则，而 Google Fonts 的正确使用方式是通过 @import 引入

正确解决方案

方法一：使用 @import 导入

在 Panda CSS 的全局 CSS 中直接导入 Google Fonts：

@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@400;600&display=swap');

然后在 Panda 配置中定义字体：

theme: {
  extend: {
    fonts: {
      body: 'Poppins, sans-serif',
      heading: 'Poppins, sans-serif',
    }
  }
}

方法二：直接引用字体文件

如果确实需要使用 @font-face，应该直接引用字体文件 URL 而非 Google Fonts 的 CSS URL：

globalFontface: {
  Poppins: [
    {
      src: 'url(https://fonts.gstatic.com/s/poppins/v20/...)',
      fontWeight: '400',
    },
    // 其他字重配置...
  ],
}

最佳实践建议

1. 优先使用 @import 方式：这是 Google Fonts 推荐的使用方式，简单且维护方便
2. 考虑性能影响：Google Fonts 会自动提供最优的字体格式和 CDN 分发
3. 字体加载策略：可以使用 font-display: swap 来优化字体加载期间的显示效果
4. 字体子集化：如果只需要特定字符集，可以在 Google Fonts URL 中添加 text 参数来减少字体文件大小

总结

在 Panda CSS 中使用外部字体时，需要根据字体来源选择正确的引入方式。对于 Google Fonts 这类托管服务，直接使用 @import 是最简单有效的方法，而 globalFontface 更适合用于自托管字体文件的场景。理解这些区别可以帮助开发者避免常见的字体加载问题，确保网页字体按预期显示。