zqlit/blog
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 全量梳理文档结构；补 Gitea 迁移指南 / 架构精简候选；架构总览补证书管家子系统

Browse Source 
用户四问：「把项目文件全部理一遍 还有readme文件」「gitea 后面可能还要迁移 帮我写一个迁移文档」
「证书管家做完了吗」「感觉现在架构还是复杂了」

一、文档梳理：根目录 15 个 md → 2 个

根目录只留 README.md（入口）+ 架构总览.md（现状唯一事实源），其余全部归位：

  docs/
  ├── README.md              ← 新增：文档地图（入口 / 当前有效 / 历史归档 三层）
  ├── 证书管家.md             ← 原「函数版证书管家-方案.md」改名
  │                              （它早已是「现状+沿革」文档，标题名不副实 —— 签发早已不在 CF Worker）
  ├── Gitea迁移指南.md        ← 新增
  ├── 架构精简候选.md         ← 新增
  ├── CNB构建落地方案.md / GITEA_SECRETS.md
  └── archive/{平台与选型,功能与修复,主题与内容}/   ← 32 份

- 32 个归档文档统一加 `> 📦 本文档已归档` banner，并指向架构总览
  —— 这个仓库历史文档里全是「权威口径」，混看很容易拿废弃结论当现状
- gitea-backup/ → deploy/gitea/（原名「backup」不准，它是部署包；与其它 deploy 单元并列）
- 新增 md 链接校验（python 脚本，中文路径用 sed 不安全）→ 首轮 18 处断链
  （多一层目录要让 banner 里的相对路径补一个 ../）→ 修正后 0 断链

二、新增 docs/Gitea迁移指南.md（★ 有死线：境外 VPS 11 月到期）

★ 核心价值是「指出迁移面已大幅缩小」：仓库原有的 deploy/gitea/迁移前检查清单.md
（2026-10-04）是为「Gitea + act_runner + 又拍云同步 *整套* 搬迁」写的，**那个前提已经不存在**——
构建归 CNB，runner / upyun-sync / 中转机 / COS 都不需要了。迁移实际只剩「搬数据卷 + 改地址」。

★★ 全文最重要：本仓有 9 处写死了旧地址，按易漏程度排序（1-3 本机，4-5 线上）
  1 本机 .git/config 的 gitea remote
  2 scripts/setup-cnb-remotes.sh 的 GITEA_URL 默认值
  3 deploy/editor-api/bootstrap.sh 的 GITEA_URL 默认值
  4 ★ /srv/editor-api/.env 的 GITEA_URL      ← 漏了会「持续报错但只警告不阻断」，没人发现
  5 ★ /srv/blog 的 gitea remote               ← 同上
  6 docs/GITEA_SECRETS.md
  7-9 架构总览.md / README.md / editor-api/README.md
（不用改：docker-compose.editor.yml、server.mjs、pushall 别名 —— 只引用 remote 名字）

另含：建议新实例改用域名而非 IP（以后搬机器只改 DNS；⚠️ Gitea 28 起只读 ROOT_URL 不读
[server] DOMAIN）；rsync 而非 dump（属主必须 uid/gid 1000）；切换顺序「先建新的→验证→再拆旧的」；
验证清单强调 `git push gitea --dry-run`；第九节给出「干脆不留这个辅仓」的选项与判断依据。

顺带修掉两个硬伤：
- deploy/gitea/docker-compose.yml 的镜像 tag `1.28.0-rootless` 根本不存在
  （Gitea 28 起去掉 1. 前缀）→ 改 28.0.0-rootless（pin 死，不用 latest）
- deploy/gitea/.gitignore 漏了 backups/（跑一次备份就会把含 secrets 的 dump 写进历史）

三、证书管家核实（结论：已上线运行，2 个遗留）

线上实测：容器 Up (healthy)；/preflight 7/7 全过；3 组域名；下次自动续期 04:10。

遗留 ① writeapi.usj.cc 证书没纳管（真问题）：nginx 配置在 /www/conf.d/writeapi.usj.cc.conf，
不在 /www/sites/ 管理树里 → 1Panel 的 ssl/upload+sslID 物化碰不到它。
实测仍是 RSA / CN=usj.cc / 到期 2026-12-07，本项目续期不会更新 → 12 月会断。
遗留 ② dnsapi.usj.cc 没上 HTTPS。
（澄清假问题：200181.xyz 公网看到的 LE 证书是 CF 自家边缘证书，与本项目无关）

四、新增 docs/架构精简候选.md（回应「架构还是复杂了」）

结论：复杂度不在件数，在「跨 6 个环境，其中 4 个要自己维护」。国内机 9 个容器里属于本项目的
只有 3 个，能动的只有 2 个。5 个候选 + 建议执行顺序：
  1 停 certimate 容器（工作流已全停用）——先 stop 观察，别急着删
  2 cn-dns-helper 大概率已是遗留（「Worker 侧签发」时代产物；现在签发在国内机且自带 dnsprovider，
    /preflight 显示 CF 凭据可读；Worker 侧 dnsremoted.ts 已无任何引用）
  3 Gitea：迁 or 不留
  4 两套写作前端收敛（本轮不动，先看使用频率）
  5 writeapi.usj.cc 证书纳管（12 月死线）
并明确列出 6 项「必要复杂度，不建议动」。

五、架构总览补齐证书管家子系统（★ 之前完全缺席）

一个完整子系统在「事实源文档」里一个字都没有 —— 这本身就是文档债。补：
- §0 一句话（四→五个子系统）、§1.1 子系统表、§1.2 地址地图两行
- **新增 §5.7 证书管家**：职责划分 / 为什么非要这么分（Worker 免费版 CPU 10ms）/
  三条不能破的红线（Worker 不得签发 · 证书路由只认 Bearer 会话 · 角色必须正着枚举放行）/
  纳管域名表 / 与 certimate 的关系 / 已知遗留
- .cnb.yml 行数 284 → 337（数字漂了）；头部更新时间 → 2026-10-06；附录表改指 docs/
- §6 待办：#13（证书遗留）、#14（复杂度盘点）新增；#7 改写为「Gitea 11 月到期，★ 有死线」

六、记忆

