Quartz项目中使用自定义字体的配置指南

在构建静态网站时，字体的选择和应用是影响用户体验和视觉设计的重要因素。本文将详细介绍如何在Quartz项目中正确配置和使用自定义字体，包括Google字体和本地字体。

字体配置基础

Quartz项目通过quartz.config.ts文件中的typography配置项来管理字体设置。基础配置格式如下：

typography: {
  header: {
    name: "字体名称",
    weights: [400, 700],
    includeItalic: false,
  },
  body: {
    name: "字体名称",
    weights: [400, 700],
    includeItalic: false,
  },
  code: "字体名称",
}

Google字体的使用

对于Google字体库中的字体，配置相对简单。只需确保字体名称与Google字体库中的名称完全一致即可。例如：

typography: {
  header: {
    name: "Oswald",
    weights: [400, 700],
    includeItalic: false,
  },
  body: {
    name: "Courier Prime",
    weights: [400],
    includeItalic: false,
  },
  code: "IBM Plex Mono",
}

注意点：

1. 字体名称区分大小写
2. 多单词字体名称需要用引号括起来
3. weights数组指定需要的字重
4. includeItalic控制是否包含斜体变体

本地字体的应用

对于不在Google字体库中的字体，如Haettenschweiler，需要通过以下步骤实现：

1. 将字体文件(如.woff2格式)放入项目的static目录
2. 在custom.scss中使用@font-face规则定义字体

@font-face {
  font-family: "Haettenschweiler";
  src: url("/static/Haettenschweiler.woff2") format("woff2");
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}

3. 覆盖默认的CSS变量

:root {
  --headerFont: "Haettenschweiler", system-ui, sans-serif !important;
}

常见问题解决

1. 字体加载失败：确保字体名称拼写正确，特别是多单词字体名称需要用引号括起来
2. OG图片生成失败：当所有字体都加载失败时，OG图片插件会报错。确保至少有一个字体正确加载
3. 字体权重问题：配置的weights数组必须与字体实际提供的字重匹配

最佳实践建议

1. 优先使用Google字体库中的字体，简化配置
2. 对于本地字体，提供多种格式(woff2, woff)以增强兼容性
3. 限制字体数量和字重，优化页面加载性能
4. 为本地字体设置font-display: swap，避免布局偏移
5. 在开发过程中使用npx quartz build --serve命令实时预览字体效果

通过以上配置，开发者可以灵活地为Quartz项目定制独特的字体风格，既可以使用Google提供的丰富字体资源，也可以集成特定的品牌字体，打造个性化的网站体验。