Quartz博客项目自定义字体在GitHub Pages部署失败的解决方案

问题现象

在使用Quartz博客框架搭建个人博客时，开发者可能会遇到一个典型的字体加载问题：本地开发环境下自定义字体能够正常显示，但当部署到GitHub Pages或Vercel等平台后，字体却无法加载，页面只能回退到默认字体。

问题根源分析

经过技术排查，发现问题的核心在于CSS中@font-face规则的URL路径配置。在Quartz项目中，字体文件通常存放在/static目录下，开发者在CSS中可能会这样引用：

@font-face {
  font-family: 'CustomFont';
  src: url('/static/fonts/custom-font.woff2') format('woff2');
}

这种写法在本地开发时能够正常工作，因为本地服务器通常将站点根目录映射到项目根目录。然而，当项目部署到GitHub Pages等平台时，如果站点被部署在子目录下（如username.github.io/quartz），上述绝对路径引用就会失效。

解决方案

要解决这个问题，需要根据部署环境的实际路径调整字体引用URL。具体有以下几种方法：

方法一：使用相对路径

@font-face {
  font-family: 'CustomFont';
  src: url('./static/fonts/custom-font.woff2') format('woff2');
}

方法二：使用Jekyll/Liquid模板变量（适用于GitHub Pages）

如果项目使用Jekyll构建，可以利用站点配置中的baseurl变量：

@font-face {
  font-family: 'CustomFont';
  src: url('{{ site.baseurl }}/static/fonts/custom-font.woff2') format('woff2');
}

方法三：修改Quartz配置

在Quartz的配置文件中，确保baseUrl设置正确，并确保字体路径与之匹配：

# quartz.config.yaml
baseUrl: /quartz  # 根据实际部署路径设置

然后在CSS中使用：

@font-face {
  font-family: 'CustomFont';
  src: url('{{ .Site.BaseURL }}/static/fonts/custom-font.woff2') format('woff2');
}

验证方案

为确保修改有效，建议采取以下验证步骤：

1. 本地构建测试：运行hugo server -D查看本地预览
2. 生产环境构建测试：运行hugo生成静态文件，检查public目录中的CSS文件路径是否正确
3. 部署后使用浏览器开发者工具检查网络请求，确认字体文件是否成功加载

最佳实践建议

1. 统一开发与生产环境：尽量使开发环境的URL结构与生产环境保持一致
2. 使用构建工具处理路径：考虑使用PostCSS、Webpack等工具自动处理资源路径
3. 字体文件优化：确保字体文件经过适当压缩（如woff2格式），并考虑使用字体子集减少文件大小
4. 备用字体方案：在@font-face规则中添加本地字体回退，提高加载可靠性

总结

静态站点部署中的资源路径问题是常见挑战，特别是在使用GitHub Pages等平台时。通过理解不同环境下的URL解析机制，并采用适当的路径引用策略，可以确保自定义字体等资源在各种环境下都能正常加载。Quartz博客框架作为基于Hugo的解决方案，开发者需要特别注意静态资源路径的配置，才能获得一致的跨环境体验。