.workbuddy/memory/MEMORY.md 新增「文档结构」「Gitea 迁移死线」两节；证书管家节补实测与遗留。
This commit is contained in:
zqlit committed 2026-10-06 22:27:36 +08:00
1 parent 15a8b502db
commit 1568b150b3
48 files changed
+782 -100
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/archive/主题与内容/CLEANUP_GUIDE.md
+184
View File
@@ -0,0 +1,184 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../架构总览.md)。
# 🧹 Ying主题文档清理指南
## 📋 需要删除的文件（20个）
这些文件都已经整理到 `docs/性能优化文档/` 文件夹，可以安全删除。
### 删除命令（Windows CMD）
```bash
cd E:\GitHub\blog
# 删除优化文档
del themes\Ying\OPTIMIZATION_REPORT.md
del themes\Ying\OPTIMIZATION_STEP1_PLAN.md
del themes\Ying\TEST_STEP1.md
del themes\Ying\OPTIMIZATION_STEP2_PLAN.md
del themes\Ying\OPTIMIZATION_STEP2_FINAL.md
del themes\Ying\OPTIMIZATION_STEP3_PLAN.md
del themes\Ying\OPTIMIZATION_COMPLETE_GUIDE.md
del themes\Ying\IMPLEMENTATION_SUMMARY.md
del themes\Ying\TEST_JS_OPTIMIZATION.md
del themes\Ying\GUIDE_FONT_SUBSETTING.md
del themes\Ying\PLAN1_COMPLETE_SUMMARY.md
del themes\Ying\PJAX_COMPATIBILITY.md
del themes\Ying\PJAX_FIX_SUMMARY.md
del themes\Ying\FONT_OPTIMIZATION_MANUAL.md
del themes\Ying\FONT_OPTIMIZATION_FALLBACK.md
del themes\Ying\FINAL_FONT_TEST.md
del themes\Ying\GITHUB_ACTIONS_GUIDE.md
del themes\Ying\COMMIT_GUIDE.md
del themes\Ying\ACTIONS_FIX_GUIDE.md
del themes\Ying\PROJECT_COMPLETE_SUMMARY.md
```
### 删除命令（Mac/Linux）
```bash
cd E:\GitHub\blog
# 删除优化文档
rm themes/Ying/OPTIMIZATION_REPORT.md
rm themes/Ying/OPTIMIZATION_STEP1_PLAN.md
rm themes/Ying/TEST_STEP1.md
rm themes/Ying/OPTIMIZATION_STEP2_PLAN.md
rm themes/Ying/OPTIMIZATION_STEP2_FINAL.md
rm themes/Ying/OPTIMIZATION_STEP3_PLAN.md
rm themes/Ying/OPTIMIZATION_COMPLETE_GUIDE.md
rm themes/Ying/IMPLEMENTATION_SUMMARY.md
rm themes/Ying/TEST_JS_OPTIMIZATION.md
rm themes/Ying/GUIDE_FONT_SUBSETTING.md
rm themes/Ying/PLAN1_COMPLETE_SUMMARY.md
rm themes/Ying/PJAX_COMPATIBILITY.md
rm themes/Ying/PJAX_FIX_SUMMARY.md
rm themes/Ying/FONT_OPTIMIZATION_MANUAL.md
rm themes/Ying/FONT_OPTIMIZATION_FALLBACK.md
rm themes/Ying/FINAL_FONT_TEST.md
rm themes/Ying/GITHUB_ACTIONS_GUIDE.md
rm themes/Ying/COMMIT_GUIDE.md
rm themes/Ying/ACTIONS_FIX_GUIDE.md
rm themes/Ying/PROJECT_COMPLETE_SUMMARY.md
```
---
## ✅ 保留的文件
**不要删除这些文件：**
- ✅ `README.md` - 主题说明文档
- ✅ `archetypes/post.md` - Hugo模板文件
---
## 📊 清理验证
### 清理前
```bash
dir themes\Ying\*.md
```
**应该看到20个优化文档**
### 清理后
```bash
dir themes\Ying\*.md
```
**应该只看到2个文件：**
- README.md
- archetypes\post.md
---
## 💡 已整理的文档位置
**所有优化文档已整理到：**
```
E:\GitHub\blog\docs\性能优化文档\
```
**索引文档：**
```
E:\GitHub\blog\docs\性能优化文档\README.md
```
---
## 🎯 快速清理命令
### 一键清理（Windows PowerShell）
```powershell
cd E:\GitHub\blog
# 删除所有优化文档
Remove-Item themes\Ying\OPTIMIZATION_*.md -Force
Remove-Item themes\Ying\TEST_*.md -Force
Remove-Item themes\Ying\PLAN1_*.md -Force
Remove-Item themes\Ying\PJAX_*.md -Force
Remove-Item themes\Ying\FONT_*.md -Force
Remove-Item themes\Ying\FINAL_*.md -Force
Remove-Item themes\Ying\GITHUB_*.md -Force
Remove-Item themes\Ying\COMMIT_*.md -Force
Remove-Item themes\Ying\ACTIONS_*.md -Force
Remove-Item themes\Ying\PROJECT_*.md -Force
Remove-Item themes\Ying\IMPLEMENTATION_*.md -Force
Remove-Item themes\Ying\GUIDE_*.md -Force
Remove-Item themes\Ying\OPTIMIZATION_COMPLETE_GUIDE.md -Force
Write-Host "✅ 清理完成"
```
---
## 📝 清理后提交
```bash
# 查看删除的文件
git status
# 提交清理
git add -A
git commit -m "docs: 清理Ying主题冗余文档
- 删除20个优化相关文档
- 已整理到 docs/性能优化文档/ 文件夹
- 保留 README.md 和 archetypes/post.md"
# 推送
git push origin main
```
---
## 🎉 清理完成
### 清理效果
- ✅ Ying主题目录更简洁
- ✅ 只保留必要文件
- ✅ 优化文档已整理到专门文件夹
- ✅ 便于维护和查找
### 文档位置
**所有优化文档：**
```
E:\GitHub\blog\docs\性能优化文档\
```
**索引文档：**
```
E:\GitHub\blog\docs\性能优化文档\README.md
```
---
**清理指南完成！** 🎉
**按照指南操作即可清理Ying主题中的冗余文档！**
docs/archive/主题与内容/博客字体优化文章规划.md
+357
View File
@@ -0,0 +1,357 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../架构总览.md)。
# 博客字体优化方案 - 文章规划
## 📋 文章定位
- **目标读者：** 生活博主、非技术背景博主
- **文章风格：** 通俗易懂、重效果、少术语
- **核心卖点：** 用真实案例告诉你，字体优化能让博客快多少
---
## 📝 推荐文章结构
### 标题建议（选一个）
1. **我的博客加载快了50%，只因为改了字体**
2. **博客太慢？可能是字体拖后腿了**
3. **从3秒到1秒：我是怎么优化博客字体的**
4. **博客字体优化：一个让网站变快的简单技巧**
**推荐：** 第1个（有具体数字，有悬念）
---
### 文章大纲
```
一、开头：我的博客有多慢？（引入问题）
二、发现问题：原来是字体拖后腿（诊断过程）
三、字体优化到底是什么？（通俗解释）
四、我是怎么做的（真实案例）
五、效果对比（数据说话）
六、你也可以这样做（通用方案）
七、总结
```
---
## 📝 详细内容规划
### 一、开头：我的博客有多慢？（200字）
**写法：** 从用户视角出发，描述痛点
**要点：**
- 博客打开要3秒以上
- 移动端更慢，用户等不及就走了
- 用了各种缓存、CDN都没用
- 最后发现是字体文件太大
**示例段落：**
> 我的博客一直有个问题：打开太慢。
>
> 用PageSpeed Insights测了一下，移动端得分只有60分。加载时间3秒多，这在现在这个"3秒定生死"的时代，基本等于告诉用户"别等了，走吧"。
>
> 我试过开CDN、压缩图片、用缓存插件，效果都不明显。直到有一天，我在Network面板里发现了一个1.2MB的字体文件...
---
### 二、发现问题：原来是字体拖后腿（300字）
**写法：** 用通俗语言解释问题
**要点：**
- 中文字体为什么这么大？（2万个字符）
- 你的博客实际用了多少字？（可能只有2000个）
- 浪费了90%的带宽在不需要的字上
**类比：**
> 这就好比你要寄一封信，但邮局让你把整本字典一起寄出去。你只用了里面的几十个字，却要为整本字典的重量买单。
**数据展示：**
```
原始字体：1,226 KB（包含20,000+字符）
实际使用：2,485字符
浪费：90%的字符从未出现过
```
---
### 三、字体优化到底是什么？（200字）
**写法：** 用比喻解释，避免术语
**核心概念：**
- 字体子集化：只保留你用到的字
- 就像"按需定制"，不是"全买"
**比喻：**
> 字体优化就像是去餐厅点菜。
>
> 原来的方式：把整本菜单都买下来，只吃其中几道。
> 优化后的方式：只点你要吃的菜，吃完走人。
>
> 结果：花更少的钱，吃得一样饱。
**技术原理（简化版）：**
1. 扫描你博客的所有文章
2. 提取实际使用的字符
3. 生成一个"精简版"字体
4. 体积减少80%+
---
### 四、我是怎么做的（真实案例）（500字）
**写法：** 分步骤讲解，附代码和截图
**步骤1：分析现状**
```
工具：Chrome DevTools → Network面板
发现：zql-v2.woff2 文件大小 1.2MB
```
**步骤2：选择工具**
- 推荐：Python + fonttools
- 备选：在线工具（无需编程）
**步骤3：提取字符**
```bash
# 运行脚本，自动提取
python subset-font.py
```
**步骤4：生成子集**
```
结果：
- 原始：1,226 KB → 子集：740 KB
- 减少：40%
```
**步骤5：更新CSS**
```css
/* 修改前 */
src: url('../font/zql-v2.woff2');
/* 修改后 */
src: url('../font/zql-v2-subset.woff2');
```
**截图建议：**
1. Network面板显示字体大小对比
2. 脚本运行结果截图
3. 优化前后文件大小对比
---
### 五、效果对比（数据说话）（300字）
**写法：** 用图表和数据展示效果
**数据表格：**
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| 字体大小 | 1.2 MB | 740 KB | -40% |
| 加载时间 | 3.2秒 | 1.8秒 | -44% |
| PageSpeed得分 | 60 | 85 | +42% |
| 移动端体验 | 差 | 良好 | ✅ |
**用户体感：**
> 优化后最明显的变化是：页面"刷"一下就出来了。
>
> 以前打开文章，能明显看到文字先显示为方块，然后才变成正常字体。现在几乎看不到这个过程了。
**截图建议：**
1. PageSpeed Insights优化前后对比
2. Network面板加载瀑布图
3. 实际打开速度对比GIF
---
### 六、你也可以这样做（通用方案）（400字）
**写法：** 提供可复用的方案
**方案A：在线工具（零代码）**
1. 访问 fontsquirrel.com/webfont-generator
2. 上传你的字体文件
3. 选择"Expert"模式
4. 勾选"Custom Subsetting"
5. 下载优化后的字体
6. 替换原文件，更新CSS
**方案B：Python脚本（推荐）**
```bash
# 安装工具
pip install fonttools brotli
# 运行脚本
python subset-font.py
```
**方案C：找我帮忙（最简单）**
- 提供你的博客地址
- 我帮你分析和优化
- 全程指导，保证效果
**注意事项：**
- 优化前备份原文件
- 测试所有页面的显示效果
- 特殊符号可能需要单独处理
---
### 七、总结（150字）
**要点回顾：**
1. 中文字体很大，但你用的字很少
2. 字体优化可以减少40-90%的大小
3. 加载速度提升明显
4. 操作并不复杂
**结尾金句：**
> 博客优化就像减肥：找对方法，效果立竿见影。
>
> 字体优化就是那个你一直忽略、但效果惊人的"减肥方法"。
>
> 试试看，你的博客也能快50%。
---
## 📊 文章数据
### 预期指标
- **字数：** 2000-2500字
- **阅读时间：** 8-10分钟
- **代码块：** 5-6个（简化版）
- **截图：** 8-10张
- **表格：** 2-3个
### SEO关键词
- 博客优化
- 字体优化
- 网站加速
- Hugo优化
- 字体子集化
- PageSpeed提升
---
## 🎨 排版建议
### 标题层级
- H2：大章节（7个）
- H3：小节（每章节2-3个）
- H4：更细的点（少用）
### 视觉元素
- ✅ 数据表格（对比效果）
- ✅ 代码块（简化版，带注释）
- ✅ 截图（Network面板、PageSpeed）
- ✅ 比喻图（餐厅点菜的比喻）
- ✅ 对比图（优化前后）
### 代码展示原则
- 只展示必要的代码
- 每行代码都有注释
- 提供"复制即用"的版本
- 避免大段代码块
---
## 📸 截图清单
### 必须截图
1. [ ] PageSpeed Insights优化前得分
2. [ ] PageSpeed Insights优化后得分
3. [ ] Network面板字体文件大小
4. [ ] 脚本运行结果
5. [ ] 优化前后文件大小对比
### 建议截图
6. [ ] 字体加载瀑布图
7. [ ] 实际打开速度对比
8. [ ] 移动端测试结果
---
## ✍️ 写作技巧
### 开头吸引人
- 用具体数字（"3秒"、"50%"）
- 描述用户痛点（"用户等不及就走了"）
- 制造悬念（"最后发现是..."）
### 中间讲清楚
- 用比喻解释技术概念
- 分步骤讲解，每步都清晰
- 提供"复制即用"的代码
### 结尾有力量
- 总结核心要点
- 给出行动建议
- 用金句收尾
### 语言风格
- ❌ 避免："首先、其次、最后"
- ❌ 避免："众所周知"
- ✅ 使用："我发现"、"我试过"
- ✅ 使用："你也可以"、"很简单"
---
## 🎯 文章亮点
### 独特卖点
1. **真实数据** - 不是理论，是实际优化结果
2. **通俗易懂** - 生活博主也能看懂
3. **可复用** - 读者可以直接照着做
4. **效果明显** - 40%的提升很震撼
### 差异化
- 其他文章：讲技术原理
- 你的文章：讲实际效果 + 简单方案
---
## 📅 写作计划
### 第1天：素材收集
- [ ] 整理优化前后的数据
- [ ] 截图关键页面
- [ ] 准备代码示例
### 第2天：初稿写作
- [ ] 按大纲写完整初稿
- [ ] 插入截图和代码
- [ ] 检查逻辑连贯性
### 第3天：润色发布
- [ ] 精简语言，删除冗余
- [ ] 优化标题和开头
- [ ] 检查错别字
- [ ] 发布并分享
---
## 💡 进阶建议
### 如果想更深入
- 添加"常见问题"章节
- 提供不同Hugo主题的适配方案
- 分享自动化脚本
### 如果想更简洁
- 只保留"问题→方案→效果"三部分
- 删除技术细节，只留结论
- 用对比图代替文字描述
---
**文档版本：** v1.0
**创建日期：** 2026-06-03
**适用场景：** 博客字体优化技术文章
docs/archive/主题与内容/古风官职字符添加指南.md
+166
View File
@@ -0,0 +1,166 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../架构总览.md)。
# 📜 添加古风官职字符到字体子集
## 📋 需要添加的字符
古风官职文本中的特殊字符（可能缺失）：
```
— 庶 民 太 尉 谏 给 簿 司 户 录 丞 判 殿
```
---
## 🚀 方法1：运行Python脚本（推荐）
```bash
cd E:\GitHub\blog
# 运行合并脚本
python scripts/merge_ancient_chars.py
# 重新生成字体子集
python scripts/subset-font-safe.py
```
---
## 🚀 方法2：手动添加字符
### 步骤1：编辑字符列表
打开文件：`themes/Ying/static/font/used_chars.txt`
在文件末尾添加：
```
—庶民太尉谏给簿司户录丞判殿
```
### 步骤2：重新生成字体子集
```bash
cd E:\GitHub\blog
# 重新生成字体子集
python scripts/subset-font-safe.py
```
---
## 🧪 验证添加成功
### 检查字符列表
```bash
# 查看字符列表
type themes\Ying\static\font\used_chars.txt
# 搜索特殊字符
findstr "—" themes\Ying\static\font\used_chars.txt
```
### 检查字体文件
```bash
# 查看字体文件大小
dir themes\Ying\static\font\zql-v2-subset.*
```
**预期：** 字体文件大小应该略有增加（包含新字符）
---
## 📊 预期效果
### 字体大小变化
| 指标 | 添加前 | 添加后 | 变化 |
|------|--------|--------|------|
| **字符数** | 2,485 | ~2,500 | +15 |
| **字体大小** | 757KB | ~760KB | +3KB |
**说明：** 增加15个字符，字体大小增加约3KB（可忽略）
---
## 🎯 使用场景
### 古风官职系统
这些字符用于：
```
正一品 太师 2000
从一品 太尉 1400
正二品 参知政事 1050
...
正九品 主簿 15
从九品 司户参军 5
— 庶民 0
```
**应用场景：**
- 古风游戏
- 历史题材文章
- 等级系统展示
---
## 💡 后续优化
### 如果还有其他特殊字符
1. 收集所有需要的特殊字符
2. 添加到 `used_chars.txt`
3. 重新运行字体子集化
### 自动化
**GitHub Actions会自动处理：**
- 当你发布包含这些字符的文章时
- 自动重新生成字体子集
- 自动部署到UpYun
---
## 🔄 回滚方案
### 如果出现问题
```bash
# 恢复原始字符列表
git checkout themes/Ying/static/font/used_chars.txt
# 重新生成字体子集
python scripts/subset-font-safe.py
```
---
## ✅ 完成确认
### 检查清单
- [ ] 字符已添加到 used_chars.txt
- [ ] 字体子集已重新生成
- [ ] 字体文件大小略有增加
- [ ] 新字符可以正常显示
### 测试
```bash
# 启动Hugo
hugo server -D
# 访问包含古风官职的页面
# 检查字符是否正常显示
```
---
**添加古风官职字符指南完成！** 🎉
**按照指南操作即可完成字符添加！**
docs/archive/主题与内容/性能优化（历史）/01-项目完成总结.md
+302
View File
@@ -0,0 +1,302 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 01-项目完成总结
**创建日期：** 2026-06-03
**版本：** v1.0
**状态：** ✅ 已完成
---
## 🎉 项目概述
### 项目目标
对Hugo主题Ying进行全面性能优化，包括：
- JS按需加载优化
- 字体子集化优化
- GitHub Actions自动化
### 优化效果
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **总体资源** | ~3MB | ~1.5MB | ⚡ -50% |
| **加载速度** | 慢 | 快 | ⚡ +40% |
| **Lighthouse** | 60 | 75-80 | ⚡ +33% |
---
## ✅ 已完成的工作
### 1. JS按需加载优化（第1步）
**完成时间：** 2026-06-03
**优化效果：**
- 首页JS：800KB → 350KB（⚡ -56%）
- 文章页JS：800KB → 450KB（⚡ -44%）
**主要工作：**
- ✅ JS代码拆分为4个bundle
- ✅ 核心JS始终加载
- ✅ 页面特定JS按需加载
- ✅ 非关键JS延迟加载
- ✅ PJAX完美适配
**修改文件：**
- `themes/Ying/layouts/partials/footer.html`
- `themes/Ying/assets/js/modules/mypjax.js`
---
### 2. 字体子集化优化（第2步）
**完成时间：** 2026-06-03
**优化效果：**
- 字体大小：1.2MB → 757KB（⚡ -37%）
**主要工作：**
- ✅ 使用Python fonttools提取字符
- ✅ 生成子集字体（2,485个字符）
- ✅ 更新CSS字体声明
- ✅ 保持所有字符正常显示
**修改文件：**
- `themes/Ying/assets/css/main.css`
- `themes/Ying/static/font/zql-v2-subset.woff2`
- `themes/Ying/static/font/zql-v2-subset.woff`
- `themes/Ying/static/font/used_chars.txt`
---
### 3. GitHub Actions自动化（第3步）
**完成时间：** 2026-06-03
**自动化程度：** 100%
**主要工作：**
- ✅ 创建字体子集化工作流
- ✅ 配置自动触发条件
- ✅ 与deploy.yml完美协调
- ✅ 智能检测变更
- ✅ 自动部署到UpYun
**创建文件：**
- `.github/workflows/subset-fonts.yml`
- `requirements.txt`
---
## 📊 技术实现
### JS优化策略
```
core.js (200KB) - 始终加载
├── UIkit
├── 图标字体
├── 图片灯箱
├── 工具函数
├── 搜索功能
├── 浮动工具
├── 进度条
├── PJAX
└── 主题主逻辑
page-only.js (180KB) - 文章详情页
├── Artalk评论
├── 段落评论
└── 打赏功能
deferred.js (25KB) - 延迟加载
├── Toast消息
└── 图片懒加载
infinite-scroll.js (20KB) - 首页（如果启用）
tiaozhuan.js (8KB) - 特定页面
```
### 字体优化策略
```
原始字体（1.2MB）
├── 20,000+ 字符
└── 完整中文字符集
子集字体（757KB）
├── 2,485 个字符
├── 常用中文字符
├── 英文字母和数字
├── 常用标点符号
└── 特殊符号
优化效果：-37%
```
### 自动化流程
```
用户push内容更新
↓
deploy.yml（部署文章）
↓
subset-fonts.yml（优化字体）
↓
deploy.yml（部署新字体）
↓
✅ 完成！
```
---
## 🎯 项目亮点
### 1. 性能显著提升
- ✅ 资源减少50%
- ✅ 加载速度提升40%
- ✅ Lighthouse 75-80分
- ✅ 用户体验大幅改善
### 2. 完全自动化
- ✅ GitHub Actions自动运行
- ✅ 智能检测变更
- ✅ 无需手动干预
- ✅ 节省时间和精力
### 3. 智能优化
- ✅ 只在需要时优化
- ✅ 避免不必要的部署
- ✅ 节省资源和成本
- ✅ 保持系统高效
### 4. 完整文档
- ✅ 16份详细文档
- ✅ 覆盖所有场景
- ✅ 故障排除指南
- ✅ 最佳实践说明
---
## 📁 文档清单
### 核心文档（3份）
- ✅ 01-项目完成总结.md（本文件）
- ✅ 02-方案1完成总结.md
- ✅ 03-三步优化完整指南.md
### 优化实施（4份）
- ✅ 04-JS按需加载优化.md
- ✅ 05-PJAX适配说明.md
- ✅ 06-PJAX修复总结.md
- ✅ 07-字体子集化优化.md
### 自动化（3份）
- ✅ 08-GitHub-Actions使用指南.md
- ✅ 09-Actions修复指南.md
- ✅ 10-提交指南.md
### 测试验证（2份）
- ✅ 11-JS优化测试指南.md
- ✅ 12-字体优化测试指南.md
### 详细方案（4份）
- ✅ 13-主题全面优化分析.md
- ✅ 14-JS优化最终方案.md
- ✅ 15-字体优化手动指南.md
- ✅ 16-实施总结报告.md
---
## 💡 后续使用
### 日常开发
```bash
# 发布新文章
git add content/posts/new-article.md
git commit -m "feat: new article"
git push origin main
# 等待自动化（3-10分钟）
# - deploy.yml：部署文章
# - subset-fonts.yml：优化字体（如果需要）
# - deploy.yml：部署新字体（如果需要）
```
### 监控系统
```bash
# 查看GitHub Actions
https://github.com/zqlit/blog/actions
# 查看工作流状态
- Deploy to Production（部署）
- Font Subset Optimization（字体优化）
```
### 性能测试
```bash
# 每月测试一次
# 使用Chrome DevTools的Lighthouse
# 或者：https://pagespeed.web.dev/
# 记录：Performance、FCP、LCP、TTI
```
---
## 🎓 学到了什么？
### 技术技能
- ✅ JavaScript代码拆分
- ✅ 字体子集化技术
- ✅ GitHub Actions工作流
- ✅ Hugo静态站点优化
### DevOps实践
- ✅ CI/CD流程设计
- ✅ 自动化部署
- ✅ 工作流协调
- ✅ 性能监控
---
## 🏆 成就解锁
- ⚡ **性能优化大师** - 资源减少50%
- 🤖 **自动化专家** - 完整CI/CD流程
- 🚀 **前端优化师** - Lighthouse 75-80分
- 💡 **DevOps工程师** - GitHub Actions精通
---
## 🎊 项目完成
**恭喜你完成了完整的Hugo博客性能优化和自动化系统！**
- ✅ 性能提升50%
- ✅ 加载速度提升40%
- ✅ Lighthouse 75-80分
- ✅ 完全自动化
- ✅ 生产就绪
**现在可以专注于创作优质内容了！** 🚀
---
**项目完成时间：** 2026-06-03
**总耗时：** 约6小时
**优化效果：** 性能提升50%
**自动化程度：** 100%
**维护成本：** 0（完全自动化）
**祝你博客越办越好！** 🎉
docs/archive/主题与内容/性能优化（历史）/02-方案1完成总结.md
+364
View File
@@ -0,0 +1,364 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 02-方案1完成总结
**创建日期：** 2026-06-03
**版本：** v1.0
**状态：** ✅ 已完成
**方案：** 保守优化（JS + 字体，不改变CSS加载方式）
---
## 📋 方案概述
### 为什么选择方案1（保守优化）？
**原因：**
1. ✅ 零风险，不会破坏现有功能
2. ✅ 快速实施（3-4小时）
3. ✅ 仍然获得显著性能提升
4. ✅ 样式完全不变
**对比方案2（激进优化）：**
- 方案2包括CSS内联优化
- 需要100%提取所有CSS，风险高
- 可能遗漏某些样式
- 维护成本高
---
## ✅ 已完成的优化
### 第1步：JS按需加载优化
**完成时间：** 2026-06-03
**优化效果：**
- 首页JS：800KB → 350KB（⚡ -56%）
- 文章页JS：800KB → 450KB（⚡ -44%）
**主要工作：**
- ✅ JS代码拆分为4个bundle
- ✅ 核心JS始终加载（~200KB）
- ✅ 页面特定JS按需加载（~180KB）
- ✅ 非关键JS延迟加载（~25KB）
- ✅ PJAX完美适配
**修改文件：**
- `themes/Ying/layouts/partials/footer.html`
- `themes/Ying/assets/js/modules/mypjax.js`
---
### 第2步：字体子集化优化
**完成时间：** 2026-06-03
**优化效果：**
- 字体大小：1.2MB → 757KB（⚡ -37%）
**主要工作：**
- ✅ 使用Python fonttools提取字符
- ✅ 生成子集字体（2,485个字符）
- ✅ 更新CSS字体声明
- ✅ 保持所有字符正常显示
**修改文件：**
- `themes/Ying/assets/css/main.css`
- `themes/Ying/static/font/zql-v2-subset.woff2`
- `themes/Ying/static/font/zql-v2-subset.woff`
- `themes/Ying/static/font/used_chars.txt`
---
## 📊 优化效果
### 性能提升数据
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **JS（首页）** | 800KB | 350KB | ⚡ -56% |
| **JS（文章页）** | 800KB | 450KB | ⚡ -44% |
| **字体** | 1.2MB | 757KB | ⚡ -37% |
| **总体资源（首页）** | ~3MB | ~1.5MB | ⚡ -50% |
| **总体资源（文章页）** | ~3MB | ~1.6MB | ⚡ -47% |
| **FCP** | 2.5s | ~1.5s | ⚡ -40% |
| **TTI** | 4.0s | ~2.0s | ⚡ -50% |
| **TBT** | 350ms | ~100ms | ⚡ -71% |
| **Lighthouse** | 60 | 75-80 | ⚡ +25-33% |
---
## 🔧 技术实现
### JS优化策略
**核心JS（始终加载）：**
- UIkit框架
- 图标字体
- 图片灯箱
- 工具函数
- 搜索功能
- 浮动工具
- 进度条
- PJAX
- 主题主逻辑
**页面特定JS（按需加载）：**
- Artalk评论系统（文章详情页）
- 段落评论（文章详情页）
- 打赏功能（文章详情页）
**延迟加载的JS：**
- Toast消息
- 图片懒加载
---
### 字体优化策略
**方法：** Python fonttools
**步骤：**
1. 构建Hugo站点
2. 扫描所有HTML和CSS文件
3. 提取实际使用的字符
4. 生成子集字体
5. 更新CSS字体声明
**结果：**
- 提取了2,485个字符
- 字体大小减少37%
- 保持所有字符正常显示
---
## ✅ 测试验证
### 功能测试
- ✅ 首页功能正常
- ✅ 文章详情页正常
- ✅ 评论区正常加载
- ✅ 打赏功能正常
- ✅ 深色模式正常
- ✅ 响应式布局正常
### 性能测试
- ✅ Network面板显示JS大小减少
- ✅ Network面板显示字体大小减少
- ✅ Lighthouse得分提升
- ✅ 无Console错误
---
## 💡 优势和劣势
### 优势 ✅
1. **零风险** - 不会破坏现有功能
2. **快速实施** - 3-4小时完成
3. **显著提升** - 性能提升50%
4. **样式不变** - CSS保持不变
5. **易于维护** - 代码结构清晰
### 劣势 ⚠️
1. **CSS未优化** - 仍有优化空间
2. **字体优化有限** - 只减少37%（预期87%）
3. **需要Python** - 字体优化依赖Python环境
---
## 🔄 与方案2对比
### 方案1（保守优化）✅ 已选择
**优化内容：**
- JS按需加载
- 字体子集化
- 保持CSS不变
**预期效果：**
- 性能提升40-50%
- Lighthouse 75-80分
**风险：** 低
**实施时间：** 3-4小时
---
### 方案2（激进优化）❌ 未选择
**优化内容：**
- CSS内联优化
- JS按需加载
- 字体子集化
**预期效果：**
- 性能提升60-70%
- Lighthouse 90+分
**风险：** 高
**实施时间：** 8-10小时
---
## 🎯 为什么方案1更好？
### 对于你的场景
1. **零风险** - 生产环境最重要
2. **快速见效** - 立即享受性能提升
3. **保持稳定** - 所有功能正常
4. **易于维护** - 代码结构清晰
5. **成本低** - 无需大量测试
### 如果选择方案2
**可能出现的问题：**
- CSS内联不完整，导致样式丢失
- 需要大量测试验证
- 维护成本高
- 风险大
---
## 📁 修改的文件清单
### 1. JS优化
**修改文件：**
- `themes/Ying/layouts/partials/footer.html`（JS拆分）
- `themes/Ying/assets/js/modules/mypjax.js`（PJAX适配）
**创建文件：**
- 无（使用Hugo资源管道）
---
### 2. 字体优化
**修改文件：**
- `themes/Ying/assets/css/main.css`（字体声明）
**创建文件：**
- `themes/Ying/static/font/zql-v2-subset.woff2`（子集字体）
- `themes/Ying/static/font/zql-v2-subset.woff`（子集字体）
- `themes/Ying/static/font/used_chars.txt`（字符列表）
---
## 🧪 测试清单
### JS优化测试
- [ ] 首页正常显示
- [ ] 导航菜单正常
- [ ] 搜索功能正常
- [ ] 主题切换正常
- [ ] 文章详情页正常
- [ ] 评论区正常加载
- [ ] 打赏功能正常
- [ ] PJAX导航正常
- [ ] 无限滚动正常（如果启用）
### 字体优化测试
- [ ] 中文字符正常
- [ ] 英文字符正常
- [ ] 数字正常
- [ ] 标点符号正常
- [ ] 深色模式正常
- [ ] 移动端正常
### 性能测试
- [ ] Network面板显示JS大小减少
- [ ] Network面板显示字体大小减少
- [ ] Lighthouse得分提升
- [ ] 无Console错误
---
## 💡 使用建议
### 日常开发
```bash
# 发布新文章
git add content/posts/new-article.md
git commit -m "feat: new article"
git push origin main
# 等待自动化（3-10分钟）
# - deploy.yml：部署文章
# - subset-fonts.yml：优化字体（如果需要）
# - deploy.yml：部署新字体（如果需要）
```
### 监控系统
```bash
# 查看GitHub Actions
https://github.com/zqlit/blog/actions
# 查看工作流状态
- Deploy to Production（部署）
- Font Subset Optimization（字体优化）
```
---
## 🔄 后续优化
### 如果需要进一步优化
**选项1：实施CSS内联（方案2的一部分）**
- 风险：高
- 收益：额外提升20-30%
- 建议：谨慎考虑
**选项2：优化字体子集化**
- 使用更大的字符集
- 或者使用系统字体
- 建议：当前方案已足够
**选项3：其他优化**
- 图片优化
- CDN配置
- 缓存策略
- 建议：按需实施
---
## 🎉 项目完成
### 完成情况
- ✅ JS按需加载优化（-56%首页，-44%文章页）
- ✅ 字体子集化优化（-37%）
- ✅ 总体性能提升50%
- ✅ Lighthouse 75-80分
- ✅ 完全自动化
### 下一步
**什么都不用做！** 🚀
- ✅ 系统已经自动化运行
- ✅ 发布新文章时自动优化
- ✅ 享受性能提升
- ✅ 专注于内容创作
---
**方案1完成时间：** 2026-06-03
**总耗时：** 约4小时
**优化效果：** 性能提升50%
**风险等级：** 低（零风险）
**维护成本：** 0（完全自动化）
**方案1是最优选择！** 🎉
docs/archive/主题与内容/性能优化（历史）/03-三步优化完整指南.md
+602
View File
@@ -0,0 +1,602 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 03-三步优化完整指南
**创建日期：** 2026-06-03
**版本：** v1.0
**状态：** ✅ 已完成
**适用对象：** Hugo主题Ying性能优化
---
## 📋 概述
### 三步优化内容
1. **JS按需加载优化** - 减少56%首页JS
2. **字体子集化优化** - 减少37%字体大小
3. **GitHub Actions自动化** - 100%自动化
### 预期效果
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **总体资源** | ~3MB | ~1.5MB | ⚡ -50% |
| **加载速度** | 慢 | 快 | ⚡ +40% |
| **Lighthouse** | 60 | 75-80 | ⚡ +33% |
---
## 🚀 第1步：JS按需加载优化
### 1.1 优化目标
将JS拆分为多个bundle，实现按需加载：
- 核心JS始终加载
- 页面特定JS按需加载
- 非关键JS延迟加载
### 1.2 实施步骤
#### 步骤1：分析JS结构
**核心JS（必须加载）：**
- UIkit框架
- 图标字体
- 图片灯箱
- 工具函数
- 搜索功能
- 浮动工具
- 进度条
- PJAX
- 主题主逻辑
**页面特定JS（按需加载）：**
- Artalk评论系统（文章详情页）
- 段落评论（文章详情页）
- 打赏功能（文章详情页）
**延迟加载的JS：**
- Toast消息
- 图片懒加载
---
#### 步骤2：修改footer.html
**文件：** `themes/Ying/layouts/partials/footer.html`
**修改内容：**
1. 创建核心JS bundle
```gohtml
{{ $coreScripts := slice $iconfont $uikit $viewimage $utils $loader $cache $search $floatingTools $nprogress $pjaxLib $mypjax $pangu $linkify $main | resources.Concat "js/core.js" | resources.Minify | resources.Fingerprint }}
<script defer src="{{ $coreScripts.RelPermalink }}"></script>
```
2. 创建页面特定JS bundle
```gohtml
{{ if .IsPage }}
{{ $artalkModule := resources.Get "js/modules/artalk.js" }}
{{ $paragraphComments := resources.Get "js/modules/paragraph-comments.js" }}
{{ $reward := resources.Get "js/modules/reward.js" }}
{{ $pageScripts := slice $artalkModule $paragraphComments $reward | resources.Concat "js/page-only.js" | resources.Minify | resources.Fingerprint }}
<script defer src="{{ $pageScripts.RelPermalink }}"></script>
<script>window._pageOnlyScriptUrl = '{{ $pageScripts.RelPermalink }}';</script>
{{ end }}
```
3. 创建延迟加载JS bundle
```gohtml
{{ $toast := resources.Get "js/modules/toast.js" }}
{{ $easylazyload := resources.Get "js/modules/lazyload.js" }}
{{ $deferredScripts := slice $toast $easylazyload | resources.Concat "js/deferred.js" | resources.Minify | resources.Fingerprint }}
<script>
if ('requestIdleCallback' in window) {
requestIdleCallback(function() {
var script = document.createElement('script');
script.src = '{{ $deferredScripts.RelPermalink }}';
script.defer = true;
document.body.appendChild(script);
});
} else {
setTimeout(function() {
var script = document.createElement('script');
script.src = '{{ $deferredScripts.RelPermalink }}';
script.defer = true;
document.body.appendChild(script);
}, 1000);
}
</script>
```
---
#### 步骤3：适配PJAX
**文件：** `themes/Ying/assets/js/modules/mypjax.js`
**修改内容：**
在 `pjax:complete` 事件中添加动态加载逻辑：
```javascript
// 动态加载页面特定JS（PJAX适配）
var isArticlePage = document.querySelector('#Comments') !== null ||
document.querySelector('.post-content') !== null;
if (isArticlePage && !window._pageOnlyLoaded && window._pageOnlyScriptUrl) {
var script = document.createElement('script');
script.src = window._pageOnlyScriptUrl;
script.onload = function() {
window._pageOnlyLoaded = true;
console.log('page-only.js loaded for PJAX navigation');
if (typeof window.initArtalk === 'function') {
try { window.initArtalk(); } catch(e) {}
}
};
document.body.appendChild(script);
}
```
---
### 1.3 预期效果
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **首页JS** | 800KB | 350KB | ⚡ -56% |
| **文章页JS** | 800KB | 450KB | ⚡ -44% |
| **TTI** | 4.0s | ~2.0s | ⚡ -50% |
| **TBT** | 350ms | ~100ms | ⚡ -71% |
---
### 1.4 测试验证
**功能测试：**
- [ ] 首页功能正常
- [ ] 文章详情页正常
- [ ] 评论区正常加载
- [ ] PJAX导航正常
- [ ] 打赏功能正常
**性能测试：**
- [ ] Network面板显示JS大小减少
- [ ] Lighthouse得分提升
- [ ] 无Console错误
---
## 🚀 第2步：字体子集化优化
### 2.1 优化目标
将中文字体从1.2MB优化到757KB，减少37%。
### 2.2 实施步骤
#### 步骤1：备份原始字体
```bash
cd E:\GitHub\blog
# Windows
copy themes\Ying\static\font\zql-v2.woff2 themes\Ying\static\font\zql-v2.woff2.backup
copy themes\Ying\static\font\zql-v2.woff themes\Ying\static\font\zql-v2.woff.backup
# Mac/Linux
cp themes/Ying/static/font/zql-v2.woff2 themes/Ying/static/font/zql-v2.woff2.backup
cp themes/Ying/static/font/zql-v2.woff themes/Ying/static/font/zql-v2.woff.backup
```
---
#### 步骤2：安装Python依赖
```bash
pip install fonttools brotli
```
---
#### 步骤3：构建Hugo站点
```bash
hugo --destination=public
```
---
#### 步骤4：运行字体子集化
```bash
python scripts/subset-font-safe.py
```
**预期输出：**
```
🔤 字体子集化工具（安全版本）
==================================================
✅ 找到public目录，将扫描构建后的HTML
🔍 扫描目录: content, layouts, public
📝 提取了 2492 个唯一字符
💾 字符列表已保存到: themes/Ying/static/font\used_chars.txt
✂️ 正在生成子集字体...
✅ 子集化完成！
📊 优化结果:
子集字符数: 2485
子集文件大小: 739.7 KB
减少: 486.8 KB (39.7%)
🎉 所有子集字体生成成功！
```
---
#### 步骤5：更新CSS字体声明
**文件：** `themes/Ying/assets/css/main.css`
**修改字体声明：**
```css
@font-face {
font-family: 'zql';
src: url('../font/zql-v2-subset.woff2') format('woff2'),
url('../font/zql-v2-subset.woff') format('woff');
font-display: swap;
}
```
**关键改动：**
- `zql-v2.woff2` → `zql-v2-subset.woff2`
- `zql-v2.woff` → `zql-v2-subset.woff`
- 删除 `unicode-range`
---
### 2.3 预期效果
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **字体大小** | 1.2MB | 757KB | ⚡ -37% |
| **字符数** | 20,000+ | 2,485 | - |
| **字体加载时间** | ~6s | ~4s | ⚡ -33% |
---
### 2.4 测试验证
**功能测试：**
- [ ] 中文字符正常
- [ ] 英文字符正常
- [ ] 数字正常
- [ ] 标点符号正常
- [ ] 深色模式正常
**性能测试：**
- [ ] Network面板显示字体大小减少
- [ ] 无404错误
- [ ] Lighthouse无字体警告
---
## 🚀 第3步：GitHub Actions自动化
### 3.1 优化目标
实现字体子集化的完全自动化：
- 内容更新时自动优化
- 每周定期检查
- 智能检测变更
- 与deploy.yml完美协调
### 3.2 实施步骤
#### 步骤1：创建requirements.txt
**文件：** `requirements.txt`
```
fonttools
brotli
```
---
#### 步骤2：创建GitHub Actions工作流
**文件：** `.github/workflows/subset-fonts.yml`
**关键配置：**
1. **触发条件：**
```yaml
on:
push:
branches:
- main
paths:
- 'content/**'
- 'layouts/**'
schedule:
- cron: '0 2 * * 1' # 每周一凌晨2点
workflow_dispatch:
inputs:
force_rebuild:
description: '强制重新生成子集字体'
required: false
default: 'false'
type: boolean
```
2. **工作流步骤：**
```yaml
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
cache: 'pip'
- name: Install dependencies
run: |
pip install fonttools brotli
- name: Build Hugo site
uses: peaceiris/actions-hugo@v2
with:
hugo-version: 'latest'
extended: true
- name: Subset fonts
run: python scripts/subset-font-safe.py
- name: Commit changes
run: |
git config --local user.email "github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"
git add themes/Ying/static/font/zql-v2-subset.*
git commit -m "chore: update font subset (automated) [skip ci]"
- name: Push changes
run: git push origin main
```
3. **避免循环触发：**
```yaml
git commit -m "chore: update font subset (automated) [skip ci]"
```
---
#### 步骤3：与deploy.yml协调
**你的deploy.yml已有防循环机制：**
```yaml
- name: Push Image Optimizations
run: |
if ! git log --oneline -1 | grep -q "\[skip ci\]"; then
echo "No auto-commits to push"
else
git push origin HEAD:main
fi
```
**协调流程：**
```
你push到main
↓
deploy.yml（部署文章）
↓
subset-fonts.yml（优化字体）
↓
commit [skip ci]
↓
push到main
↓
deploy.yml看到[skip ci]，不再次触发 ✅
↓
完美协调！
```
---
### 3.3 预期效果
**自动化程度：** 100%
**触发条件：**
- ✅ 内容更新时自动优化
- ✅ 每周定期检查
- ✅ 手动触发支持
**协调机制：**
- ✅ 与deploy.yml完美协调
- ✅ 无循环触发
- ✅ 智能检测变更
---
### 3.4 测试验证
**功能测试：**
- [ ] GitHub Actions正常运行
- [ ] 字体优化成功
- [ ] 自动commit和push
- [ ] 与deploy.yml协调正常
**自动化测试：**
- [ ] 发布新文章时触发
- [ ] 每周定时触发
- [ ] 手动触发成功
---
## 📊 完整优化效果
### 性能提升总结
| 优化步骤 | 优化内容 | 提升 |
|---------|---------|------|
| **第1步** | JS按需加载 | ⚡ -56%（首页） |
| **第2步** | 字体子集化 | ⚡ -37% |
| **第3步** | 自动化 | ⚡ 100%自动化 |
| **总计** | 性能优化 | ⚡ -50%（总体） |
### Lighthouse得分
- **优化前：** 60分
- **优化后：** 75-80分
- **提升：** +25-33%
---
## 🎯 实施时间表
### 第1天：JS优化（2小时）
**上午：**
- 分析JS结构
- 修改footer.html
- 测试功能
**下午：**
- 适配PJAX
- 性能测试
- 提交代码
---
### 第2天：字体优化（1.5小时）
**上午：**
- 备份字体
- 安装Python依赖
- 运行子集化
**下午：**
- 更新CSS
- 测试字体显示
- 提交代码
---
### 第3天：自动化（1小时）
**上午：**
- 创建requirements.txt
- 创建GitHub Actions工作流
- 测试自动化
**下午：**
- 验证与deploy.yml协调
- 提交代码
- 监控Actions运行
---
## 💡 最佳实践
### 1. 逐步实施
- ✅ 先实施JS优化
- ✅ 验证无问题后实施字体优化
- ✅ 最后配置自动化
- ✅ 每个步骤都测试验证
### 2. 充分测试
- ✅ 功能测试（所有页面）
- ✅ 性能测试（Lighthouse）
- ✅ 兼容性测试（多浏览器）
- ✅ 自动化测试（GitHub Actions）
### 3. 文档记录
- ✅ 记录所有修改
- ✅ 记录测试结果
- ✅ 记录问题和解决方案
- ✅ 创建故障排除指南
---
## 🔄 回滚方案
### 如果JS优化失败
```bash
# 恢复footer.html
git checkout themes/Ying/layouts/partials/footer.html
# 恢复mypjax.js
git checkout themes/Ying/assets/js/modules/mypjax.js
# 重新构建
hugo --cleanDestinationDir
```
### 如果字体优化失败
```bash
# 恢复字体文件
cp themes/Ying/static/font/zql-v2.woff2.backup themes/Ying/static/font/zql-v2.woff2
cp themes/Ying/static/font/zql-v2.woff.backup themes/Ying/static/font/zql-v2.woff
# 恢复CSS
git checkout themes/Ying/assets/css/main.css
# 重新构建
hugo --cleanDestinationDir
```
### 如果自动化失败
```bash
# 删除工作流文件
rm .github/workflows/subset-fonts.yml
# 或者禁用工作流
# 在GitHub仓库设置中禁用Actions
```
---
## 🎉 项目完成
### 完成情况
- ✅ 第1步：JS按需加载优化（-56%首页）
- ✅ 第2步：字体子集化优化（-37%）
- ✅ 第3步：GitHub Actions自动化（100%）
- ✅ 总体性能提升50%
- ✅ Lighthouse 75-80分
### 后续使用
**什么都不用做！** 🚀
- ✅ 系统已经自动化运行
- ✅ 发布新文章时自动优化
- ✅ 享受性能提升
- ✅ 专注于内容创作
---
**三步优化完成时间：** 2026-06-03
**总耗时：** 约4.5小时
**优化效果：** 性能提升50%
**自动化程度：** 100%
**维护成本：** 0（完全自动化）
**祝你博客越办越好！** 🎉
docs/archive/主题与内容/性能优化（历史）/04-JS按需加载优化.md
+559
View File
@@ -0,0 +1,559 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 04-JS按需加载优化
**创建日期：** 2026-06-03
**版本：** v1.0
**状态：** ✅ 已完成
**优化效果：** 首页JS减少56%，文章页JS减少44%
---
## 📋 优化概述
### 优化目标
将所有JS打包为单个bundle（800KB）拆分为多个bundle，实现按需加载：
- 核心JS始终加载（~200KB）
- 页面特定JS按需加载（~180KB）
- 非关键JS延迟加载（~25KB）
### 优化效果
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **首页JS** | 800KB | 350KB | ⚡ -56% |
| **文章页JS** | 800KB | 450KB | ⚡ -44% |
| **TTI** | 4.0s | ~2.0s | ⚡ -50% |
| **TBT** | 350ms | ~100ms | ⚡ -71% |
---
## 🔍 JS文件分析
### 原始JS结构（优化前）
所有JS打包为单个bundle.js（800KB）：
```
bundle.js (800KB)
├── iconfont.js
├── uikit.min.js
├── view-image.min.js
├── utils.js
├── loader.js
├── cache.js
├── search.js
├── floating-tools.js
├── paragraph-comments.js
├── infinite-scroll.js
├── artalk.js
├── nprogress.js
├── pjax.js
├── pangu.js
├── linkify.js
├── main.js
├── mypjax.js
├── toast.js
├── tiaozhuan.js
├── reward.js
└── lazyload.js
```
**问题：**
- 所有页面都加载所有JS
- 首页不需要Artalk评论
- 文章页不需要无限滚动
- 浪费带宽和加载时间
---
### 优化后JS结构
拆分为4个bundle：
```
1. core.js (200KB) - 始终加载
├── iconfont.js
├── uikit.min.js
├── view-image.min.js
├── utils.js
├── loader.js
├── cache.js
├── search.js
├── floating-tools.js
├── nprogress.js
├── pjax.js
├── mypjax.js
├── pangu.js
├── linkify.js
└── main.js
2. page-only.js (180KB) - 文章详情页
├── artalk.js
├── paragraph-comments.js
└── reward.js
3. deferred.js (25KB) - 延迟加载
├── toast.js
└── lazyload.js
4. infinite-scroll.js (20KB) - 首页（如果启用）
5. tiaozhuan.js (8KB) - 特定页面
```
---
## 🛠️ 实施步骤
### 步骤1：修改footer.html
**文件：** `themes/Ying/layouts/partials/footer.html`
**修改内容：**
#### 1. 创建核心JS bundle
```gohtml
{{/* ====== 1. 核心JS Bundle - 始终加载 ====== */}}
{{ $iconfont := resources.Get "js/libs/iconfont.js" }}
{{ $uikit := resources.Get "js/libs/uikit.min.js" }}
{{ $viewimage := resources.Get "js/libs/view-image.min.js" }}
{{ $utils := resources.Get "js/modules/utils.js" }}
{{ $loader := resources.Get "js/modules/loader.js" }}
{{ $cache := resources.Get "js/modules/cache.js" }}
{{ $search := resources.Get "js/modules/search.js" }}
{{ $floatingTools := resources.Get "js/modules/floating-tools.js" }}
{{ $nprogress := resources.Get "js/libs/nprogress.js" }}
{{ $pjaxLib := resources.Get "js/libs/pjax.js" }}
{{ $mypjax := resources.Get "js/modules/mypjax.js" }}
{{ $pangu := resources.Get "js/modules/pangu.js" }}
{{ $linkify := resources.Get "js/modules/linkify.js" }}
{{ $main := resources.Get "js/main.js" }}
{{ $coreScripts := slice $iconfont $uikit $viewimage $utils $loader $cache $search $floatingTools $nprogress $pjaxLib $mypjax $pangu $linkify $main | resources.Concat "js/core.js" | resources.Minify | resources.Fingerprint }}
<script defer src="{{ $coreScripts.RelPermalink }}"></script>
```
---
#### 2. 创建页面特定JS bundle
```gohtml
{{/* ====== 4. 页面特定JS - 按需加载 ====== */}}
{{/* 文章详情页专用JS */}}
{{ if .IsPage }}
{{ $artalkModule := resources.Get "js/modules/artalk.js" }}
{{ $paragraphComments := resources.Get "js/modules/paragraph-comments.js" }}
{{ $reward := resources.Get "js/modules/reward.js" }}
{{ $pageScripts := slice $artalkModule $paragraphComments $reward | resources.Concat "js/page-only.js" | resources.Minify | resources.Fingerprint }}
<script defer src="{{ $pageScripts.RelPermalink }}"></script>
<script>window._pageOnlyScriptUrl = '{{ $pageScripts.RelPermalink }}';</script>
{{ else }}
{{/* 非文章页面：只存储URL，不加载 */}}
{{ $artalkModule := resources.Get "js/modules/artalk.js" }}
{{ $paragraphComments := resources.Get "js/modules/paragraph-comments.js" }}
{{ $reward := resources.Get "js/modules/reward.js" }}
{{ $pageScripts := slice $artalkModule $paragraphComments $reward | resources.Concat "js/page-only.js" | resources.Minify | resources.Fingerprint }}
<script>window._pageOnlyScriptUrl = '{{ $pageScripts.RelPermalink }}';</script>
{{ end }}
```
---
#### 3. 创建延迟加载JS bundle
```gohtml
{{/* ====== 5. 延迟加载的非关键JS ====== */}}
{{ $toast := resources.Get "js/modules/toast.js" }}
{{ $easylazyload := resources.Get "js/modules/lazyload.js" }}
{{ $deferredScripts := slice $toast $easylazyload | resources.Concat "js/deferred.js" | resources.Minify | resources.Fingerprint }}
<script>
// 使用requestIdleCallback在浏览器空闲时加载
if ('requestIdleCallback' in window) {
requestIdleCallback(function() {
var script = document.createElement('script');
script.src = '{{ $deferredScripts.RelPermalink }}';
script.defer = true;
document.body.appendChild(script);
});
} else {
setTimeout(function() {
var script = document.createElement('script');
script.src = '{{ $deferredScripts.RelPermalink }}';
script.defer = true;
document.body.appendChild(script);
}, 1000);
}
</script>
```
---
#### 4. 首页专用JS
```gohtml
{{/* ====== 6. 首页专用JS ====== */}}
{{ if .IsHome }}
{{ if .Site.Params.infiniteScroll.enable }}
{{ $infiniteScroll := resources.Get "js/modules/infinite-scroll.js" }}
<script defer src="{{ $infiniteScroll.RelPermalink }}"></script>
{{ end }}
{{ end }}
```
---
#### 5. 特定页面专用JS
```gohtml
{{/* ====== 7. 特定页面专用JS ====== */}}
{{ if or (eq .Type "links") (eq .Type "circles") }}
{{ $tiaozhuan := resources.Get "js/modules/tiaozhuan.js" }}
<script defer src="{{ $tiaozhuan.RelPermalink }}"></script>
{{ end }}
```
---
### 步骤2：适配PJAX
**文件：** `themes/Ying/assets/js/modules/mypjax.js`
**修改内容：**
在 `pjax:complete` 事件中添加动态加载逻辑：
```javascript
// pjax加载完成
document.addEventListener("pjax:complete", function () {
// 立即执行：进度条、基础 UI
if (typeof NProgress !== 'undefined') NProgress.done();
pjax_reload();
// 动态加载页面特定JS（PJAX适配）
// 检测当前页面是否为文章详情页，如果是则加载page-only.js
var currentPath = window.location.pathname;
var isArticlePage = document.querySelector('#Comments') !== null ||
document.querySelector('.post-content') !== null;
if (isArticlePage && !window._pageOnlyLoaded && window._pageOnlyScriptUrl) {
// 动态加载page-only.js（使用Hugo fingerprint后的正确URL）
var script = document.createElement('script');
script.src = window._pageOnlyScriptUrl;
script.onload = function() {
window._pageOnlyLoaded = true;
console.log('page-only.js loaded for PJAX navigation');
// 初始化Artalk等
if (typeof window.initArtalk === 'function') {
try { window.initArtalk(); } catch(e) { console.error('initArtalk error:', e); }
}
if (typeof window.initParagraphComments === 'function') {
try { window.initParagraphComments(); } catch(e) {}
}
};
document.body.appendChild(script);
}
// 下一帧执行：轻量初始化
requestAnimationFrame(function() {
if (typeof initCodeCopy === 'function') initCodeCopy();
if (typeof window.initSearch === 'function') {
try { window.initSearch(); } catch(e) {}
}
if (typeof window.refreshFloatingTools === 'function') {
window.refreshFloatingTools();
} else if (typeof window.initFloatingTools === 'function') {
try { window.initFloatingTools(); } catch(e) {}
}
// 文章动画
if (typeof window.initPostScrollspy === 'function') window.initPostScrollspy();
});
// 空闲时执行：非关键功能
var idle = window.requestIdleCallback || function(fn) { return setTimeout(fn, 200); };
idle(function() {
if (typeof window.initParagraphComments === 'function') {
try { window.initParagraphComments(); } catch(e) {}
}
if (typeof window.initInfiniteScroll === 'function' && window.enableInfiniteScroll) {
window.initInfiniteScroll();
}
if (typeof window.initLinkStatus === 'function') {
try { window.initLinkStatus(); } catch(e) {}
}
if (typeof window.initArtalk === 'function') {
try { window.initArtalk(); } catch(e) {}
}
if (typeof window.bsz_fetch === 'function') {
try { window.bsz_fetch(); } catch(e) {}
}
if (typeof window.initImageFrameReveal === 'function') {
try { window.initImageFrameReveal(); } catch(e) {}
}
// 链接卡片和中英文间距（DOM 扫描，非关键）
if (typeof window.initLinkify === 'function') window.initLinkify();
if (typeof window.initPangu === 'function') window.initPangu();
});
// 延迟：代码折叠
setTimeout(function() {
if (typeof window.initCodeFold === 'function') window.initCodeFold();
}, 300);
});
```
---
## 📊 加载时序
### 优化前
```
页面加载
↓
下载bundle.js (800KB)
↓
执行所有JS
↓
渲染页面
↓
用户可以交互
```
**问题：** 所有JS都在首屏加载，阻塞渲染
---
### 优化后
```
页面加载
↓
下载core.js (200KB) - 立即
↓
渲染页面（核心功能可用）
↓
用户可以交互
↓
下载page-only.js (180KB) - 按需（仅文章页）
↓
下载deferred.js (25KB) - 延迟（浏览器空闲）
↓
所有功能可用
```
**优势：**
- ✅ 首屏渲染更快
- ✅ 核心功能立即可用
- ✅ 非核心功能延迟加载
- ✅ 节省带宽
---
## 🧪 测试验证
### 功能测试清单
#### 首页功能
- [ ] 导航菜单正常
- [ ] 搜索功能正常
- [ ] 主题切换正常
- [ ] 文章列表显示正常
- [ ] 分页功能正常
- [ ] 无限滚动正常（如果启用）
- [ ] 浮动工具栏正常
#### 文章详情页功能
- [ ] 文章内容正常显示
- [ ] 图片灯箱正常
- [ ] 评论区正常加载（Artalk）
- [ ] 打赏功能正常
- [ ] 段落评论正常
- [ ] 返回顶部正常
#### 其他页面功能
- [ ] 友链页面正常
- [ ] circles页面正常
- [ ] 归档页面正常
- [ ] 搜索结果页正常
#### 跨页面功能
- [ ] PJAX导航正常
- [ ] 浏览器前进/后退正常
- [ ] 书签/分享链接正常
---
### 性能测试
#### Network面板
1. 打开DevTools → Network
2. 刷新页面
3. 检查：
- [ ] core.js首先加载（~200KB）
- [ ] page-only.js仅在文章页加载（~180KB）
- [ ] deferred.js最后加载（~25KB）
- [ ] 总体JS大小减少
#### Lighthouse测试
1. 打开DevTools → Lighthouse
2. 运行Performance审计
3. 预期指标：
- [ ] Performance得分：75-85
- [ ] TTI：改善20-30%
- [ ] TBT：改善40-50%
- [ ] Speed Index：改善20-30%
---
## 🐛 故障排除
### 问题1：评论区未加载
**症状：** 文章详情页看不到评论区
**可能原因：**
1. page-only.js加载失败
2. Artalk初始化时机不对
3. JavaScript错误
**解决方案：**
1. 打开Console查看错误
2. 检查Network面板，确认page-only.js加载成功
3. 确认window._pageOnlyScriptUrl已定义
---
### 问题2：功能延迟响应
**症状：** 点击某些按钮后1-2秒才响应
**原因：** 非关键JS还在加载
**解决方案：**
- 这是预期行为，用户可能会感觉到轻微延迟
- 如果延迟明显（>3秒），考虑将该模块移到core.js
---
### 问题3：无限滚动失效
**症状：** 首页无法加载更多文章
**可能原因：**
1. infinite-scroll.js未加载
2. window.enableInfiniteScroll未定义
**解决方案：**
1. 检查hugo.toml中infiniteScroll.enable是否为true
2. 查看Console是否有错误
3. 确认infinite-scroll.js加载成功
---
### 问题4：PJAX导航失效
**症状：** 点击链接后页面完全刷新
**可能原因：**
1. PJAX库未加载
2. mypjax.js初始化失败
**解决方案：**
1. 检查Console是否有错误
2. 确认pjax.js在core.js中
3. 检查mypjax.js的配置
---
## 🔄 回滚方案
### 如果优化后出现严重问题
**快速回滚：**
```bash
cd E:\GitHub\blog
# 恢复footer.html
git checkout themes/Ying/layouts/partials/footer.html
# 恢复mypjax.js
git checkout themes/Ying/assets/js/modules/mypjax.js
# 重新构建
hugo --cleanDestinationDir
hugo server -D
```
---
## 💡 最佳实践
### 1. 逐步优化
- ✅ 先测试核心功能
- ✅ 逐步添加按需加载
- ✅ 充分测试每个步骤
- ✅ 记录问题和解决方案
### 2. 监控性能
- ✅ 定期Lighthouse测试
- ✅ 监控网络请求
- ✅ 检查Console错误
- ✅ 记录性能数据
### 3. 持续改进
- ✅ 根据实际使用调整
- ✅ 优化加载时序
- ✅ 减少bundle大小
- ✅ 提升用户体验
---
## 📈 优化效果总结
### 性能提升
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **首页JS** | 800KB | 350KB | ⚡ -56% |
| **文章页JS** | 800KB | 450KB | ⚡ -44% |
| **TTI** | 4.0s | ~2.0s | ⚡ -50% |
| **TBT** | 350ms | ~100ms | ⚡ -71% |
### 用户体验提升
- 🚀 **首屏更快** - 资源减少56%
- ⚡ **交互更流畅** - TTI提升50%
- 📱 **移动端更好** - 节省带宽
- 🎨 **功能完整** - 所有功能正常
---
**JS优化完成时间：** 2026-06-03
**实施耗时：** 约2小时
**优化效果：** 首页JS减少56%
**风险等级：** 低
**维护成本：** 低
**JS优化效果显著！** 🎉
docs/archive/主题与内容/性能优化（历史）/05-PJAX适配说明.md
+330
View File
@@ -0,0 +1,330 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 05-PJAX适配说明
**创建日期：** 2026-06-03
**版本：** v1.0
**状态：** ✅ 已完成
**适用范围：** JS按需加载优化的PJAX适配
---
## 📋 问题背景
### PJAX是什么？
PJAX（PushState + AJAX）是一种页面无刷新加载技术：
- 通过AJAX加载新内容
- 更新浏览器地址栏
- 无需刷新整个页面
- 提升用户体验
### 问题场景
**优化前：**
```
用户访问首页 → bundle.js加载（800KB）
用户点击文章 → PJAX导航（无刷新）
进入文章详情页 → 评论区正常（因为所有JS已加载）
```
**优化后（有问题）：**
```
用户访问首页 → core.js加载（200KB）
用户点击文章 → PJAX导航（无刷新）
进入文章详情页 → 评论区不加载 ❌
→ page-only.js未加载 ❌
→ initArtalk未定义 ❌
```
**根本原因：**
- PJAX不重新加载JS文件
- page-only.js只在首次访问时加载
- PJAX导航时，JS已经加载过了，不会重新加载
---
## ✅ 解决方案
### 方案：动态加载 + 全局URL
**实现思路：**
1. **存储URL** - 在footer.html中存储page-only.js的URL到全局变量
2. **检测页面** - 在mypjax.js中检测当前页面是否为文章详情页
3. **动态加载** - 如果是且page-only.js未加载，动态创建script标签加载
4. **初始化功能** - 加载完成后自动初始化Artalk等功能
---
## 🛠️ 实施步骤
### 步骤1：修改footer.html
**修改内容：**
- 所有页面都计算page-only.js的URL
- 存储在window._pageOnlyScriptUrl全局变量中
- 文章页面直接加载，非文章页面只存储URL
**关键代码：**
```gohtml
{{ if .IsPage }}
{{/* 文章页面：加载page-only.js */}}
<script defer src="{{ $pageScripts.RelPermalink }}"></script>
<script>window._pageOnlyScriptUrl = '{{ $pageScripts.RelPermalink }}';</script>
{{ else }}
{{/* 非文章页面：只存储URL，不加载 */}}
<script>window._pageOnlyScriptUrl = '{{ $pageScripts.RelPermalink }}';</script>
{{ end }}
```
**作用：**
- 确保PJAX导航时能找到page-only.js的正确路径
- Hugo会自动添加fingerprint（如page-only.min.abc123.js）
---
### 步骤2：修改mypjax.js
**修改内容：**
- 在pjax:complete事件中添加动态加载逻辑
- 检测当前页面是否为文章详情页
- 如果是且page-only.js未加载，动态加载
- 设置window._pageOnlyLoaded标志防止重复加载
**关键代码：**
```javascript
// 动态加载页面特定JS（PJAX适配）
var isArticlePage = document.querySelector('#Comments') !== null ||
document.querySelector('.post-content') !== null;
if (isArticlePage && !window._pageOnlyLoaded && window._pageOnlyScriptUrl) {
var script = document.createElement('script');
script.src = window._pageOnlyScriptUrl;
script.onload = function() {
window._pageOnlyLoaded = true;
console.log('page-only.js loaded for PJAX navigation');
if (typeof window.initArtalk === 'function') {
try { window.initArtalk(); } catch(e) {}
}
if (typeof window.initParagraphComments === 'function') {
try { window.initParagraphComments(); } catch(e) {}
}
};
document.body.appendChild(script);
}
```
**作用：**
- 当PJAX导航到文章页时，自动加载page-only.js
- 初始化Artalk评论、段落评论、打赏功能
- 确保用户体验无缝
---
## 🧪 测试验证
### 测试场景
#### 场景1：首页 → 文章详情页
**步骤：**
1. 访问首页
2. 点击文章链接
3. 检查文章详情页
**预期结果：**
- ✅ PJAX导航成功（地址栏更新，无刷新）
- ✅ 文章内容正常显示
- ✅ 评论区正常加载
- ✅ Console显示：`page-only.js loaded for PJAX navigation`
---
#### 场景2：文章 → 另一篇文章
**步骤：**
1. 在文章详情页
2. 点击"下一篇"或其他文章
3. 检查新文章页
**预期结果：**
- ✅ PJAX导航成功
- ✅ 新文章内容正常
- ✅ 评论区正常（无需重新加载page-only.js）
---
#### 场景3：文章 → 首页
**步骤：**
1. 在文章详情页
2. 点击导航栏"首页"
3. 检查首页
**预期结果：**
- ✅ PJAX导航成功
- ✅ 首页内容正常
- ✅ 无Console错误
---
### Console日志检查
**正常情况应该看到：**
**访问首页时：**
```
Pjax initialized: {...}
（无page-only.js相关日志）
```
**PJAX导航到文章详情页时：**
```
Pjax reload triggered
page-only.js loaded for PJAX navigation
```
---
## 💡 技术细节
### 为什么需要全局URL？
**问题：** Hugo构建时会自动添加fingerprint
**示例：**
```
原始：page-only.js
构建后：page-only.min.abc123.js
```
**解决：** 使用全局变量存储正确的URL
```javascript
window._pageOnlyScriptUrl = '/js/page-only.min.abc123.js';
```
---
### 如何防止重复加载？
**使用标志位：**
```javascript
// 检查是否已加载
if (!window._pageOnlyLoaded) {
// 加载page-only.js
// ...
window._pageOnlyLoaded = true;
}
```
---
### 错误处理
**如果page-only.js加载失败：**
```javascript
script.onerror = function() {
console.error('Failed to load page-only.js');
// 可以尝试重新加载或显示错误提示
};
```
---
## 📊 性能影响
### 首次加载（首页）
- ✅ page-only.js不加载（节省~180KB）
- ✅ 首页加载更快
### PJAX导航到文章详情页
- ⚠️ 需要额外加载page-only.js（~180KB）
- ⚠️ 会有100-200ms延迟（网络请求）
- ✅ 但这是按需加载，用户正在看文章，可以接受
### 后续PJAX导航（文章→文章）
- ✅ page-only.js已加载，无需重新加载
- ✅ 性能无影响
---
## 🔄 回滚方案
### 如果PJAX适配出现问题
**方案1：回滚mypjax.js**
```bash
git checkout themes/Ying/assets/js/modules/mypjax.js
```
**方案2：始终加载page-only.js**
修改footer.html，所有页面都加载page-only.js：
```gohtml
{{/* 始终加载page-only.js */}}
<script defer src="{{ $pageScripts.RelPermalink }}"></script>
```
**缺点：** 首页也会加载artalk等JS，违背优化初衷
---
## 💡 最佳实践
### 1. 充分测试
- ✅ 测试所有页面类型
- ✅ 测试PJAX导航场景
- ✅ 测试边界情况
- ✅ 监控Console错误
### 2. 性能监控
- ✅ 监控page-only.js加载时间
- ✅ 检查是否有重复加载
- ✅ 记录PJAX导航耗时
- ✅ 优化加载时序
### 3. 错误处理
- ✅ 添加加载失败处理
- ✅ 提供降级方案
- ✅ 记录错误日志
- ✅ 及时修复问题
---
## 📈 总结
### PJAX适配完成
- ✅ 动态加载page-only.js
- ✅ 全局变量传递URL
- ✅ 事件监听（pjax:complete）
- ✅ 加载状态标志（防止重复加载）
### 优化效果保持
- ✅ 首页JS减少56%
- ✅ 文章页JS减少44%
- ✅ PJAX完美适配
- ✅ 所有功能正常
### 兼容性
- ✅ Chrome 47+
- ✅ Firefox 55+
- ✅ Safari 12.1+
- ✅ Edge 79+
---
**PJAX适配完成时间：** 2026-06-03
**实施耗时：** 约30分钟
**风险等级：** 低
**测试状态：** 通过
**PJAX适配完美！** 🎉
docs/archive/主题与内容/性能优化（历史）/06-PJAX修复总结.md
+204
View File
@@ -0,0 +1,204 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 06-PJAX修复总结
**创建日期：** 2026-06-03
**版本：** v1.0
**状态：** ✅ 已完成
**问题：** PJAX导航后评论区不加载
---
## 🔴 问题描述
### 问题现象
用户反馈：通过PJAX导航到文章详情页后，评论区不加载。
### 复现步骤
1. 访问首页
2. 点击文章链接（PJAX导航，无刷新）
3. 进入文章详情页
4. 评论区未加载
### 错误信息
Console显示：
```
Uncaught ReferenceError: initArtalk is not defined
```
---
## 🔍 问题分析
### 根本原因
1. **page-only.js只在首次访问时加载**
- 文章详情页直接访问时，page-only.js在footer.html中加载
- PJAX导航时，不会重新加载JS文件
2. **initArtalk函数未定义**
- artalk.js中的initArtalk函数在page-only.js中
- 如果page-only.js未加载，该函数不存在
3. **mypjax.js尝试调用未定义的函数**
- pjax:complete事件中调用initArtalk
- 但函数未定义，导致错误
---
## ✅ 解决方案
### 方案：动态加载 + 全局URL
**核心思路：**
1. 存储page-only.js的URL到全局变量
2. PJAX导航时检测是否需要加载
3. 动态创建script标签加载
4. 加载完成后初始化功能
---
## 🛠️ 实施步骤
### 步骤1：修改footer.html
**修改内容：**
- 所有页面都计算page-only.js的URL
- 存储在window._pageOnlyScriptUrl全局变量
**关键代码：**
```gohtml
{{ if .IsPage }}
<script defer src="{{ $pageScripts.RelPermalink }}"></script>
<script>window._pageOnlyScriptUrl = '{{ $pageScripts.RelPermalink }}';</script>
{{ else }}
<script>window._pageOnlyScriptUrl = '{{ $pageScripts.RelPermalink }}';</script>
{{ end }}
```
---
### 步骤2：修改mypjax.js
**修改内容：**
- 在pjax:complete事件中添加动态加载逻辑
- 检测当前页面是否为文章详情页
- 动态加载page-only.js
- 初始化Artalk等功能
**关键代码：**
```javascript
// 动态加载页面特定JS（PJAX适配）
var isArticlePage = document.querySelector('#Comments') !== null ||
document.querySelector('.post-content') !== null;
if (isArticlePage && !window._pageOnlyLoaded && window._pageOnlyScriptUrl) {
var script = document.createElement('script');
script.src = window._pageOnlyScriptUrl;
script.onload = function() {
window._pageOnlyLoaded = true;
console.log('page-only.js loaded for PJAX navigation');
if (typeof window.initArtalk === 'function') {
try { window.initArtalk(); } catch(e) {}
}
};
document.body.appendChild(script);
}
```
---
## 🧪 测试验证
### 测试场景
**场景1：首页 → 文章详情页**
- [ ] PJAX导航成功
- [ ] 评论区正常加载
- [ ] Console显示加载日志
**场景2：文章 → 另一篇文章**
- [ ] PJAX导航成功
- [ ] 评论区正常（无需重新加载）
**场景3：文章 → 首页**
- [ ] PJAX导航成功
- [ ] 首页正常
---
## 📊 性能影响
### 优化效果保持
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **首页JS** | 800KB | 350KB | ⚡ -56% |
| **文章页JS** | 800KB | 450KB | ⚡ -44% |
| **PJAX适配** | ✅ | ✅ | - |
### PJAX适配开销
- **代码量：** +30行（mypjax.js）
- **运行时开销：** 可忽略不计
- **网络开销：** 仅首次加载page-only.js（~180KB）
---
## 🔄 回滚方案
### 如果修复出现问题
**方案1：回滚mypjax.js**
```bash
git checkout themes/Ying/assets/js/modules/mypjax.js
```
**方案2：始终加载page-only.js**
```gohtml
<script defer src="{{ $pageScripts.RelPermalink }}"></script>
```
---
## 💡 经验总结
### 关键点
1. **PJAX不重新加载JS**
- 需要手动处理动态加载
- 使用全局变量传递URL
2. **函数定义检查**
- 调用前检查函数是否存在
- 使用typeof检查
3. **加载状态管理**
- 使用标志位防止重复加载
- window._pageOnlyLoaded
4. **错误处理**
- 添加try-catch
- 记录错误日志
---
## ✅ 修复完成
- ✅ PJAX导航正常
- ✅ 评论区正常加载
- ✅ 性能优化保持
- ✅ 所有功能正常
**PJAX修复成功！** 🎉
---
**修复完成时间：** 2026-06-03
**修复耗时：** 约30分钟
**风险等级：** 低
**测试状态：** 通过
docs/archive/主题与内容/性能优化（历史）/07-字体子集化优化.md
+239
View File
@@ -0,0 +1,239 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 07-字体子集化优化
**创建日期：** 2026-06-03
**版本：** v1.0
**状态：** ✅ 已完成
**优化效果：** 字体减少37%（1.2MB → 757KB）
---
## 📋 优化概述
### 优化目标
将中文字体从1.2MB优化到757KB，减少37%，提升加载速度。
### 优化效果
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **字体大小** | 1.2MB | 757KB | ⚡ -37% |
| **字符数** | 20,000+ | 2,485 | - |
| **加载时间** | ~6s | ~4s | ⚡ -33% |
---
## 🔍 优化原理
### 原始字体
- 包含完整中文字符集（20,000+字符）
- 包含CJK扩展区（生僻字）
- 文件大小：1.2MB
### 子集字体
- 只包含实际使用的字符（2,485个）
- 常用中文字符
- 英文字母和数字
- 常用标点符号
- 文件大小：757KB
---
## 🛠️ 实施步骤
### 步骤1：备份原始字体
```bash
cd E:\GitHub\blog
# Windows
copy themes\Ying\static\font\zql-v2.woff2 themes\Ying\static\font\zql-v2.woff2.backup
copy themes\Ying\static\font\zql-v2.woff themes\Ying\static\font\zql-v2.woff.backup
# Mac/Linux
cp themes/Ying/static/font/zql-v2.woff2 themes/Ying/static/font/zql-v2.woff2.backup
cp themes/Ying/static/font/zql-v2.woff themes/Ying/static/font/zql-v2.woff.backup
```
---
### 步骤2：安装Python依赖
```bash
pip install fonttools brotli
```
---
### 步骤3：构建Hugo站点
```bash
hugo --destination=public
```
---
### 步骤4：运行字体子集化
```bash
python scripts/subset-font-safe.py
```
**预期输出：**
```
🔤 字体子集化工具（安全版本）
==================================================
✅ 找到public目录，将扫描构建后的HTML
🔍 扫描目录: content, layouts, public
📝 提取了 2492 个唯一字符
💾 字符列表已保存到: themes/Ying/static/font\used_chars.txt
✂️ 正在生成子集字体...
✅ 子集化完成！
📊 优化结果:
子集字符数: 2485
子集文件大小: 739.7 KB
减少: 486.8 KB (39.7%)
🎉 所有子集字体生成成功！
```
---
### 步骤5：更新CSS字体声明
**文件：** `themes/Ying/assets/css/main.css`
**修改字体声明：**
```css
@font-face {
font-family: 'zql';
src: url('../font/zql-v2-subset.woff2') format('woff2'),
url('../font/zql-v2-subset.woff') format('woff');
font-display: swap;
}
```
**关键改动：**
- `zql-v2.woff2` → `zql-v2-subset.woff2`
- `zql-v2.woff` → `zql-v2-subset.woff`
- 删除 `unicode-range`
---
## 🧪 测试验证
### 功能测试
- [ ] 中文字符正常
- [ ] 英文字符正常
- [ ] 数字正常
- [ ] 标点符号正常
- [ ] 深色模式正常
- [ ] 移动端正常
### 性能测试
- [ ] Network面板显示字体大小减少
- [ ] 无404错误
- [ ] Lighthouse无字体警告
---
## 🔄 回滚方案
### 如果优化失败
```bash
# 恢复原始字体
cp themes/Ying/static/font/zql-v2.woff2.backup themes/Ying/static/font/zql-v2.woff2
cp themes/Ying/static/font/zql-v2.woff.backup themes/Ying/static/font/zql-v2.woff
# 恢复CSS
git checkout themes/Ying/assets/css/main.css
```
---
## 📊 Python脚本说明
### 脚本功能
**subset-font-safe.py：**
- 扫描所有HTML、CSS、Markdown文件
- 提取实际使用的字符
- 生成子集字体
- 验证优化效果
### 工作原理
1. **扫描目录**
- content/（文章内容）
- layouts/（模板文件）
- public/（构建后的HTML）
2. **提取字符**
- 中文字符
- 英文字母和数字
- 常用标点符号
- 特殊符号
3. **生成子集**
- 使用fonttools库
- 保留字体特性
- 压缩输出
---
## 💡 最佳实践
### 1. 定期更新
```bash
# 每月运行一次
python scripts/subset-font-safe.py
```
### 2. 监控字符覆盖
```bash
# 查看字符列表
cat themes/Ying/static/font/used_chars.txt
```
### 3. 验证优化效果
```bash
# 检查文件大小
ls -lh themes/Ying/static/font/zql-v2-subset.*
```
---
## 📈 优化总结
### 完成情况
- ✅ 字体大小减少37%
- ✅ 保持所有字符正常显示
- ✅ 加载速度提升33%
- ✅ 自动化脚本就绪
### 后续使用
- ✅ GitHub Actions自动优化
- ✅ 内容更新时自动触发
- ✅ 无需手动干预
---
**字体优化完成时间：** 2026-06-03
**实施耗时：** 约1.5小时
**优化效果：** 字体减少37%
**风险等级：** 低
**维护成本：** 0（自动化）
**字体优化效果显著！** 🎉
docs/archive/主题与内容/性能优化（历史）/08-GitHub-Actions使用指南.md
+359
View File
@@ -0,0 +1,359 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 08-GitHub-Actions使用指南
**创建日期：** 2026-06-03
**版本：** v1.0
**状态：** ✅ 已配置完成
**工作流：** Font Subset Optimization
---
## 📋 工作流概述
### 工作流名称
`Font Subset Optimization`（字体子集优化）
### 工作流文件
`.github/workflows/subset-fonts.yml`
### 触发条件
1. **自动触发** - 推送到main分支且content/或layouts/有变更
2. **手动触发** - 在GitHub Actions界面手动运行
3. **定期触发** - 每周一凌晨2点自动检查
---
## 🚀 使用方法
### 方法1：自动触发（推荐）✅
**无需任何操作！** 当你推送内容更新时，工作流自动运行：
```bash
# 发布新文章
git add content/posts/new-article.md
git commit -m "feat: new article"
git push origin main
# GitHub Actions自动：
# 1. 检测到content目录有变更
# 2. 构建Hugo站点
# 3. 运行字体子集化
# 4. 提交优化后的字体
```
**查看运行状态：**
```
访问：https://github.com/zqlit/blog/actions
```
---
### 方法2：手动触发
**适用场景：**
- 强制重新生成子集字体
- 修改了字体脚本
- 测试工作流
**操作步骤：**
1. 访问GitHub仓库 → **Actions** 标签
2. 选择 **Font Subset Optimization**
3. 点击 **Run workflow**
4. （可选）勾选 **强制重新生成子集字体**
5. 点击 **Run workflow** 按钮
---
### 方法3：定期自动运行
**默认：** 每周一凌晨2点自动运行
**作用：** 检查是否需要更新
**修改频率：**
```yaml
# 编辑 .github/workflows/subset-fonts.yml
schedule:
# 每天凌晨3点
- cron: '0 3 * * *'
# 每月1号凌晨2点
- cron: '0 2 1 * *'
```
---
## 📊 工作流步骤
### 步骤1：检出代码
```yaml
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
```
**作用：** 下载仓库代码
---
### 步骤2：设置Python环境
```yaml
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
cache: 'pip'
```
**作用：** 安装Python 3.11
---
### 步骤3：安装依赖
```yaml
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install fonttools brotli
```
**作用：** 安装字体处理工具
---
### 步骤4：构建Hugo站点
```yaml
- name: Build Hugo site
uses: peaceiris/actions-hugo@v2
with:
hugo-version: 'latest'
extended: true
- name: Build
run: hugo --destination=public --minify
```
**作用：** 生成静态HTML
---
### 步骤5：运行字体子集化
```yaml
- name: Subset fonts
run: python scripts/subset-font-safe.py
```
**作用：** 提取字符并生成优化字体
---
### 步骤6：验证优化效果
```yaml
- name: Verify optimization
run: |
ORIGINAL_SIZE=$(stat -c%s themes/Ying/static/font/zql-v2.woff2)
SUBSET_SIZE=$(stat -c%s themes/Ying/static/font/zql-v2-subset.woff2)
# 检查子集字体是否更小
```
**作用：** 确保优化有效
---
### 步骤7：提交更改
```yaml
- name: Commit changes
run: |
git config --local user.email "github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"
git add themes/Ying/static/font/zql-v2-subset.*
git commit -m "chore: update font subset (automated) [skip ci]"
```
**作用：** 保存优化后的字体
**关键：** `[skip ci]` 避免触发deploy.yml
---
### 步骤8：推送更改
```yaml
- name: Push changes
run: git push origin main
```
**作用：** 推送到GitHub仓库
---
## 🔍 监控和调试
### 查看运行状态
1. 访问GitHub仓库
2. 点击 **Actions** 标签
3. 查看运行列表
**状态图标：**
- ✅ **绿色** - 成功
- ❌ **红色** - 失败
- 🟡 **黄色** - 进行中
---
### 查看详细日志
1. 点击具体运行记录
2. 点击 **subset-fonts** 任务
3. 展开每个步骤查看日志
**关键日志：**
```
✅ Font optimized: reduced 486800 bytes (39%)
```
---
## ⚙️ 自定义配置
### 修改触发条件
**只在特定文件变更时触发：**
```yaml
on:
push:
paths:
- 'content/posts/**'
- 'content/**/*.md'
```
---
### 修改运行频率
```yaml
schedule:
# 每天凌晨3点
- cron: '0 3 * * *'
# 每周一和周四凌晨2点
- cron: '0 2 * * 1,4'
```
---
### 禁用定期运行
```yaml
# schedule:
# - cron: '0 2 * * 1'
```
---
## 🐛 故障排除
### 问题1：工作流没有触发
**解决方案：**
1. 检查仓库设置 → Actions → 已启用
2. 检查路径过滤是否正确
3. 查看Actions页面的错误信息
---
### 问题2：Python依赖安装失败
**解决方案：**
```yaml
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install fonttools brotli --no-cache-dir
```
---
### 问题3：Hugo构建失败
**解决方案：**
1. 检查hugo.toml配置
2. 确保所有主题文件存在
3. 查看Hugo错误日志
---
### 问题4：推送失败
**原因：** GitHub Actions没有写权限
**解决方案：**
1. 仓库设置 → Actions → General
2. **Workflow permissions** → 选择 **Read and write permissions**
---
## 💡 最佳实践
### 1. 保护主分支
**建议：** 启用分支保护规则
---
### 2. 监控工作流
**建议：** 设置失败通知
---
### 3. 测试工作流
**建议：** 在feature分支测试
---
## 📈 工作流优势
### ✅ 自动化
- 无需手动运行脚本
- 内容更新时自动优化
- 定期检查确保最新
### ✅ 智能化
- 检测内容变更
- 验证优化效果
- 避免不必要的提交
### ✅ 可靠性
- 使用官方GitHub Actions
- 完整的错误处理
- 详细的日志记录
---
**GitHub Actions配置完成！** 🎉
**现在可以：**
- ✅ 推送内容时自动优化字体
- ✅ 每周定期检查
- ✅ 手动触发（需要时）
- ✅ 无需手动干预
docs/archive/主题与内容/性能优化（历史）/09-Actions修复指南.md
+210
View File
@@ -0,0 +1,210 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 09-Actions修复指南
**创建日期：** 2026-06-03
**版本：** v1.0
**状态：** ✅ 已修复
**适用范围：** GitHub Actions常见问题
---
## 🔴 问题1：Python依赖安装失败
### 错误信息
```
Error: No file in /home/runner/work/blog/blog matched to [**/requirements.txt or **/pyproject.toml]
```
### 原因
actions/setup-python@v5的cache功能需要requirements.txt文件
### 解决方案
**创建requirements.txt：**
```bash
echo fonttools > requirements.txt
echo brotli >> requirements.txt
```
**恢复cache配置：**
```yaml
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
cache: 'pip'
```
---
## 🔴 问题2：与deploy.yml冲突
### 问题场景
```
subset-fonts.yml push到main
↓
触发deploy.yml
↓
deploy.yml可能又push
↓
再次触发subset-fonts.yml
↓
无限循环！❌
```
### 解决方案
**在subset-fonts.yml的commit消息中添加[skip ci]：**
```yaml
git commit -m "chore: update font subset (automated) [skip ci]"
```
**原理：**
- deploy.yml检查commit消息
- 如果包含[skip ci]，不会再次触发
- 避免循环触发
---
## 🔴 问题3：工作流没有触发
### 可能原因
1. Actions未启用
2. 路径过滤不正确
3. 仓库名配置错误
### 解决方案
**检查仓库设置：**
```
Settings → Actions → General → 选择 "Allow all actions"
```
**检查仓库名：**
```yaml
if: github.repository == 'zqlit/blog' # 确保正确
```
---
## 🔴 问题4：推送失败
### 错误信息
```
Permission denied
```
### 解决方案
**修改仓库权限：**
```
Settings → Actions → General → Workflow permissions
→ 选择 "Read and write permissions"
→ 勾选 "Allow GitHub Actions to create and approve pull requests"
```
---
## 🔴 问题5：Hugo构建失败
### 可能原因
1. hugo.toml配置错误
2. 主题文件缺失
3. Hugo版本不兼容
### 解决方案
**检查配置文件：**
```bash
hugo config
```
**指定Hugo版本：**
```yaml
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: '0.128.2' # 指定版本
extended: true
```
---
## 🔴 问题6：字体子集化失败
### 可能原因
1. Python脚本语法错误
2. 字体文件不存在
3. 依赖版本不兼容
### 解决方案
**检查Python脚本：**
```bash
python scripts/subset-font-safe.py
```
**检查依赖版本：**
```bash
pip show fonttools
pip show brotli
```
---
## 💡 预防措施
### 1. 定期检查
```bash
# 每周查看Actions运行状态
# https://github.com/zqlit/blog/actions
```
### 2. 监控日志
```bash
# 查看详细日志
# Actions → 具体运行 → subset-fonts → 查看日志
```
### 3. 测试工作流
```bash
# 在feature分支测试
git checkout -b test/workflow
git push origin test/workflow
```
---
## 📞 获取帮助
### 查看GitHub文档
- [GitHub Actions文档](https://docs.github.com/en/actions)
- [workflow语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)
### 查看Actions日志
```
Actions → 具体运行 → 查看详细日志
```
---
**故障排除指南完成！** 🎉
**遇到问题时：**
1. 查看本文档
2. 检查Actions日志
3. 搜索GitHub文档
docs/archive/主题与内容/性能优化（历史）/10-提交指南.md
+313
View File
@@ -0,0 +1,313 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 10-提交指南
**创建日期：** 2026-06-03
**版本：** v1.0
**适用范围：** 性能优化代码提交
---
## 📋 提交内容清单
### 1. JS优化（已提交）✅
**修改文件：**
- `themes/Ying/layouts/partials/footer.html`
- `themes/Ying/assets/js/modules/mypjax.js`
**提交信息：**
```
perf: JS按需加载优化 + PJAX适配
- 首页JS减少56%（800KB → 350KB）
- 文章页JS减少44%（800KB → 450KB）
- 完美适配PJAX导航
- 所有功能正常
```
---
### 2. 字体优化（待提交）⏳
**修改文件：**
- `themes/Ying/assets/css/main.css`
- `themes/Ying/static/font/zql-v2-subset.woff2`
- `themes/Ying/static/font/zql-v2-subset.woff`
- `themes/Ying/static/font/used_chars.txt`
**提交信息：**
```
perf: 字体子集化优化 - 减少37%
- 字体大小：1.2MB → 757KB
- 使用Python fonttools提取2,485个字符
- 保持所有字符正常显示
```
---
### 3. 自动化工作流（待提交）⏳
**创建文件：**
- `.github/workflows/subset-fonts.yml`
- `requirements.txt`
**提交信息：**
```
ci: 添加字体子集化自动化工作流
- GitHub Actions自动运行
- 内容更新时自动触发
- 每周定期检查
- 智能检测变更
```
---
## 🚀 推荐提交命令
### 方案A：一次提交所有优化（推荐）
```bash
cd E:\GitHub\blog
# 查看修改
git status
# 添加所有文件
git add themes/Ying/assets/css/main.css
git add themes/Ying/static/font/zql-v2-subset.*
git add themes/Ying/static/font/used_chars.txt
git add .github/workflows/subset-fonts.yml
git add requirements.txt
# 提交
git commit -m "perf: 完整性能优化 - JS按需加载 + 字体子集化 + 自动化
JS优化：
- 首页JS减少56%（800KB → 350KB）
- 文章页JS减少44%（800KB → 450KB）
- 完美适配PJAX导航
字体优化：
- 字体大小减少37%（1.2MB → 757KB）
- 使用Python fonttools提取2,485个字符
自动化：
- GitHub Actions自动字体子集化
- 内容更新时自动触发
- 每周定期检查
总体效果：
- 总体资源减少50%+
- Lighthouse得分提升至75-80"
# 推送
git push origin main
```
---
### 方案B：分步提交
**步骤1：提交JS优化**
```bash
git add themes/Ying/layouts/partials/footer.html
git add themes/Ying/assets/js/modules/mypjax.js
git commit -m "perf: JS按需加载优化 + PJAX适配"
```
**步骤2：提交字体优化**
```bash
git add themes/Ying/assets/css/main.css
git add themes/Ying/static/font/zql-v2-subset.*
git add themes/Ying/static/font/used_chars.txt
git commit -m "perf: 字体子集化优化 - 减少37%"
```
**步骤3：提交自动化工作流**
```bash
git add .github/workflows/subset-fonts.yml
git add requirements.txt
git commit -m "ci: 添加字体子集化自动化工作流"
```
**步骤4：推送所有提交**
```bash
git push origin main
```
---
## 📋 提交前检查清单
### 文件检查
- [ ] main.css已修改（字体路径）
- [ ] zql-v2-subset.woff2已生成（757KB）
- [ ] zql-v2-subset.woff已生成（757KB）
- [ ] subset-fonts.yml已创建
- [ ] requirements.txt已创建
### 功能检查
- [ ] 首页正常显示
- [ ] 文章详情页正常
- [ ] 评论区正常加载
- [ ] 深色模式正常
- [ ] 字体显示正常
### 性能检查
- [ ] Network面板显示字体大小 ~757KB
- [ ] JS大小减少（首页~350KB）
- [ ] 无Console错误
---
## 🔍 验证提交
### 提交后检查
```bash
# 查看提交历史
git log --oneline -5
# 查看提交详情
git show HEAD
# 查看远程是否同步
git fetch origin
git log --oneline origin/main -3
```
### GitHub Actions验证
1. 访问：`https://github.com/zqlit/blog/actions`
2. 查看是否有新的工作流运行
3. 检查工作流状态
---
## 💡 提交最佳实践
### 1. 清晰的提交信息
**好的示例：**
```
perf: JS按需加载优化 - 首页减少56%
- 拆分为core.js、page-only.js、deferred.js
- 核心JS始终加载
- 页面特定JS按需加载
- 完美适配PJAX导航
```
**不好的示例：**
```
update
fix
perf
```
---
### 2. 原子性提交
**好的做法：**
- 一个提交解决一个问题
- 便于回滚和追踪
- 代码审查更容易
**不好的做法：**
- 一个提交包含多个不相关修改
- 难以回滚
- 代码审查困难
---
### 3. 测试后再提交
**流程：**
1. 本地测试通过
2. 提交代码
3. 推送到远程
4. 等待CI/CD运行
5. 验证部署成功
---
## 🔄 回滚方案
### 如果提交后发现问题
**回滚到上一个提交：**
```bash
# 查看提交历史
git log --oneline -10
# 回滚到特定提交
git revert <commit-hash>
# 或者回滚到上一个提交
git reset --hard HEAD~1
git push origin main --force
```
**注意：** `--force` 会覆盖远程历史，谨慎使用
---
## 📊 提交统计
### 本次优化提交
**提交次数：** 3-4次
**修改文件：** 8-10个
**新增文件：** 5-6个
**代码行数：** +500行（估算）
### 提交时间线
```
Day 1: JS优化
├── 修改footer.html
├── 修改mypjax.js
└── 测试验证
Day 2: 字体优化
├── 运行子集化脚本
├── 修改main.css
└── 测试验证
Day 3: 自动化
├── 创建subset-fonts.yml
├── 创建requirements.txt
└── 测试自动化
```
---
## ✅ 提交完成
### 验证成功
- ✅ 所有文件已提交
- ✅ GitHub Actions正常运行
- ✅ 部署成功
- ✅ 性能提升生效
### 后续使用
**现在可以：**
- ✅ 发布新文章时自动优化
- ✅ 享受性能提升
- ✅ 无需手动干预
---
**提交指南完成！** 🎉
**祝你提交顺利！**
docs/archive/主题与内容/性能优化（历史）/11-JS优化测试指南.md
+190
View File
@@ -0,0 +1,190 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 11-JS优化测试指南
**创建日期：** 2026-06-03
**版本：** v1.0
**适用范围：** JS按需加载优化测试
---
## 🧪 测试步骤
### 步骤1：构建并启动Hugo
```bash
cd E:\GitHub\blog
hugo --cleanDestinationDir
hugo server -D
```
访问：`http://localhost:1313`
---
### 步骤2：Network面板检查
1. 打开DevTools（F12）
2. 切换到 **Network** 面板
3. 刷新页面（Ctrl+Shift+R）
**预期结果：**
- ✅ 看到 `core.js` 文件加载（~200KB）
- ✅ 首页不加载 `page-only.js`
- ✅ 文章详情页加载 `page-only.js`（~180KB）
- ✅ 总体JS大小显著减少
---
### 步骤3：Lighthouse测试
1. 切换到 **Lighthouse** 面板
2. 选择 **Performance**
3. 点击 **Analyze page load**
**预期指标：**
- [ ] Performance得分：75-85（提升15-25分）
- [ ] TTI：改善20-30%
- [ ] TBT：改善40-50%
- [ ] Speed Index：改善20-30%
---
## 🔍 功能测试清单
### 首页功能
**核心功能（必须正常）：**
- [ ] 导航菜单点击正常
- [ ] 搜索框打开/关闭正常
- [ ] 搜索结果显示正常
- [ ] 主题切换（深色/浅色）正常
- [ ] 文章列表显示正常
- [ ] 分页功能正常
- [ ] 浮动工具栏正常
**条件加载功能：**
- [ ] 无限滚动正常（如果启用）
---
### 文章详情页功能
**核心功能（必须正常）：**
- [ ] 文章内容正常显示
- [ ] 图片灯箱正常（点击查看大图）
- [ ] 返回顶部按钮正常
**按需加载功能（必须正常）：**
- [ ] Artalk评论区正常加载（等待1-2秒）
- [ ] 评论功能正常（发布、回复）
- [ ] 打赏按钮功能正常
- [ ] 段落评论正常（如果启用）
---
### 其他页面功能
- [ ] 友链页面（/links）正常
- [ ] circles页面（/circles）正常
- [ ] 归档页面（/archives）正常
- [ ] 搜索结果页正常
---
### 跨页面功能
- [ ] PJAX导航正常（页面无刷新切换）
- [ ] 浏览器前进/后退正常
- [ ] 书签/分享链接正常
---
## 📊 性能指标对比表
### Network面板数据
| 资源 | 优化前大小 | 优化后大小 | 减少 |
|------|-----------|-----------|------|
| **首页JS** | 800KB | ____KB | ____% |
| **文章页JS** | 800KB | ____KB | ____% |
| **总体资源** | ~3MB | ____KB | ____% |
### Lighthouse指标
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **Performance得分** | 60 | ____ | +____ |
| **FCP** | 2.5s | ____s | ____% |
| **LCP** | 3.5s | ____s | ____% |
| **TTI** | 4.0s | ____s | ____% |
| **TBT** | 350ms | ____ms | ____% |
| **Speed Index** | 3.0s | ____s | ____% |
---
## 🐛 故障排除
### 问题1：评论区未加载
**解决方案：**
1. 打开Console查看错误
2. 检查Network面板，确认page-only.js加载成功
3. 等待2-3秒，Artalk可能需要时间初始化
---
### 问题2：功能延迟响应
**解决方案：**
- 这是预期行为，用户可能会感觉到轻微延迟
- 如果延迟明显（>3秒），考虑将该模块移到core.js
---
### 问题3：无限滚动失效
**解决方案：**
1. 检查hugo.toml中infiniteScroll.enable是否为true
2. 查看Console是否有错误
3. 确认infinite-scroll.js加载成功
---
## 🔄 回滚方案
### 如果优化后出现严重问题
```bash
# 备份当前文件
cp themes/Ying/layouts/partials/footer.html themes/Ying/layouts/partials/footer.html.optimized
# 恢复原始代码（参考TEST_JS_OPTIMIZATION.md中的回滚方案）
```
---
## ✅ 测试通过标准
### 功能标准（必须全部通过）
- ✅ 所有页面正常显示
- ✅ 核心功能正常（导航、搜索、主题切换）
- ✅ 文章详情页功能正常（评论、打赏、灯箱）
- ✅ 无限滚动正常（如果启用）
- ✅ PJAX导航正常
- ✅ 无Console错误（或只有非关键警告）
### 性能标准（至少达到一项）
- ✅ Lighthouse Performance得分提升10+分
- ✅ TTI改善15%+
- ✅ TBT改善30%+
- ✅ 总体JS大小减少40%+
---
**JS优化测试指南完成！** 🎉
**测试通过后即可提交代码！**
docs/archive/主题与内容/性能优化（历史）/12-字体优化测试指南.md
+197
View File
@@ -0,0 +1,197 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 12-字体优化测试指南
**创建日期：** 2026-06-03
**版本：** v1.0
**适用范围：** 字体子集化优化测试
---
## 🧪 测试步骤
### 步骤1：重新构建Hugo
```bash
cd E:\GitHub\blog
hugo --cleanDestinationDir
hugo server -D
```
访问：`http://localhost:1313`
---
### 步骤2：检查字体加载
1. 打开DevTools（F12）
2. 切换到 **Network** 面板
3. 刷新页面
4. 筛选 `woff2` 或 `woff`
**预期结果：**
- ✅ 看到 `zql-v2-subset.woff2` 被加载
- ✅ 文件大小：~757KB（而不是1.2MB）
- ✅ 无404错误
---
### 步骤3：视觉检查
#### 中文字符测试
- [ ] 导航菜单中文正常
- [ ] 文章标题中文正常
- [ ] 文章内容中文正常
- [ ] 深色模式下中文正常
#### 英文字符测试
- [ ] 英文字母正常（A-Z, a-z）
- [ ] 数字正常（0-9）
- [ ] 常用符号正常（@#$%）
#### 标点符号测试
- [ ] 中文标点正常（，。！？、；：""''）
- [ ] 英文标点正常（,.!?;:'"）
- [ ] 括号正常（（）【】《》）
#### 不同页面测试
- [ ] 首页字体正常
- [ ] 文章详情页字体正常
- [ ] 友链页面字体正常
- [ ] 归档页面字体正常
- [ ] 移动端字体正常
---
### 步骤4：深色模式测试
1. 点击头像或主题切换按钮
2. 检查深色模式下：
- [ ] 所有文字正常显示
- [ ] 字体颜色正确
- [ ] 无闪烁或异常
---
## 📊 性能验证
### Network面板数据记录
| 文件 | 优化前 | 优化后 | 减少 |
|------|--------|--------|------|
| **zql-v2.woff2** | 1.2MB | ____KB | ____% |
| **zql-v2.woff** | 1.2MB | ____KB | ____% |
| **总字体大小** | 2.4MB | ____KB | ____% |
---
### Lighthouse测试（可选）
使用Chrome DevTools的Lighthouse面板测试
**预期指标：**
- Performance得分：75-85
- 无字体相关警告
- FCP：改善20-30%
---
## 🔍 验证子集化效果
### 检查字符覆盖
你的子集字体包含 **2,485个字符**，包括：
**基本字符：**
- ✅ 英文字母（A-Z, a-z）
- ✅ 数字（0-9）
- ✅ 常用标点符号
**中文字符：**
- ✅ 常用汉字（根据网站内容提取）
- ✅ 中文标点符号
- ✅ CJK符号
---
## 🐛 故障排除
### 问题1：字符显示为方块（□）
**解决方案A：重新运行子集化**
```bash
python scripts/subset-font-safe.py
```
**解决方案B：保留原始字体作为fallback**
```css
@font-face {
font-family: 'zql';
src: url('../font/zql-v2-subset.woff2') format('woff2');
font-display: swap;
}
@font-face {
font-family: 'zql-full';
src: url('../font/zql-v2.woff2') format('woff2');
font-display: swap;
}
body {
font-family: 'zql', 'zql-full', serif;
}
```
---
### 问题2：字体文件404错误
**解决方案：**
1. 确认文件存在：`ls themes/Ying/static/font/zql-v2-subset.*`
2. 检查CSS路径是否正确
3. 清理Hugo缓存：`hugo --cleanDestinationDir`
---
## 🔄 回滚方案
### 如果优化后出现问题
```bash
# 恢复原始字体
cp themes/Ying/static/font/zql-v2.woff2.backup themes/Ying/static/font/zql-v2.woff2
cp themes/Ying/static/font/zql-v2.woff.backup themes/Ying/static/font/zql-v2.woff
# 恢复CSS
git checkout themes/Ying/assets/css/main.css
```
---
## ✅ 测试通过标准
### 功能标准（必须全部通过）
- ✅ 所有页面正常显示
- ✅ 中文字符正常（常用汉字、标点）
- ✅ 英文字符正常（字母、数字、符号）
- ✅ 深色模式正常
- ✅ 响应式布局正常
- ✅ 无Console错误
### 性能标准（至少达到一项）
- ✅ 字体大小减少30%+（1.2MB → 757KB ✅ 已达成）
- ✅ 加载时间减少20%+
- ✅ Lighthouse无字体警告
---
**字体优化测试指南完成！** 🎉
**测试通过后即可提交代码！**
docs/archive/主题与内容/性能优化（历史）/13-主题全面优化分析.md
+239
View File
@@ -0,0 +1,239 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 13-主题全面优化分析
**创建日期：** 2026-06-03
**版本：** v1.0
**分析对象：** Hugo主题Ying
**分析范围：** 性能、代码质量、SEO、安全性
---
## 📋 主题概述
### 主题信息
- **主题名称：** Ying
- **主题类型：** Hugo静态站点主题
- **功能特点：** 简洁优雅、深色模式、PJAX导航、响应式设计
### 技术栈
- **前端框架：** UIkit
- **图标库：** Remixicon
- **评论系统：** Artalk
- **图表库：** Echarts
- **导航技术：** PJAX
---
## ✅ 优点
### 1. 优秀的资源压缩策略
- ✅ CSS/JS文件合并和压缩
- ✅ 使用Hugo资源管道
- ✅ Fingerprint缓存破坏
### 2. 深色模式支持
- ✅ CSS变量实现
- ✅ 平滑过渡动画
- ✅ 用户偏好存储
### 3. 响应式设计
- ✅ 移动端适配
- ✅ 触摸优化
- ✅ 灵活布局
### 4. 模块化JavaScript
- ✅ 功能模块分离
- ✅ 按需初始化
- ✅ 错误处理
### 5. 现代化SEO基础
- ✅ Open Graph标签
- ✅ Twitter Card
- ✅ Canonical URL
---
## ⚠️ 需要优化的地方
### 1. 性能优化（已实施）✅
**问题：**
- 所有JS打包为单个bundle（800KB）
- 字体文件过大（1.2MB）
- 所有页面加载所有资源
**解决方案：**
- ✅ JS按需加载（减少56%）
- ✅ 字体子集化（减少37%）
- ✅ 总体性能提升50%
---
### 2. CSS架构（建议优化）
**问题：**
- main.css为单一大文件（500KB+）
- 深度嵌套选择器
- 缺少CSS变量管理
**建议：**
- 拆分为模块化CSS
- 使用BEM命名规范
- 集中管理CSS变量
---
### 3. SEO完善（建议优化）
**问题：**
- 缺少结构化数据（JSON-LD）
- Meta keywords逻辑不完善
- 缺少面包屑导航
**建议：**
- 添加JSON-LD结构化数据
- 优化meta keywords提取
- 添加面包屑导航
---
### 4. 安全性（建议优化）
**问题：**
- 缺少SRI（Subresource Integrity）
- 未实施CSP（Content Security Policy）
- 第三方脚本安全审计
**建议：**
- 添加SRI哈希
- 实施CSP头部
- 审计第三方依赖
---
### 5. 可访问性（建议优化）
**问题：**
- 缺少ARIA标签
- 键盘导航不完整
- 颜色对比度可能不足
**建议：**
- 添加ARIA标签
- 完善键盘导航
- 检查颜色对比度
---
## 📊 优化优先级
### 高优先级（已实施）✅
1. **JS按需加载** - 减少56%
2. **字体子集化** - 减少37%
3. **GitHub Actions自动化** - 100%自动化
---
### 中优先级（建议实施）
1. **CSS架构重构** - 提升可维护性
2. **SEO完善** - 提升搜索引擎排名
3. **安全性增强** - 保护用户安全
---
### 低优先级（可选）
1. **可访问性改进** - 提升用户体验
2. **代码注释增强** - 提升可读性
3. **文档完善** - 便于维护
---
## 🎯 已实施的优化
### 1. JS按需加载优化
**优化效果：**
- 首页JS：800KB → 350KB（⚡ -56%）
- 文章页JS：800KB → 450KB（⚡ -44%）
**技术实现：**
- 代码拆分为4个bundle
- 核心JS始终加载
- 页面特定JS按需加载
- 非关键JS延迟加载
---
### 2. 字体子集化优化
**优化效果：**
- 字体大小：1.2MB → 757KB（⚡ -37%）
**技术实现：**
- Python fonttools提取字符
- 生成子集字体（2,485字符）
- 更新CSS字体声明
---
### 3. GitHub Actions自动化
**自动化程度：** 100%
**功能：**
- 内容更新时自动优化字体
- 每周定期检查
- 智能检测变更
- 自动部署到UpYun
---
## 📈 优化效果总结
### 性能提升
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **总体资源** | ~3MB | ~1.5MB | ⚡ -50% |
| **加载速度** | 慢 | 快 | ⚡ +40% |
| **Lighthouse** | 60 | 75-80 | ⚡ +33% |
---
## 💡 后续建议
### 1. 定期监控
- ✅ 每月Lighthouse测试
- ✅ 监控Core Web Vitals
- ✅ 收集用户反馈
### 2. 持续优化
- ✅ CSS架构重构
- ✅ SEO完善
- ✅ 安全性增强
### 3. 文档维护
- ✅ 更新优化文档
- ✅ 记录最佳实践
- ✅ 分享优化经验
---
**主题全面优化分析完成！** 🎉
**核心优化已实施，性能提升50%！**
docs/archive/主题与内容/性能优化（历史）/14-JS优化最终方案.md
+201
View File
@@ -0,0 +1,201 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 14-JS优化最终方案
**创建日期：** 2026-06-03
**版本：** v2.0
**状态：** ✅ 已实施
**优化效果：** 首页JS减少56%，文章页JS减少44%
---
## 📋 方案概述
### 优化目标
将JS拆分为多个bundle，实现按需加载，提升性能。
### 优化效果
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **首页JS** | 800KB | 350KB | ⚡ -56% |
| **文章页JS** | 800KB | 450KB | ⚡ -44% |
| **TTI** | 4.0s | ~2.0s | ⚡ -50% |
| **TBT** | 350ms | ~100ms | ⚡ -71% |
---
## 🔧 技术实现
### JS Bundle拆分
**1. core.js (200KB) - 始终加载**
- UIkit框架
- 图标字体
- 图片灯箱
- 工具函数
- 搜索功能
- 浮动工具
- 进度条
- PJAX
- 主题主逻辑
**2. page-only.js (180KB) - 文章详情页**
- Artalk评论系统
- 段落评论
- 打赏功能
**3. deferred.js (25KB) - 延迟加载**
- Toast消息
- 图片懒加载
**4. infinite-scroll.js (20KB) - 首页（如果启用）**
**5. tiaozhuan.js (8KB) - 特定页面**
---
## 🛠️ 实施步骤
### 步骤1：修改footer.html
**文件：** `themes/Ying/layouts/partials/footer.html`
**修改内容：**
- 创建核心JS bundle
- 创建页面特定JS bundle
- 创建延迟加载JS bundle
- 首页专用JS
- 特定页面专用JS
---
### 步骤2：适配PJAX
**文件：** `themes/Ying/assets/js/modules/mypjax.js`
**修改内容：**
- 在pjax:complete事件中添加动态加载逻辑
- 检测当前页面是否为文章详情页
- 动态加载page-only.js
- 初始化Artalk等功能
---
## 📊 加载时序
### 优化前
```
页面加载
↓
下载bundle.js (800KB)
↓
执行所有JS
↓
渲染页面
↓
用户可以交互
```
---
### 优化后
```
页面加载
↓
下载core.js (200KB) - 立即
↓
渲染页面（核心功能可用）
↓
用户可以交互
↓
下载page-only.js (180KB) - 按需（仅文章页）
↓
下载deferred.js (25KB) - 延迟（浏览器空闲）
↓
所有功能可用
```
---
## 🧪 测试验证
### 功能测试
- [ ] 首页功能正常
- [ ] 文章详情页正常
- [ ] 评论区正常加载
- [ ] 打赏功能正常
- [ ] PJAX导航正常
- [ ] 无限滚动正常（如果启用）
### 性能测试
- [ ] Network面板显示JS大小减少
- [ ] Lighthouse得分提升
- [ ] 无Console错误
---
## 🔄 回滚方案
### 如果优化后出现严重问题
```bash
# 恢复footer.html
git checkout themes/Ying/layouts/partials/footer.html
# 恢复mypjax.js
git checkout themes/Ying/assets/js/modules/mypjax.js
# 重新构建
hugo --cleanDestinationDir
```
---
## 💡 最佳实践
### 1. 逐步优化
- ✅ 先测试核心功能
- ✅ 逐步添加按需加载
- ✅ 充分测试每个步骤
- ✅ 记录问题和解决方案
### 2. 监控性能
- ✅ 定期Lighthouse测试
- ✅ 监控网络请求
- ✅ 检查Console错误
- ✅ 记录性能数据
---
## 📈 优化效果总结
### 性能提升
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **首页JS** | 800KB | 350KB | ⚡ -56% |
| **文章页JS** | 800KB | 450KB | ⚡ -44% |
| **TTI** | 4.0s | ~2.0s | ⚡ -50% |
| **TBT** | 350ms | ~100ms | ⚡ -71% |
### 用户体验提升
- 🚀 **首屏更快** - 资源减少56%
- ⚡ **交互更流畅** - TTI提升50%
- 📱 **移动端更好** - 节省带宽
- 🎨 **功能完整** - 所有功能正常
---
**JS优化最终方案完成！** 🎉
**优化效果显著，性能提升56%！**
docs/archive/主题与内容/性能优化（历史）/15-字体优化手动指南.md
+207
View File
@@ -0,0 +1,207 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 15-字体优化手动指南
**创建日期：** 2026-06-03
**版本：** v1.0
**适用场景：** 手动执行字体子集化
---
## 📋 手动操作步骤
### 步骤1：备份原始字体（2分钟）
**Windows：**
```bash
cd E:\GitHub\blog
copy themes\Ying\static\font\zql-v2.woff2 themes\Ying\static\font\zql-v2.woff2.backup
copy themes\Ying\static\font\zql-v2.woff themes\Ying\static\font\zql-v2.woff.backup
```
**Mac/Linux：**
```bash
cd E:\GitHub\blog
cp themes/Ying/static/font/zql-v2.woff2 themes/Ying/static/font/zql-v2.woff2.backup
cp themes/Ying/static/font/zql-v2.woff themes/Ying/static/font/zql-v2.woff.backup
```
---
### 步骤2：安装Python依赖（3分钟）
```bash
pip install fonttools brotli
```
**验证安装：**
```bash
python -c "from fontTools.ttLib import TTFont; print('fonttools installed')"
```
---
### 步骤3：构建Hugo站点（2分钟）
```bash
cd E:\GitHub\blog
hugo --destination=public
```
**验证构建：**
```bash
ls public/
```
---
### 步骤4：运行字体子集化（5分钟）
```bash
python scripts/subset-font-safe.py
```
**预期输出：**
```
🔤 字体子集化工具（安全版本）
==================================================
✅ 找到public目录，将扫描构建后的HTML
🔍 扫描目录: content, layouts, public
📝 提取了 2492 个唯一字符
💾 字符列表已保存到: themes/Ying/static/font\used_chars.txt
✂️ 正在生成子集字体...
✅ 子集化完成！
📊 优化结果:
子集字符数: 2485
子集文件大小: 739.7 KB
减少: 486.8 KB (39.7%)
🎉 所有子集字体生成成功！
```
---
### 步骤5：验证生成的文件（1分钟）
**Windows：**
```bash
dir themes\Ying\static\font\zql-v2-subset.*
```
**Mac/Linux：**
```bash
ls -lh themes/Ying/static/font/zql-v2-subset.*
```
**预期大小：**
- `zql-v2-subset.woff2`: ~757KB
- `zql-v2-subset.woff`: ~757KB
---
### 步骤6：更新CSS字体声明（3分钟）
**编辑文件：** `themes/Ying/assets/css/main.css`
**找到第1-14行的字体声明：**
```css
@font-face {
font-family: 'zql';
src: url('../font/zql-v2.woff2') format('woff2'),
url('../font/zql-v2.woff') format('woff');
font-display: swap;
unicode-range: U+0000-007F,
U+4E00-9FFF,
U+2000-206F,
U+3000-303F;
}
```
**替换为：**
```css
@font-face {
font-family: 'zql';
src: url('../font/zql-v2-subset.woff2') format('woff2'),
url('../font/zql-v2-subset.woff') format('woff');
font-display: swap;
}
```
---
### 步骤7：测试验证（5分钟）
**重新构建：**
```bash
hugo --cleanDestinationDir
hugo server -D
```
**访问：** `http://localhost:1313`
**检查清单：**
- [ ] 中文字符正常
- [ ] 英文字符正常
- [ ] 深色模式正常
- [ ] Network面板显示字体大小 ~757KB
---
### 步骤8：提交代码（2分钟）
```bash
git add themes/Ying/assets/css/main.css
git add themes/Ying/static/font/zql-v2-subset.*
git commit -m "perf: 字体子集化优化 - 减少37%"
git push origin main
```
---
## 🐛 故障排除
### 问题1：字符显示为方块
**解决方案：** 重新运行子集化脚本
### 问题2：字体文件404
**解决方案：** 检查CSS路径，清理Hugo缓存
### 问题3：Python脚本运行失败
**解决方案：** 检查Python版本和依赖
---
## 🔄 回滚方案
```bash
# 恢复原始字体
cp themes/Ying/static/font/zql-v2.woff2.backup themes/Ying/static/font/zql-v2.woff2
cp themes/Ying/static/font/zql-v2.woff.backup themes/Ying/static/font/zql-v2.woff
# 恢复CSS
git checkout themes/Ying/assets/css/main.css
```
---
## 📊 操作时间
- 步骤1：备份字体 - 2分钟
- 步骤2：安装依赖 - 3分钟
- 步骤3：构建Hugo - 2分钟
- 步骤4：运行子集化 - 5分钟
- 步骤5：验证文件 - 1分钟
- 步骤6：更新CSS - 3分钟
- 步骤7：测试验证 - 5分钟
- 步骤8：提交代码 - 2分钟
**总计：约23分钟**
---
**字体优化手动指南完成！** 🎉
**按照步骤操作即可完成字体优化！**
docs/archive/主题与内容/性能优化（历史）/16-实施总结报告.md
+316
View File
@@ -0,0 +1,316 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 16-实施总结报告
**创建日期：** 2026-06-03
**版本：** v1.0
**报告类型：** 性能优化实施总结
**项目状态：** ✅ 已完成
---
## 📋 项目概述
### 项目目标
对Hugo主题Ying进行全面性能优化，包括：
1. JS按需加载优化
2. 字体子集化优化
3. GitHub Actions自动化
### 优化效果
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **总体资源** | ~3MB | ~1.5MB | ⚡ -50% |
| **加载速度** | 慢 | 快 | ⚡ +40% |
| **Lighthouse** | 60 | 75-80 | ⚡ +33% |
---
## ✅ 已完成的工作
### 1. JS按需加载优化（第1步）
**完成时间：** 2026-06-03
**实施耗时：** 约2小时
**优化效果：**
- 首页JS：800KB → 350KB（⚡ -56%）
- 文章页JS：800KB → 450KB（⚡ -44%）
**主要工作：**
- ✅ JS代码拆分为4个bundle
- ✅ 核心JS始终加载（~200KB）
- ✅ 页面特定JS按需加载（~180KB）
- ✅ 非关键JS延迟加载（~25KB）
- ✅ PJAX完美适配
**修改文件：**
- `themes/Ying/layouts/partials/footer.html`
- `themes/Ying/assets/js/modules/mypjax.js`
---
### 2. 字体子集化优化（第2步）
**完成时间：** 2026-06-03
**实施耗时：** 约1.5小时
**优化效果：**
- 字体大小：1.2MB → 757KB（⚡ -37%）
**主要工作：**
- ✅ 使用Python fonttools提取字符
- ✅ 生成子集字体（2,485个字符）
- ✅ 更新CSS字体声明
- ✅ 保持所有字符正常显示
**修改文件：**
- `themes/Ying/assets/css/main.css`
- `themes/Ying/static/font/zql-v2-subset.woff2`
- `themes/Ying/static/font/zql-v2-subset.woff`
- `themes/Ying/static/font/used_chars.txt`
---
### 3. GitHub Actions自动化（第3步）
**完成时间：** 2026-06-03
**实施耗时：** 约1小时
**自动化程度：** 100%
**主要工作：**
- ✅ 创建字体子集化工作流
- ✅ 配置自动触发条件
- ✅ 与deploy.yml完美协调
- ✅ 智能检测变更
- ✅ 自动部署到UpYun
**创建文件：**
- `.github/workflows/subset-fonts.yml`
- `requirements.txt`
---
## 📊 技术实现
### JS优化策略
```
core.js (200KB) - 始终加载
├── UIkit
├── 图标字体
├── 图片灯箱
├── 工具函数
├── 搜索功能
├── 浮动工具
├── 进度条
├── PJAX
└── 主题主逻辑
page-only.js (180KB) - 文章详情页
├── Artalk评论
├── 段落评论
└── 打赏功能
deferred.js (25KB) - 延迟加载
├── Toast消息
└── 图片懒加载
infinite-scroll.js (20KB) - 首页（如果启用）
tiaozhuan.js (8KB) - 特定页面
```
---
### 字体优化策略
```
原始字体（1.2MB）
├── 20,000+ 字符
└── 完整中文字符集
子集字体（757KB）
├── 2,485 个字符
├── 常用中文字符
├── 英文字母和数字
├── 常用标点符号
└── 特殊符号
优化效果：-37%
```
---
### 自动化流程
```
用户push内容更新
↓
deploy.yml（部署文章）
↓
subset-fonts.yml（优化字体）
↓
deploy.yml（部署新字体）
↓
✅ 完成！
```
---
## 🎯 项目亮点
### 1. 性能显著提升
- ✅ 资源减少50%
- ✅ 加载速度提升40%
- ✅ Lighthouse 75-80分
- ✅ 用户体验大幅改善
### 2. 完全自动化
- ✅ GitHub Actions自动运行
- ✅ 智能检测变更
- ✅ 无需手动干预
- ✅ 节省时间和精力
### 3. 智能优化
- ✅ 只在需要时优化
- ✅ 避免不必要的部署
- ✅ 节省资源和成本
- ✅ 保持系统高效
### 4. 完整文档
- ✅ 16份详细文档
- ✅ 覆盖所有场景
- ✅ 故障排除指南
- ✅ 最佳实践说明
---
## 📁 文档清单
### 核心文档（3份）
- ✅ 01-项目完成总结.md
- ✅ 02-方案1完成总结.md
- ✅ 03-三步优化完整指南.md
### 优化实施（4份）
- ✅ 04-JS按需加载优化.md
- ✅ 05-PJAX适配说明.md
- ✅ 06-PJAX修复总结.md
- ✅ 07-字体子集化优化.md
### 自动化（3份）
- ✅ 08-GitHub-Actions使用指南.md
- ✅ 09-Actions修复指南.md
- ✅ 10-提交指南.md
### 测试验证（2份）
- ✅ 11-JS优化测试指南.md
- ✅ 12-字体优化测试指南.md
### 详细方案（4份）
- ✅ 13-主题全面优化分析.md
- ✅ 14-JS优化最终方案.md
- ✅ 15-字体优化手动指南.md
- ✅ 16-实施总结报告.md（本文件）
---
## 💡 后续使用
### 日常开发
```bash
# 发布新文章
git add content/posts/new-article.md
git commit -m "feat: new article"
git push origin main
# 等待自动化（3-10分钟）
# - deploy.yml：部署文章
# - subset-fonts.yml：优化字体（如果需要）
# - deploy.yml：部署新字体（如果需要）
```
### 监控系统
```bash
# 查看GitHub Actions
https://github.com/zqlit/blog/actions
# 查看工作流状态
- Deploy to Production（部署）
- Font Subset Optimization（字体优化）
```
### 性能测试
```bash
# 每月测试一次
# 使用Chrome DevTools的Lighthouse
# 或者：https://pagespeed.web.dev/
# 记录：Performance、FCP、LCP、TTI
```
---
## 🎓 学到了什么？
### 技术技能
- ✅ JavaScript代码拆分
- ✅ 字体子集化技术
- ✅ GitHub Actions工作流
- ✅ Hugo静态站点优化
### DevOps实践
- ✅ CI/CD流程设计
- ✅ 自动化部署
- ✅ 工作流协调
- ✅ 性能监控
---
## 🏆 成就解锁
- ⚡ **性能优化大师** - 资源减少50%
- 🤖 **自动化专家** - 完整CI/CD流程
- 🚀 **前端优化师** - Lighthouse 75-80分
- 💡 **DevOps工程师** - GitHub Actions精通
---
## 🎊 项目完成
**恭喜你完成了完整的Hugo博客性能优化和自动化系统！**
- ✅ 性能提升50%
- ✅ 加载速度提升40%
- ✅ Lighthouse 75-80分
- ✅ 完全自动化
- ✅ 生产就绪
**现在可以专注于创作优质内容了！** 🚀
---
**项目完成时间：** 2026-06-03
**总耗时：** 约4.5小时
**优化效果：** 性能提升50%
**自动化程度：** 100%
**维护成本：** 0（完全自动化）
**祝你博客越办越好！** 🎉
---
**实施总结报告完成！** 🎉
**所有16份文档已创建！**
docs/archive/主题与内容/性能优化（历史）/Markdown表格样式使用指南.md
+405
View File
@@ -0,0 +1,405 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# Ying主题 Markdown 表格样式使用指南
**创建日期：** 2026-06-03
**版本：** v2.0（重新设计）
**状态：** ✅ 已实现
---
## 📋 表格样式概述
### 设计理念
**完全符合Ying主题风格：**
- ✅ **圆角12px** - 与blockquote一致
- ✅ **毛玻璃效果** - 与.main容器一致
- ✅ **柔和阴影** - 层次丰富不突兀
- ✅ **透明边框** - rgba颜色更自然
- ✅ **深色模式** - 柔和的rgba过渡
- ✅ **斑马条纹** - 提升可读性
- ✅ **悬停效果** - 交互友好
- ✅ **响应式设计** - 移动端自动横向滚动
- ✅ **多种变体** - 紧凑型、无边框、高亮
### 设计参考
**参考元素：**
- blockquote（圆角、阴影、边框风格）
- .main容器（毛玻璃效果）
- 代码块（背景、边框风格）
---
## 🎨 浅色模式设计
### 配色方案
| 元素 | 颜色 | 说明 |
|------|------|------|
| **表格背景** | `rgba(255, 255, 255, 0.95)` | 毛玻璃效果 |
| **表格边框** | `rgba(0, 0, 0, 0.08)` | 透明柔和 |
| **表格阴影** | `0 8px 24px rgba(0, 0, 0, 0.06)` | 层次丰富 |
| **表头背景** | 渐变 `rgba(0,0,0,0.03)` → `rgba(0,0,0,0.01)` | 微妙渐变 |
| **表头文字** | `rgba(30, 30, 30, 0.92)` | 深灰，可读性强 |
| **表头边框** | `rgba(0, 0, 0, 0.1)` | 底部2px |
| **单元格背景** | 白色 / `rgba(0,0,0,0.015)` | 斑马纹 |
| **单元格文字** | `rgba(30, 30, 30, 0.85)` | 中灰 |
| **单元格边框** | `rgba(0, 0, 0, 0.05)` | 浅灰底边 |
| **悬停背景** | `rgba(0, 0, 0, 0.04)` | 柔和高亮 |
| **链接颜色** | 使用主题链接色 | 与正文一致 |
| **代码背景** | `rgba(0, 0, 0, 0.04)` | 浅灰 |
| **代码文字** | `rgba(30, 30, 30, 0.9)` | 深灰 |
### 设计特点
- ✅ **圆角12px** - 与blockquote完全一致
- ✅ **毛玻璃** - `backdrop-filter: blur(8px)`
- ✅ **透明边框** - 使用rgba而不是实色
- ✅ **柔和阴影** - 避免突兀感
---
## 🌙 深色模式设计
### 配色方案
| 元素 | 颜色 | 说明 |
|------|------|------|
| **表格背景** | `rgba(15, 23, 42, 0.95)` | 深蓝毛玻璃 |
| **表格边框** | `rgba(148, 163, 184, 0.18)` | 透明灰边框 |
| **表格阴影** | `0 10px 28px rgba(0, 0, 0, 0.22)` | 更深的阴影 |
| **表头背景** | 渐变 `rgba(30,41,59,0.92)` → `rgba(15,23,42,0.78)` | 深蓝渐变 |
| **表头文字** | `rgba(226, 232, 240, 0.96)` | 浅灰白 |
| **表头边框** | `rgba(148, 163, 184, 0.2)` | 深灰底边 |
| **单元格背景** | 深蓝 / `rgba(30,41,59,0.5)` | 深色斑马纹 |
| **单元格文字** | `rgba(226, 232, 240, 0.9)` | 浅灰 |
| **单元格边框** | `rgba(148, 163, 184, 0.1)` | 深灰底边 |
| **悬停背景** | `rgba(30, 41, 59, 0.8)` | 柔和高亮 |
| **链接颜色** | 使用主题深色链接色 | 与正文一致 |
| **代码背景** | `rgba(148, 163, 184, 0.15)` | 深灰 |
| **代码文字** | `rgba(226, 232, 240, 0.95)` | 浅灰白 |
### 设计特点
- ✅ **柔和过渡** - 使用rgba透明度
- ✅ **避免纯黑** - 深蓝灰更舒适
- ✅ **层次分明** - 半透明边框和阴影
- ✅ **护眼设计** - 减少对比度
---
## 🎯 与主题一致性
### 对比其他元素
| 元素 | 圆角 | 边框 | 阴影 | 背景 |
|------|------|------|------|------|
| **blockquote** | 12px | rgba透明 | 柔和 | 渐变 |
| **.main容器** | 8px | rgba透明 | 层次丰富 | 毛玻璃 |
| **表格** | **12px** | **rgba透明** | **柔和** | **毛玻璃** ✅ |
| **代码块** | 6px | rgba透明 | 无 | 浅灰 |
**表格风格与blockquote高度一致！** ✅
---
## 📱 响应式设计
### 移动端优化（<768px）
**自动处理：**
- ✅ 表格自动横向滚动
- ✅ 第一列固定（sticky定位）
- ✅ 减小内边距（12px → 10px）
- ✅ 减小字体（0.85em）
- ✅ 圆角调整（8px）
- ✅ 触摸友好
**效果：**
- ✅ 在小屏幕完整查看表格
- ✅ 第一列始终可见
- ✅ 流畅滚动体验
- ✅ 性能优化
---
## 🎨 表格变体
### 1. 紧凑型表格（.compact）
**适用场景：** 数据密集型，需要节省空间
**Markdown语法：**
```markdown
| 列1 | 列2 | 列3 | {.compact}
|-----|-----|-----|---------
| 数据 | 数据 | 数据 |
```
**CSS类：** `table.compact`
**效果：**
- ✅ 更小的内边距（10px vs 14px）
- ✅ 更小的字体（0.9em）
- ✅ 保持主题风格
---
### 2. 无边框表格（.borderless）
**适用场景：** 简洁风格，不需要明显边框
**Markdown语法：**
```markdown
| 列1 | 列2 | 列3 | {.borderless}
|-----|-----|-----|-------------
| 数据 | 数据 | 数据 |
```
**CSS类：** `table.borderless`
**效果：**
- ✅ 无外边框
- ✅ 无阴影
- ✅ 透明背景
- ✅ 仅有底部分隔线
- ✅ 更加简洁
---
### 3. 高亮表格（.highlight）
**适用场景：** 需要突出的重要表格
**Markdown语法：**
```markdown
| 列1 | 列2 | 列3 | {.highlight}
|-----|-----|-----|------------
| 数据 | 数据 | 数据 |
```
**CSS类：** `table.highlight`
**效果：**
- ✅ 左侧4px边框（浅色：黑色60%透明，深色：灰色70%透明）
- ✅ 更明显的表头背景
- ✅ 更突出的表头边框
- ✅ 引起注意
---
## 📝 使用示例
### 示例1：基础表格
```markdown
| 姓名 | 年龄 | 职业 |
|------|------|------|
| 张三 | 25 | 工程师 |
| 李四 | 30 | 设计师 |
| 王五 | 28 | 产品经理 |
```
**效果：**
- ✅ 圆角12px卡片
- ✅ 毛玻璃背景
- ✅ 斑马条纹
- ✅ 悬停高亮
---
### 示例2：包含代码和链接
```markdown
| 工具 | 版本 | 用途 |
|------|------|------|
| Node.js | `18.0+` | JavaScript运行环境 |
| [Hugo](https://gohugo.io) | `0.128.2` | 静态站点生成器 |
| Git | `2.30+` | 版本控制 |
```
**效果：**
- ✅ 代码块样式（圆角6px，浅灰背景）
- ✅ 链接样式（虚线下划线，悬停变实线）
- ✅ 与主题链接风格一致
---
### 示例3：古风官职表格
```markdown
| 品级 | 官职 | 俸禄 | 说明 |
|------|------|------|------|
| 正一品 | 太师 | 2000 | 最高官职 |
| 从一品 | 太尉 | 1400 | 军事长官 |
| 正二品 | 参知政事 | 1050 | 副宰相 |
| 从二品 | 节度使 | 800 | 地方军政长官 |
| 正三品 | 御史中丞 | 600 | 监察官员 |
| 从三品 | 秘书监 | 480 | 文书管理 |
| 正四品 | 谏议大夫 | 380 | 谏官 |
| 从四品 | 侍读学士 | 300 | 皇帝顾问 |
| 正五品 | 给事中 | 240 | 审查奏章 |
| 从五品 | 知州 | 190 | 地方长官 |
| 正六品 | 侍御史 | 150 | 监察官员 |
| 从六品 | 通判 | 115 | 副地方长官 |
| 正七品 | 知县 | 85 | 县级长官 |
| 从七品 | 殿中侍御史 | 60 | 宫廷监察 |
| 正八品 | 大理评事 | 40 | 司法官员 |
| 从八品 | 录事参军 | 25 | 文书官员 |
| 正九品 | 主簿 | 15 | 县级文书 |
| 从九品 | 司户参军 | 5 | 户籍管理 |
| — | 庶民 | 0 | 普通百姓 |
```
**效果：**
- ✅ 20行数据清晰展示
- ✅ 斑马纹便于阅读
- ✅ 深色模式完美适配
- ✅ 与古风主题协调
---
## 💡 使用技巧
### 1. 对齐方式
```markdown
| 左对齐 | 居中对齐 | 右对齐 |
|:-------|:--------:|-------:|
| 数据 | 数据 | 数据 |
```
**效果：**
- ✅ `:---` 左对齐（默认）
- ✅ `:---:` 居中对齐
- ✅ `---:` 右对齐
---
### 2. 表格内换行
```markdown
| 列1 | 列2 |
|-----|-----|
| 第一行<br>第二行 | 数据 |
```
**效果：**
- ✅ 使用 `<br>` 标签换行
- ✅ 在单元格内显示多行
---
### 3. 代码和链接混合
```markdown
| 工具 | 版本 | 链接 |
|------|------|------|
| Hugo | `0.128.2` | [官网](https://gohugo.io) |
```
**效果：**
- ✅ 代码块特殊样式
- ✅ 链接虚线下划线
- ✅ 悬停效果
---
## 🎨 自定义样式
### 修改圆角
```css
.post-content table {
border-radius: 16px; /* 更大的圆角 */
}
```
### 修改毛玻璃强度
```css
.post-content table {
backdrop-filter: blur(12px); /* 更强的模糊 */
}
```
### 修改阴影
```css
.post-content table {
box-shadow: 0 12px 32px rgba(0, 0, 0, 0.08); /* 更大的阴影 */
}
```
### 修改深色模式透明度
```css
[data-theme="dark"] .post-content table {
background: rgba(15, 23, 42, 0.98); /* 更不透明 */
}
```
---
## ✅ 功能清单
### 基础功能
- [x] 表头样式（微妙渐变）
- [x] 斑马条纹
- [x] 悬停效果
- [x] 圆角12px（与blockquote一致）
- [x] 毛玻璃效果
- [x] 深色模式
### 进阶功能
- [x] 响应式设计
- [x] 移动端横向滚动
- [x] 第一列固定
- [x] 代码块样式
- [x] 链接样式
- [x] 图片样式
### 变体样式
- [x] 紧凑型表格（.compact）
- [x] 无边框表格（.borderless）
- [x] 高亮表格（.highlight）
### 主题一致性
- [x] 与blockquote风格一致
- [x] 与.main容器风格一致
- [x] 使用主题CSS变量
- [x] 深色模式配色协调
---
## 🎉 总结
### 设计优势
1. **完全符合主题** - 与blockquote、.main容器风格统一
2. **视觉舒适** - 毛玻璃、柔和阴影、透明边框
3. **深色模式友好** - rgba颜色、柔和过渡
4. **交互体验好** - 悬停效果、平滑动画
5. **响应式完善** - 移动端优化
6. **易于定制** - CSS变量
### 使用建议
1. **基础表格** - 使用默认样式
2. **数据密集** - 使用紧凑型（.compact）
3. **简洁风格** - 使用无边框（.borderless）
4. **重要表格** - 使用高亮（.highlight）
5. **移动端** - 自动响应式，无需特殊处理
---
**表格样式设计完成！完全符合Ying主题风格！** 🎉
**现在可以在Markdown文章中使用表格了！**
docs/archive/主题与内容/性能优化（历史）/README.md
+200
View File
@@ -0,0 +1,200 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../../架构总览.md)。
# 📚 性能优化文档索引
**整理日期：** 2026-06-03
**项目：** Hugo博客性能优化
**优化效果：** 性能提升50%，Lighthouse 75-80分
---
## 📁 文档分类
### 🎯 一、项目总结（3份）
| 序号 | 文档名称 | 创建日期 | 说明 |
|------|---------|---------|------|
| 1 | [01-项目完成总结.md](./01-项目完成总结.md) | 2026-06-03 | 整个项目完成情况总结 |
| 2 | [02-方案1完成总结.md](./02-方案1完成总结.md) | 2026-06-03 | JS和字体优化总结 |
| 3 | [03-三步优化完整指南.md](./03-三步优化完整指南.md) | 2026-06-03 | 三步优化的完整指南 |
---
### 🔧 二、优化实施（4份）
| 序号 | 文档名称 | 创建日期 | 说明 |
|------|---------|---------|------|
| 4 | [04-JS按需加载优化.md](./04-JS按需加载优化.md) | 2026-06-03 | JS代码拆分和按需加载 |
| 5 | [05-PJAX适配说明.md](./05-PJAX适配说明.md) | 2026-06-03 | PJAX导航适配 |
| 6 | [06-PJAX修复总结.md](./06-PJAX修复总结.md) | 2026-06-03 | PJAX修复详情 |
| 7 | [07-字体子集化优化.md](./07-字体子集化优化.md) | 2026-06-03 | 字体优化方案和实施 |
---
### 🤖 三、GitHub Actions自动化（3份）
| 序号 | 文档名称 | 创建日期 | 说明 |
|------|---------|---------|------|
| 8 | [08-GitHub-Actions使用指南.md](./08-GitHub-Actions使用指南.md) | 2026-06-03 | Actions详细使用说明 |
| 9 | [09-Actions修复指南.md](./09-Actions修复指南.md) | 2026-06-03 | 常见问题和修复方法 |
| 10 | [10-提交指南.md](./10-提交指南.md) | 2026-06-03 | Git提交最佳实践 |
---
### 🧪 四、测试验证（2份）
| 序号 | 文档名称 | 创建日期 | 说明 |
|------|---------|---------|------|
| 11 | [11-JS优化测试指南.md](./11-JS优化测试指南.md) | 2026-06-03 | JS优化测试方法 |
| 12 | [12-字体优化测试指南.md](./12-字体优化测试指南.md) | 2026-06-03 | 字体优化测试方法 |
---
### 📋 五、详细方案（4份）
| 序号 | 文档名称 | 创建日期 | 说明 |
|------|---------|---------|------|
| 13 | [13-主题全面优化分析.md](./13-主题全面优化分析.md) | 2026-06-03 | Ying主题优化分析 |
| 14 | [14-JS优化最终方案.md](./14-JS优化最终方案.md) | 2026-06-03 | JS优化详细技术方案 |
| 15 | [15-字体优化手动指南.md](./15-字体优化手动指南.md) | 2026-06-03 | 字体优化手动操作 |
| 16 | [16-实施总结报告.md](./16-实施总结报告.md) | 2026-06-03 | 整体实施情况报告 |
---
## 📊 文档统计
### 按类别统计
| 类别 | 数量 | 说明 |
|------|------|------|
| 项目总结 | 3份 | 整体完成情况 |
| 优化实施 | 4份 | 具体优化方法 |
| 自动化 | 3份 | GitHub Actions |
| 测试验证 | 2份 | 测试方法和结果 |
| 详细方案 | 4份 | 技术细节 |
| **总计** | **16份** | 完整文档体系 |
---
## 🎯 快速查找指南
### 场景1：了解项目整体情况
**推荐阅读顺序：**
1. [01-项目完成总结.md](./01-项目完成总结.md) - 快速了解全貌
2. [03-三步优化完整指南.md](./03-三步优化完整指南.md) - 详细优化内容
---
### 场景2：实施JS优化
**推荐阅读顺序：**
1. [04-JS按需加载优化.md](./04-JS按需加载优化.md) - 了解优化方法
2. [05-PJAX适配说明.md](./05-PJAX适配说明.md) - 适配PJAX
3. [11-JS优化测试指南.md](./11-JS优化测试指南.md) - 测试验证
---
### 场景3：实施字体优化
**推荐阅读顺序：**
1. [07-字体子集化优化.md](./07-字体子集化优化.md) - 了解优化方法
2. [15-字体优化手动指南.md](./15-字体优化手动指南.md) - 手动操作
3. [12-字体优化测试指南.md](./12-字体优化测试指南.md) - 测试验证
---
### 场景4：配置GitHub Actions
**推荐阅读顺序：**
1. [08-GitHub-Actions使用指南.md](./08-GitHub-Actions使用指南.md) - 使用方法
2. [09-Actions修复指南.md](./09-Actions修复指南.md) - 故障排除
3. [10-提交指南.md](./10-提交指南.md) - 提交最佳实践
---
### 场景5：遇到问题需要排查
**推荐阅读顺序：**
1. [09-Actions修复指南.md](./09-Actions修复指南.md) - Actions问题
2. [06-PJAX修复总结.md](./06-PJAX修复总结.md) - PJAX问题
3. [11-JS优化测试指南.md](./11-JS优化测试指南.md) - JS问题
4. [12-字体优化测试指南.md](./12-字体优化测试指南.md) - 字体问题
---
## 📈 优化效果总览
### 性能提升数据
| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| **JS（首页）** | 800KB | 350KB | ⚡ -56% |
| **JS（文章页）** | 800KB | 450KB | ⚡ -44% |
| **字体** | 1.2MB | 757KB | ⚡ -37% |
| **总体资源（首页）** | ~3MB | ~1.5MB | ⚡ -50% |
| **总体资源（文章页）** | ~3MB | ~1.6MB | ⚡ -47% |
| **Lighthouse** | 60 | 75-80 | ⚡ +25-33% |
---
## 🔄 文档维护
### 定期检查（每季度）
- [ ] 检查文档是否仍然准确
- [ ] 更新过时的信息
- [ ] 添加新的优化经验
- [ ] 整理重复内容
### 文档版本控制
所有文档都包含版本信息和创建日期，便于追踪变更。
---
## 💡 使用建议
### 新手入门
1. 先阅读 [01-项目完成总结.md](./01-项目完成总结.md)
2. 了解整体优化效果
3. 根据需要查阅具体文档
### 技术实施
1. 按照对应类别的文档顺序阅读
2. 先理解原理，再动手实施
3. 遇到问题查看故障排除文档
### 日常维护
1. 无需手动维护（完全自动化）
2. 定期查看GitHub Actions运行状态
3. 每月进行一次性能测试
---
## 📞 获取帮助
### 文档未覆盖的问题
1. 查看GitHub Actions日志
2. 检查Hugo官方文档
3. 搜索相关技术问题
### 需要更新文档
1. 编辑对应的Markdown文件
2. 更新版本号和日期
3. 提交到Git仓库
---
**文档整理完成：** 2026-06-03
**总文档数：** 16份
**覆盖范围：** 完整的优化和自动化体系
**维护状态：** 生产就绪
**祝你使用愉快！** 🎉
docs/archive/主题与内容/深色模式表格修复指南.md
+291
View File
@@ -0,0 +1,291 @@
> 📦 **本文档已归档**（2026-10-06）。它记录的是**当时的工作过程与结论**，可能已被后续决策推翻。
> **请勿据此判断当前架构** —— 现行架构唯一事实源是 [`架构总览.md`](../../../架构总览.md)。
# 深色模式表格样式修复指南
## 🔍 问题诊断
**症状：** 深色模式表格样式没有生效
**可能原因：**
1. 浏览器缓存
2. Hugo缓存
3. CSS文件未正确更新
4. 查看的位置不正确
---
## 🚀 完整修复步骤
### 步骤1：确认CSS已更新
**我已经确认CSS文件已更新：**
```
文件：themes/Ying/assets/css/main.css
位置：第723-726行
内容：
[data-theme="dark"] .post-content th {
color: rgba(203, 213, 225, 0.85);
border-bottom-color: rgba(148, 163, 184, 0.15);
}
```
✅ **代码已正确修改**
---
### 步骤2：清理所有缓存
**执行以下命令：**
```bash
cd E:\GitHub\blog
# 1. 清理Hugo构建缓存
hugo --cleanDestinationDir
# 2. 删除public目录（如果存在）
rd /s /q public 2>nul
# 3. 删除Hugo缓存
rd /s /q resources 2>nul
# 4. 重新构建
hugo server -D --noHTTPCache
```
---
### 步骤3：浏览器强制刷新
**Chrome/Edge：**
1. 按 `F12` 打开开发者工具
2. 右键点击刷新按钮
3. 选择 **"清空缓存并硬性重新加载"**
**或者：**
- 按 `Ctrl + Shift + R`
- 或 `Ctrl + F5`
**Firefox：**
- 按 `Ctrl + Shift + R`
---
### 步骤4：禁用浏览器缓存（开发时）
**Chrome DevTools设置：**
1. 按 `F12` 打开开发者工具
2. 切换到 **Network** 面板
3. 勾选 **Disable cache**
4. 保持DevTools打开
5. 刷新页面
---
## 🧪 验证方法
### 方法1：检查CSS加载
**Chrome DevTools：**
1. 按 `F12`
2. 切换到 **Elements** 面板
3. 找到 `<link>` 标签加载CSS
4. 点击CSS链接查看内容
5. 搜索 `post-content th`
6. 确认颜色值是 `rgba(203, 213, 225, 0.85)`
### 方法2：检查元素样式
**Chrome DevTools：**
1. 按 `F12`
2. 点击 **选择元素** 工具（左上角箭头）
3. 点击表格的表头
4. 查看 **Styles** 面板
5. 找到 `color` 属性
6. 确认值
### 方法3：查看源代码
**查看CSS文件：**
```bash
# 在命令行查看
type themes\Ying\assets\css\main.css | findstr "post-content th"
```
**应该看到：**
```css
[data-theme="dark"] .post-content th {
color: rgba(203, 213, 225, 0.85);
border-bottom-color: rgba(148, 163, 184, 0.15);
}
```
---
## 🎨 当前的颜色值
### 深色模式表格配色
| 元素 | 颜色 | 说明 |
|------|------|------|
| **表头文字** | `rgba(203, 213, 225, 0.85)` | 柔和灰白 |
| **单元格文字** | `rgba(203, 213, 225, 0.8)` | 稍暗一点 |
| **表头边框** | `rgba(148, 163, 184, 0.15)` | 透明灰 |
| **单元格边框** | `rgba(148, 163, 184, 0.08)` | 更透明 |
| **表头背景** | 渐变深蓝 | `rgba(30,41,59,0.92)` → `rgba(15,23,42,0.78)` |
| **表格背景** | 深蓝毛玻璃 | `rgba(15, 23, 42, 0.95)` |
---
## 🔧 备用方案
### 如果还是没有变化
**方案A：添加更高优先级的样式**
在CSS文件末尾添加：
```css
/* 强制覆盖深色模式表格样式 */
[data-theme="dark"] .post-content table th {
color: rgba(203, 213, 225, 0.85) !important;
border-bottom-color: rgba(148, 163, 184, 0.15) !important;
}
```
**方案B：使用内联样式测试**
在Markdown文章中使用HTML：
```html
<div data-theme="dark">
<table>
<thead>
<tr>
<th style="color: rgba(203, 213, 225, 0.85);">表头</th>
</tr>
</thead>
</table>
</div>
```
---
## 📋 测试表格
### 创建测试文章
**新建文件：** `content/posts/test-table.md`
```markdown
---
title: "表格样式测试"
date: 2026-06-03
---
## 测试表格
| 项目 | 浅色模式 | 深色模式 | 状态 |
|------|---------|---------|------|
| **表头文字** | 深灰 | 柔和灰白 | 测试中 |
| **单元格文字** | 中灰 | 柔和灰白 | 测试中 |
| **边框** | 浅灰 | 透明灰 | 测试中 |
| **背景** | 白色 | 深蓝毛玻璃 | 测试中 |
### 步骤
1. 访问此页面
2. 点击头像切换深色模式
3. 检查表头文字颜色
```
---
## 🎯 检查清单
### 缓存清理
- [ ] Hugo缓存已清理
- [ ] public目录已删除
- [ ] 浏览器缓存已清理
- [ ] 强制刷新已执行
### CSS验证
- [ ] CSS文件已更新（第723-726行）
- [ ] 颜色值正确：`rgba(203, 213, 225, 0.85)`
- [ ] CSS已正确加载到浏览器
### 功能测试
- [ ] 创建了测试表格
- [ ] 切换到深色模式
- [ ] 表头文字不刺眼
- [ ] 整体视觉舒适
---
## 🔄 进一步调整
### 如果颜色还是太亮
**调整选项1（更柔和）：**
```css
color: rgba(180, 190, 205, 0.8)
```
**调整选项2（更透明）：**
```css
color: rgba(203, 213, 225, 0.7)
```
**调整选项3（更暗）：**
```css
color: rgba(160, 175, 195, 0.85)
```
---
## 💡 常见问题
### Q1：为什么浏览器缓存这么顽固？
**A1：** 现代浏览器会积极缓存CSS/JS文件。开发时建议：
- 始终打开DevTools
- 勾选Disable cache
- 使用强制刷新
### Q2：Hugo缓存在哪里？
**A2：** Hugo缓存位置：
- Windows: `%TEMP%\hugo_cache`
- 或项目目录的 `resources` 文件夹
### Q3：如何确认CSS已加载？
**A3：** 在Chrome DevTools中：
- Elements面板 → 搜索CSS选择器
- 或Network面板 → 查看CSS请求
---
## 🎉 完成确认
### 成功标志
- ✅ 浏览器强制刷新后生效
- ✅ 表头文字为柔和灰白色
- ✅ 不刺眼，视觉舒适
- ✅ 深色模式整体协调
### 如果还是不行
**联系我，我会：**
1. 检查CSS文件完整性
2. 提供内联样式方案
3. 或创建独立的测试文件
---
**文档版本：** v1.0
**创建日期：** 2026-06-03
**适用问题：** 深色模式表格样式未生效