博客框架使用手册

1. 项目定位与价值主张

这是一个基于 Hexo + Butterfly 主题 的现代化静态博客系统，具备以下推广优势：

访问快：静态页面直接分发，首屏加载快，移动端体验好。
成本低：无需自建后端服务，托管和维护成本可控。
可扩展：评论、统计、分享、搜索等能力通过 API 插件化接入。
SEO 友好：天然支持文章归档、标签、分类、RSS、Sitemap。
内容优先：创作者只需要写 Markdown，即可完成发布。

2. 技术栈总览（前后端、框架、服务）

2.1 前端技术栈（浏览器侧）

主题框架：hexo-theme-butterfly
模板/渲染：Pug / EJS / Stylus（主题内部）
交互语言：JavaScript（原生 + fetch）
搜索交互：本地搜索脚本（读取 search.xml）
页面增强：PJAX、代码高亮、图片灯箱、深色模式、复制版权提示等

2.2 “后端”技术栈（构建与服务侧）

该博客是“静态站”架构，没有传统业务后端（如 Java/Spring、Node API Server）。

静态站框架：Hexo 7.3.0
Node 生态：npm + Hexo 插件体系
构建命令：hexo generate
本地预览：hexo server
部署机制：hexo-deployer-git → GitHub Pages 仓库
域名：harrysong.online（CNAME）

2.3 内容与数据层

文章内容：source/_posts/**/*.md
页面内容：source/about、source/comments 等
结构化数据：source/_data/*.yml（如 about/link）
站点配置：_config.yml
主题配置：_config.butterfly.yml

3. 已启用 API / 外部服务清单

能力	服务/API	当前状态	作用
评论系统	Twikoo (`/.netlify/functions/twikoo`)	已启用	评论发布、加载、评论计数
访问统计	Busuanzi API	已启用	站点 UV/PV、页面 PV
行为分析	Google Analytics (`G-NSEYEGN2Q9`)	已启用	流量来源、用户行为、页面效果分析
社交分享	AddToAny	已启用	一键分享到 Twitter/微信/微博等
站内搜索	`search.xml`（本地索引）	已启用	前端本地全文检索
RSS 订阅	`atom.xml`	已启用	订阅分发、内容触达
图片静态资源	`static.harrysong.online`	已启用	图像资源分发、内容展示
徽章接口	`img.shields.io`	已启用	页脚运行状态徽章

4. 整体架构图

flowchart LR
  subgraph AuthorSide[内容生产端]
    A1[作者写 Markdown]
    A2[维护 YAML 数据]
    A3[修改 Hexo/主题配置]
  end

  subgraph BuildSide[构建与发布端]
    B1[Hexo Generate]
    B2[生成静态资源<br/>HTML/CSS/JS/XML]
    B3[Hexo Deploy Git]
    B4[GitHub Pages]
  end

  subgraph RuntimeSide[访问与服务端]
    C1[用户浏览器]
    C2[Twikoo 评论 API]
    C3[Busuanzi 统计 API]
    C4[Google Analytics]
    C5[AddToAny 分享]
    C6[静态资源域名/CDN]
  end

  A1 --> B1
  A2 --> B1
  A3 --> B1
  B1 --> B2 --> B3 --> B4 --> C1
  C1 --> C2
  C1 --> C3
  C1 --> C4
  C1 --> C5
  C1 --> C6

5. 发布流程图

flowchart TD
  P1[新建文章 hexo new post] --> P2[编辑 Markdown 正文与 Front-matter]
  P2 --> P3[本地预览 hexo server]
  P3 --> P4{检查通过?}
  P4 -- 否 --> P2
  P4 -- 是 --> P5[生成静态文件 hexo generate]
  P5 --> P6[部署 hexo deploy]
  P6 --> P7[GitHub Pages 更新]
  P7 --> P8[线上可访问 harrysong.online]
  P8 --> P9[GA/Busuanzi 回收数据]

6. 运行时请求链路图

sequenceDiagram
  participant U as 访客浏览器
  participant S as 静态站点(harrysong.online)
  participant T as Twikoo API
  participant B as Busuanzi
  participant G as Google Analytics
  participant A as AddToAny
  participant C as 静态资源域名

  U->>S: 请求页面 HTML
  S-->>U: 返回 HTML/CSS/JS
  U->>C: 拉取图片/静态资源
  U->>T: 加载评论与评论计数
  U->>B: 请求 PV/UV 数据
  U->>G: 上报访问行为事件
  U->>A: 加载分享脚本

7. 功能模块说明

7.1 内容发布模块

支持文章、独立页面、分类、标签、归档。
Markdown 即内容源，降低创作门槛。
Front-matter 可配置 SEO 信息、摘要、标签体系。

7.2 互动模块

评论系统采用 Twikoo，具备轻量化、可迁移、可扩展优势。
留言板页面独立配置（type: envelope），增强用户互动氛围。

7.3 搜索与发现模块

本地搜索基于 search.xml，无需外部搜索引擎也可实现全文检索。
标签页、分类页、归档页形成内容分发网络，提高页面深度访问。

7.4 数据分析模块

Google Analytics：用户来源、路径、停留、转化分析。
Busuanzi：站点 UV/PV 与页面 PV 的轻量展示。

7.5 分发与传播模块

AddToAny 实现社交平台一键分享。
RSS (atom.xml) 支持订阅传播。
Sitemap（插件已安装）支持搜索引擎抓取。

8. 运维与日常使用 SOP（标准操作）

8.1 日常发文

hexo new post 文章标题
编辑 source/_posts/*.md
hexo server 本地检查
hexo generate && hexo deploy 发布上线

8.2 配置修改（导航、评论、统计）

修改 _config.yml（站点级）
修改 _config.butterfly.yml（主题级）
hexo clean && hexo generate && hexo server 验证
hexo deploy 上线

8.3 内容资产管理

文章内图片统一使用 static.harrysong.online，提升访问稳定性。
个人资料与友情链接放在 source/_data/*.yml，便于结构化维护。