博客魔改教程：一步步改造我的 AnZhiyu 主题

博客魔改教程 — 如何魔改我的 AnZhiyu 博客

作者：ShiZhongyan 🍭
简介：本文把我对基于 AnZhiyu 主题的博客做的常用“魔改”整理成一步步的教程，包含视觉（背景、光标）、交互（IP 欢迎、QRCode）与兼容性（PJAX、IPv6 换行）处理。适合有 Hexo/主题基础的读者复现。

免责声明与前置准备

  • 修改前请备份主题和 source 目录（git commit 或复制文件夹）。
  • 需要基本前端能力（HTML/CSS/JS）和 Hexo 本地调试（hexo s）。
  • 本文以主题路径为：d:\程序\blog-demo\themes\anzhiyu；站点源码位于 d:\程序\blog-demo\source。

总览（你会得到什么）

  • 白天/夜间两张不同的全站背景图。
  • 侧栏公告显示“欢迎信息”，基于访客 IP 显示地区与到站长的距离（腾讯位置 API）。
  • IPv6 或超长字符串自动换行，不扰乱卡片布局。
  • 在站点底部引入 QRCode 库避免依赖报错。
  • 自定义鼠标光标（内点 + 外环 + 点击涟漪），在链接/按钮悬停时有交互反馈。
  • PJAX 友好处理，使动态页面切换后交互仍可用。

步骤 1 — 添加日/夜背景图（CSS）

修改文件：source/css/custom.css

关键点：

  • 使用 body 进行背景设置，深色模式覆盖使用 [data-theme=”dark”] body。
  • 使用合适尺寸图并设置 background-size: cover。

示例 CSS：

1
2
3
4
5
6
7
8
9
/* 在 custom.css 中添加（或替换） */
body {
  background: url('https://sourcebucket.s3.bitiful.net/img/dm3.webp') no-repeat center center fixed;
  background-size: cover;
}
[data-theme="dark"] body {
  background: url('https://sourcebucket.s3.bitiful.net/img/yuanshen1.webp') no-repeat center center fixed;
  background-size: cover;
}

调试：切换主题或系统深色模式，Ctrl+F5 清缓存查看。

步骤 2 — 在公告栏显示欢迎信息（IP 定位）

修改文件：

  • source/js/txmap.js（新增或改写）
  • themes/anzhiyu/layout/includes/widget/card_announcement.pug（确保存在 #welcome-info 容器）
  • _config.anzhiyu.yml（在 inject.bottom 引入 txmap.js，并注意 data-pjax 属性）

要点：

  • 使用腾讯 Map 的 IP 定位接口（JSONP）。在成功回调中把结果存到全局（例如 window.ipLoacation）并调用 showWelcome()。
  • showWelcome() 读取 ipLoacation，生成 HTML 插入到 #welcome-info；要做好容错检查（ipLoacation 或 DOM 未准备好时返回）。
  • 在 pjax:complete 事件中再次调用 showWelcome()，保证页面切换后仍显示。

示例（伪代码）：

1
2
3
4
5
// 在 txmap.js 成功回调后
window.ipLoacation = res;
showWelcome();

// showWelcome() 内包装 try/catch，并在 pjax:complete 调用

步骤 3 — IPv6 与超长字符串换行

问题：IPv6 地址太长会溢出侧栏卡片。

解决：

  • 在插入 IP 的 HTML 中为 IP span 添加 class=”ip-addr”。
  • 在 custom.css 添加换行样式：
1
2
3
4
5
6
7
.ip-addr {
  overflow-wrap: anywhere;
  word-break: break-all;
  word-wrap: break-word;
  display: inline-block;
  max-width: 100%;
}

说明：anywhere 优先，兼容旧浏览器保留 break-all。

步骤 4 — 引入 QRCode 库，修复依赖错误

错误示例：Uncaught ReferenceError: QRCode is not defined（utils.js 调用前库未加载）

处理：

  • 在 _config.anzhiyu.yml 的 inject.bottom 中添加 QRCode 脚本（放在 utils.js 之前）：
1
<script src="https://cdn.jsdelivr.net/npm/qrcodejs@1.0.0/qrcode.min.js"></script>
  • 不要把 QRCode 脚本设为 async（若 utils.js 需要立即使用全局 QRCode）。

步骤 5 — 自定义鼠标光标（cursor.js + CSS）

目标：漂亮的光标（外环 + 内点 + 点击涟漪），悬停/按下有反馈，兼容 PJAX。

修改文件：

  • source/js/cursor.js（实现 class Cursor，用 requestAnimationFrame 与 Math.lerp 平滑位移；事件委托识别可交互元素；提供 refresh 方法）
  • source/css/custom.css（添加 #cursor、.cursor-dot、.cursor-ring、.cursor-ripple 动画样式）

关键点：

  • 使用 document.addEventListener(‘mouseover’, …) 与 target.closest(selector) 来判断 hover（支持动态添加元素）。
  • 在 mousedown 时生成一个短时的涟漪 DOM（动画结束后移除），避免频繁修改大量样式。
  • small-screen 默认隐藏自定义光标（可选）。

调试：在 DevTools 中查看 #cursor 节点是否存在及样式是否生效。

步骤 6 — PJAX 兼容（非常重要）

要点：

  • 把 cursor.js、txmap.js、QRCode 等全局库通过 inject.bottom 首次加载，确保初始页面可用。
  • 对于需要在页面切换后重新初始化的逻辑（showWelcome、CURSOR.refresh 等），监听 PJAX 事件并触发对应函数：
1
2
3
4
document.addEventListener('pjax:complete', () => {
  try { showWelcome(); } catch(e){};
  try { CURSOR && CURSOR.refresh && CURSOR.refresh(); } catch(e){};
});

步骤 7 — 文件清单（核心修改位置）

  • source/css/custom.css —— 背景、ip-addr、cursor 样式、#fps 美化等。
  • source/js/txmap.js —— 腾讯 IP 定位与 showWelcome 实现。
  • source/js/cursor.js —— 自定义光标。
  • _config.anzhiyu.yml —— inject.bottom 增加 qrcode、cursor、txmap 引入顺序。
  • themes/anzhiyu/layout/includes/widget/card_announcement.pug —— 确保 #welcome-info 存在。

我在仓库中已将这些文件分别实现（如需我把关键代码片段抽出为单独 Gist 或补充截图，我可以继续处理）。

调试与部署建议

  1. 本地运行：hexo clean && hexo s；在浏览器按 Ctrl+F5 强制刷新静态缓存。
  2. Console 检查：确保没有 “QRCode is not defined”、”ipLoacation undefined” 等错误。
  3. 测试 PJAX：在站内多次跳转，观察欢迎信息、光标是否在切换后继续可用。
  4. 兼容性：IPv6 换行规则在旧浏览器上可能略有差异，测试主流浏览器。
  5. 回退准备：修改前 git commit，出现问题可快速回退。

结语

本文把我对博客的魔改思路和具体要点总结成可复制的步骤，方便你在自己的 AnZhiyu 主题上复现。若你需要，我可以：

  • 把每个修改点生成独立的补丁/PR；
  • 提供完整版代码片段文件（cursor.js、txmap.js、custom.css 关键片段）；
  • 添加截图或演示视频。

祝你魔改愉快 🍭