一、总体概览

  • 平台与框架：Hexo 7.3.0 + Butterfly 主题（v5.3.5）。
  • 站点定位：技术学习/竞赛记录（密码学/CTF/算法/课程笔记等）+ 生活随笔，中文为主。
  • 展示风格：卡片式列表、顶部大图 Banner、封面图轮换、侧栏多卡片信息（作者、公告、最新评论、归档、标签云、站点信息）。
  • 交互增强：本地搜索、目录（TOC）、相关文章、阅读模式、深色模式切换、PJAX 页面切换、Instant.page 预获取、图片灯箱（medium-zoom）。
  • 评论与统计：Waline（含 PV/UV）+ Disqus 双系统（Waline 为主），文章卡片显示评论数；站点 PV/UV 未启用 Busuanzi（保留为可选）。
  • 多媒体：底部固定 APlayer 播放器（inject 注入）+ 音乐页 aplayerlist 播放清单。
  • 数学与代码：MathJax 渲染公式，highlight.js 高亮，行号与自动换行启用。

二、技术栈与版本

  • Hexo: 7.3.0（package.json hexo 字段与依赖）
  • 主题：hexo-theme-butterfly 5.3.5（themes/butterfly/）
  • 渲染器：
    • @upupming/hexo-renderer-markdown-it-plus（当前 Markdown 渲染主力）
    • hexo-renderer-kramed（亦已安装，存在并行可能的冗余，见改进建议）
    • hexo-renderer-stylus、hexo-renderer-pug
  • 生成/功能插件（节选）：
    • 搜索：hexo-generator-search、hexo-generator-searchdb（两者同时存在，见改进建议）
    • 站点生成：hexo-generator-index、archive、category、tag
    • 部署：hexo-deployer-git
    • 开发：hexo-server
    • 统计/字数：hexo-wordcount
    • 资源与多媒体：hexo-asset-image、hexo-tag-aplayer
    • 加密（可选）：hexo-blog-encrypt（暂未启用）
    • 主题内置/集成：pjax、instant.page、medium-zoom、canvas-nest、snackbar 等
  • 其他：@vercel/analytics 已安装但未在主题注入中显式启用。

三、核心目录结构（简要）

  • 根配置
    • _config.yml：站点全局配置（URL、构建、部署、数学、搜索、高亮、文章资源等）。
    • _config.butterfly.yml：主题配置（导航、封面、UI、交互、评论、统计、特效等）。
  • 内容与数据
    • source/_posts/：文章 Markdown（数量多，覆盖技术、竞赛、随笔等）。
    • source/_data/link.yml：友链数据，按分类展示。
    • source/link/index.md：友链页（type: link）。
    • source/tags/index.md：标签页（type: tags）。
    • source/music/index.md：音乐页（type: music，使用 aplayerlist）。
    • source/schedule/index.md：常驻更新目录页（手工索引若干文章）。
  • 主题目录
    • themes/butterfly/：主题源码、静态资源与内置脚本（包含本地搜索脚本）。

