all in

2025-12-05 00:09:32 +08:00
parent bb3d22eabf
commit 3d1dbb3f97
214 changed files with 113060 additions and 1232 deletions
@@ -0,0 +1,218 @@
+# 思源黑体（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