# 在 Linux 上安装 Windows 或 macOS 字体库

> 在 Linux 上安装、切换 Windows 或 macOS 字体，以及恢复系统字体。

Source: https://console.getchrovia.com/zh/docs/sdk-linux-fonts

本指南适用于 Ubuntu / Debian 无头采集服务器。按浏览器的目标平台安装 Windows 或 macOS 字体；需要切换时，可以安装两套。

使用运行爬虫的用户执行以下命令。Docker 部署请在浏览器所在的容器内操作。本指南使用系统级字体设置，不按浏览器实例区分。

| 目标平台 | 下载 | 大小 |
| --- | --- | --- |
| Windows | [windows-fonts.zip](https://console.getchrovia.com/api/assets/fonts/windows-fonts.zip) | 约 204 MB |
| macOS | [macos-fonts.tar.gz](https://console.getchrovia.com/api/assets/fonts/macos-fonts.tar.gz) | 约 513 MB |

## 1. 准备环境

```sh
sudo apt-get update
sudo apt-get install -y ca-certificates curl fontconfig unzip tar gzip
mkdir -p "$HOME/.cache/chrovia-font-downloads"
cd "$HOME/.cache/chrovia-font-downloads"
```

## 2. 下载并解压

停止浏览器后，执行所需平台的命令。需要两套字体时，分别执行 Windows 和 macOS 部分。

### Windows

```sh
curl -fL --retry 3 --connect-timeout 15 \
  https://console.getchrovia.com/api/assets/fonts/windows-fonts.zip \
  -o windows-fonts.zip &&
printf '%s  %s\n' \
  f73fafa0081a1ba0714531f7a4d45d4fa47e6fbfa1753a6bd5a030d5f0519fc7 \
  windows-fonts.zip | sha256sum -c - &&
sudo mkdir -p /opt/windows-fonts &&
sudo unzip -o windows-fonts.zip -d /opt/windows-fonts
```

解压完成后，设置字体读取权限：

```sh
sudo chmod -R a+rX /opt/windows-fonts
```

### macOS

```sh
curl -fL --retry 3 --connect-timeout 15 \
  https://console.getchrovia.com/api/assets/fonts/macos-fonts.tar.gz \
  -o macos-fonts.tar.gz &&
printf '%s  %s\n' \
  f2e48e5bc9cee81a96adae994a2695d3cfe5ce5dc63dccd5642c61da96397c89 \
  macos-fonts.tar.gz | sha256sum -c - &&
sudo mkdir -p /opt/macos-fonts &&
sudo tar --no-same-owner -xzf macos-fonts.tar.gz -C /opt/macos-fonts &&
sudo chmod -R a+rX /opt/macos-fonts
```

## 3. 选择字体库

运行以下命令启用 Windows 字体。启用 macOS 字体时，将 XML 中的 `/opt/windows-fonts` 改为 `/opt/macos-fonts`。

```sh
sudo rm -f /etc/fonts/conf.d/99-windows-fonts.conf \
  /etc/fonts/conf.d/99-macos-fonts.conf
sudo tee /etc/fonts/conf.d/99-chrovia-fonts.conf >/dev/null <<'EOF'
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>
  <reset-dirs />
  <dir>/opt/windows-fonts</dir>
</fontconfig>
EOF
```

## 4. 刷新缓存并检查

如果浏览器启动器或服务设置了 `FONTCONFIG_FILE`、`FONTCONFIG_PATH`，请取消这些设置，然后执行以下命令：

```sh
unset FONTCONFIG_FILE FONTCONFIG_PATH
fc-cache -f
fc-list --format='%{file}\n' | sort -u
```

确认列表非空，所有字体路径均位于所选的 `/opt/windows-fonts/` 或 `/opt/macos-fonts/` 下。

检查字体匹配，macOS 将 `Arial` 改为 `Helvetica`：

```sh
fc-match -f '%{family}: %{file}\n' 'Arial'
```

确认返回的字体族和文件路径符合所选字体库，然后完全退出并重新启动浏览器或爬虫服务。

## 切换字体库

两套字体都已安装并完成上述配置后，先停止浏览器，再执行目标平台对应的命令。

切换到 Windows：

```sh
sudo sed -i 's|/opt/macos-fonts|/opt/windows-fonts|' /etc/fonts/conf.d/99-chrovia-fonts.conf &&
fc-cache -f
```

切换到 macOS：

```sh
sudo sed -i 's|/opt/windows-fonts|/opt/macos-fonts|' /etc/fonts/conf.d/99-chrovia-fonts.conf &&
fc-cache -f
```

按第 4 步重新检查字体路径和匹配结果，再启动浏览器。

## 恢复系统字体

执行以下命令恢复系统字体：

```sh
sudo rm -f /etc/fonts/conf.d/99-chrovia-fonts.conf &&
fc-cache -f
```

之后完全退出并重新启动浏览器或爬虫服务。

在 DevTools 的 **Computed → Rendered Fonts** 中查看网页实际使用的字体。浏览器实例配置见 [Extended Preferences](https://console.getchrovia.com/zh/docs/sdk-extended-preferences)。