四、主题与 UI 关键设置

  • 导航与菜单
    • LOGO：/img/niu.gif
    • 菜单项：主页、时光轴（archives）、标签、友链
    • 顶部 Banner：index_img 与 default_top_img 均指向 /img/*.jpg|gif，默认封面集较大（94 张 gif）。
  • 列表与封面
    • 首页布局 index_layout: 3（封面与信息左右交错），简介展示长度 500。
    • 封面/侧栏/归档 cover 开启；aside 启用且默认在左侧。
  • 代码块
    • 主题 code_blocks: light、Mac 风格标题、可复制、行内换行。
    • Hexo 使用 highlight.js（行号、wrap）。
  • 文章页
    • TOC：开启且带序号、滚动百分比显示。
    • 版权信息：开启，协议为 CC BY-NC-SA 4.0。
    • 相关文章：开启，最多 6 篇。
    • 上/下一篇分页：顺序模式 1。
  • 侧栏卡片（已启用）
    • 作者卡片（Follow Me 指向 GitHub）
    • 公告（维护日志提示）
    • 最近文章（按更新时间）
    • 最新评论（Waline 聚合）
    • 分类/标签云/归档（月度）
    • 站点信息（文章数、最近推送时间、运行时长可配置）
  • 交互与视觉
    • 深色模式：按钮切换，手动模式。
    • 阅读模式：支持。
    • PJAX：开启；Instant.page：开启；进入过渡动画：开启。
    • 图片灯箱：medium-zoom；Lightbox 在主题中设置为 medium_zoom。
    • 背景特效：canvas-nest（开启，移动端关闭），click_heart（开启）。
    • Snackbar：开启；位置左下。

五、功能清单（结合插件与配置）

1) 搜索

  • 主题：local_search（占位文案“来搜吧来搜吧~”）。
  • 生成器：root _config.yml 配置 search.xml；同时安装了 search 与 searchdb 两个插件（建议二选一）。

2) 评论与访问统计

  • Waline：已配置 serverURL（Vercel 部署后端），开启 pageview & visitor 统计；首页文章卡片展示评论数与 PV。
  • Disqus：配置了 shortname，可作为备份/次要评论系统。
  • 站点级 PV/UV：Busuanzi 在主题配置中注释关闭（可按需启用）。

3) 数学公式

  • MathJax：在主题与站点均开启，单美元行内启用；engine 设为 chtml；支持按页面 Front-matter 控制。

4) 代码高亮

  • highlight.js：行号、自动换行、wrap 开启；主题 code_blocks=light。

5) 多媒体与音乐

  • 页面级：source/music/index.md 使用 {% aplayerlist %} 播放清单。
  • 全站固定：通过主题 inject.bottom 注入 APlayer 与播放列表（随机播放、固定底部、自动播放）。

6) 内容组织与导航

  • TOC、相关文章、上一/下一篇导航、归档（月度）、标签云（随机顺序、上限 40）。
  • 友链：source/_data/link.yml 维护，主题友链样式为 volantis。

7) 性能与体验

  • PJAX、Instant.page 预获取、medium-zoom、snackbar；Lazyload 暂未启用。

8) SEO 与结构化数据

  • Open Graph：开启；结构化数据：开启。
  • 尚未安装/配置 RSS（feed）与 sitemap（站点地图）插件（见改进建议）。

9) 安全与加密

  • hexo-blog-encrypt 已安装，root _config.yml 示例配置注释存在；MathJax 跳过 encrypted/** 渲染；当前未启用文章加密。

10) 部署与运维

  • 部署：hexo-deployer-git 推送到 git@github.com:coperlm/coperlm.github.io.git 的 main 分支。
  • 文章资源：post_asset_folder: true + hexo-asset-image，便于相对路径插图。

六、构建、开发与部署

  • 本地开发（PowerShell）

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    # 一次性安装依赖
    npm install

    # 本地预览（默认 http://localhost:4000）
    npm run server

    # 清理与重新生成
    npm run clean; npm run build

    # 部署（需已配置 SSH Key 并具备仓库写权限）
    npm run deploy

  • 新文档与资源组织

    • 新文章：hexo new "标题"（或直接在 source/_posts/ 下添加 .md）。
    • 文章素材：置于与文章同名的资源目录（post_asset_folder=true），图片可用相对路径引用。
    • 友链：编辑 source/_data/link.yml。
    • 专题页：tags/link/music/schedule 等页面通过 source/<page>/index.md + Front-matter 管理。

七、性能与可用性观察

  • 优点

    • PJAX + Instant.page 使页面切换与首次交互更敏捷。
    • TOC/相关文章/阅读模式/深色模式增强了长文可读性与导航性。
    • APlayer 固定播放器提升沉浸感（需注意流量与带宽）。

  • 关注点

    • 封面图/默认图较多（近百张 gif），首页首屏资源体量可能较大；建议按需精简或延迟加载。
    • Lazyload 关闭：在多图文章/长列表页会影响 FCP/LCP，可考虑开启主题 lazyload 或采用现代原生 lazy 属性。
    • canvas-nest、click-heart 等特效在低端设备上可能影响帧率；移动端已禁用 nest，较为稳妥。

八、安全与隐私

  • Waline（自建/托管后端）
    • 已启用匿名评论与 PV/UV 统计；建议在 Waline 后端开启基础反垃圾与速率限制，关注数据合规性。
  • Disqus
    • 作为备份评论系统；注意其隐私政策与被墙风险。
  • 加密文章
    • 已具备能力但未启用；如需发布敏感内容，可启用 hexo-blog-encrypt 并为分类/标签设置访问密码。

九、问题与改进清单（可执行）

1) Markdown 渲染器冗余

  • 同时安装了 markdown-it-plus 与 kramed；建议只保留一个（推荐 markdown-it-plus），并移除 hexo-renderer-kramed 与 root 中的 kramed: 配置，以避免行为不一致。

2) 搜索插件重复

  • hexo-generator-search 与 hexo-generator-searchdb 同时存在；推荐仅保留一个：
    • 若主题 local_search 读取 search.xml，保留 hexo-generator-search；
    • 或改为使用 searchdb（生成 search.json），并在主题中对应配置。

3) SEO 能力完善

  • 增加 RSS 与站点地图：
    • hexo-generator-feed（RSS/Atom）
    • hexo-generator-sitemap（sitemap.xml）

4) 统计与分析

  • 如需更细化的访问分析，可启用：
    • Vercel Analytics（已安装包，需在主题 head/bottom 注入脚本）
    • 或 Umami/GA4/Clarity 等（主题已预留配置项）。

5) 性能优化

  • 开启图片 Lazyload；
  • 精简默认封面 GIF 数量或改用静态 WebP；
  • 评估 APlayer 自动播放策略（移动端/低速网络条件下可考虑关闭自动播放）。

6) PWA 与离线

  • 如有离线访问/安装到桌面的诉求，可启用主题 pwa 并补齐 manifest 与图标资源。

7) 代码高亮统一性

  • 当前使用 highlight.js；若希望与 Butterfly 内置 Prism 生态更一致，可切换至 Prism 并开启按需加载（权衡体积与功能）。

十、快速问答（FAQ）

  • 本地搜索无结果？

    • 确认运行了 hexo generate 生成 search.xml|json；若装了两个搜索生成器，保留一个并与主题配置一致。

  • 文章公式不渲染？

    • 确认 Front-matter 未关闭 mathjax；加密路径（encrypted/**）默认跳过渲染。

  • 图片 404 或不显示？

    • 使用 post_asset_folder: true 时，建议将图片放在与文章同名的资源目录下并用相对路径引用；主题 error_img 会为断图提供默认占位图。

  • 评论数/访客数未显示？

    • 检查 Waline serverURL 可用性与跨域设置，确认主题 comments.count/pageview 已启用；首页卡片统计需等待首批上报后才会有值。

十一、结论

该博客以 Butterfly 为基础，完成了从内容到交互的较完整搭建：

  • 对技术内容（数学、密码学、算法）有友好的公式/代码支持与导航增强；
  • 评论、搜索、多媒体与视觉动效到位，使用体验较好；
  • 在 SEO、性能与插件冗余方面仍有可量化的优化空间（RSS/Sitemap、Lazyload、渲染器与搜索插件精简）。