# 思源黑体（Source Han Sans SC）本地化部署指南

本文档说明如何在项目中本地化部署思源黑体字体。

## 📋 已完成的配置

以下配置已自动完成，无需手动操作：

### 1. ✅ 字体 CSS 定义

文件：`app/styles/fonts/source-han-sans.css`

已定义 3 个字重的 `@font-face` 规则：
- Regular (400)
- Medium (500)
- Bold (700)

### 2. ✅ 项目中引入字体

文件：`app/root.tsx`

已在以下位置添加：
- 第 30 行：导入 CSS 文件
- 第 267 行：在 `links()` 函数中添加样式链接

### 3. ✅ Tailwind 配置更新

文件：`tailwind.config.ts`

已将 `Source Han Sans SC` 添加到字体栈首位（第 28 行）。

## 🚀 快速开始

### 步骤 1：下载字体文件

**Windows PowerShell（推荐）**：
```powershell
# 在项目根目录执行
.\scripts\download-fonts.ps1
```

**手动下载**：
访问以下链接直接下载字体文件到 `public/fonts/source-han-sans/`：
- [SourceHanSansSC-Regular.otf](https://github.com/adobe-fonts/source-han-sans/raw/release/SubsetOTF/SC/SourceHanSansSC-Regular.otf) (约 8MB)
- [SourceHanSansSC-Medium.otf](https://github.com/adobe-fonts/source-han-sans/raw/release/SubsetOTF/SC/SourceHanSansSC-Medium.otf) (约 8MB)
- [SourceHanSansSC-Bold.otf](https://github.com/adobe-fonts/source-han-sans/raw/release/SubsetOTF/SC/SourceHanSansSC-Bold.otf) (约 8MB)

### 步骤 2：重启开发服务器

```bash
npm run dev
```

### 步骤 4：验证字体加载

1. 打开浏览器开发者工具（F12）
2. 切换到 **Network** 标签
3. 筛选 "Font" 类型
4. 刷新页面
5. 查看是否加载了 `SourceHanSansSC-*.otf` 文件

## 📁 目录结构

```
docreview/
├── app/
│   ├── root.tsx                          # ✅ 已配置
│   └── styles/
│       └── fonts/
│           └── source-han-sans.css       # ✅ 已创建
├── public/
│   └── fonts/
│       └── source-han-sans/
│           ├── README.md                 # 使用说明
│           ├── SourceHanSansSC-Regular.otf   # ⏳ 需要下载
│           ├── SourceHanSansSC-Medium.otf    # ⏳ 需要下载
│           └── SourceHanSansSC-Bold.otf      # ⏳ 需要下载
├── scripts/
│   └── download-fonts.ps1                # ✅ 自动下载脚本
├── tailwind.config.ts                    # ✅ 已配置
└── docs/
    └── 思源黑体字体配置指南.md           # 本文档
```

## 🔄 手动下载字体（备选方案）

如果自动安装脚本无法使用，可以手动下载字体文件：

### 方法 1：GitHub 官方仓库

访问：https://github.com/adobe-fonts/source-han-sans/releases

下载文件：
- SourceHanSansSC-Regular.otf
- SourceHanSansSC-Medium.otf
- SourceHanSansSC-Bold.otf

放置到：`public/fonts/source-han-sans/`

### 方法 2：Google Fonts

访问：https://fonts.google.com/noto/specimen/Noto+Sans+SC

下载 Noto Sans SC（与思源黑体相同），然后重命名为 SourceHanSansSC-*.otf

## ⚡ 性能优化（可选）

### 1. 转换为 WOFF2 格式

WOFF2 比 OTF 文件小 30-50%，加载更快。

**使用在线工具**：
- CloudConvert: https://cloudconvert.com/otf-to-woff2
- Font Squirrel: https://www.fontsquirrel.com/tools/webfont-generator

**使用命令行**：
```bash
pip install fonttools brotli

pyftsubset SourceHanSansSC-Regular.otf \
  --output-file=SourceHanSansSC-Regular.woff2 \
  --flavor=woff2
```

转换后，更新 `app/styles/fonts/source-han-sans.css` 中的文件路径。

### 2. 字体子集化（高级）

只包含项目中实际使用的汉字，可大幅减小文件体积。

```bash
# 示例：只保留常用 3500 个汉字
pyftsubset SourceHanSansSC-Regular.otf \
  --output-file=SourceHanSansSC-Regular-subset.woff2 \
  --flavor=woff2 \
  --text-file=common-chinese-chars.txt
```

### 3. 启用 CDN 缓存

在生产环境配置 Nginx/CDN，为字体文件设置长期缓存：

```nginx
location ~* \.(woff2|woff|otf|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}
```

## 🐛 常见问题

### Q1：字体没有生效？

**检查步骤**：
1. 确认字体文件存在于 `public/fonts/source-han-sans/`
2. 打开浏览器开发者工具 → Network → 查看字体是否加载
3. 检查控制台是否有 404 错误
4. 验证 CSS 文件路径是否正确

### Q2：字体文件太大，加载慢？

**解决方案**：
1. 转换为 WOFF2 格式（减小 30-50%）
2. 使用字体子集化（只包含需要的字符）
3. 启用 CDN 和浏览器缓存
4. 考虑使用 `font-display: swap` 避免白屏

### Q3：如何添加更多字重？

**步骤**：
1. 下载对应字重的 OTF 文件
2. 放置到 `public/fonts/source-han-sans/`
3. 在 `source-han-sans.css` 中添加 `@font-face` 规则
4. 重启开发服务器

可用字重：
- ExtraLight (250)
- Light (300)
- Normal (350)
- Regular (400)
- Medium (500)
- Bold (700)
- Heavy (900)

### Q4：想回退到系统字体？

**步骤**：
1. 在 `tailwind.config.ts` 中移除 `"Source Han Sans SC",`
2. 注释 `root.tsx` 中的字体 CSS 导入
3. 重启开发服务器

## 📄 许可证

思源黑体使用 **SIL Open Font License 1.1** 许可证。

- ✅ 可免费用于商业项目
- ✅ 可修改和再分发
- ❌ 不能单独出售字体文件本身

详见：https://github.com/adobe-fonts/source-han-sans/blob/release/LICENSE.txt

## 🔗 相关资源

- **官方仓库**：https://github.com/adobe-fonts/source-han-sans
- **Google Fonts（Noto Sans SC）**：https://fonts.google.com/noto/specimen/Noto+Sans+SC
- **字体预览**：https://source.typekit.com/source-han-sans/
- **设计说明**：https://blog.typekit.com/2014/07/15/introducing-source-han-sans/

## 📞 需要帮助？

如有问题，请：
1. 查看本文档的常见问题部分
2. 阅读 `public/fonts/source-han-sans/README.md`
3. 检查浏览器开发者工具的控制台输出

---

**最后更新**：2025-11-27