1
2
3
4
5
6
7
8
9
10
11
# 清理缓存
hexo clean

# 重新生成
hexo generate

# 启动本地服务器
hexo server

#上传
hexo d

美化

优化文章永久链接为数字编号

Hexo博客设置永久网址链接 - PPPFZ's Blog

Hexo博客进阶教程（一）| 优化文章永久链接为数字编号-腾讯云开发者社区-腾讯云

安装插件

1
npm install hexo-abbrlink --save

替换配置文件_config.yml​以下内容即可

1
2
3
4
5
6
# permalink: :year/:month/:day/:title/
# permalink_defaults:
permalink: posts/:abbrlink/
abbrlink:
  alg: crc32 #support crc16(default) and crc32
  rep: dec   #support dec(default) and hex

主题颜色、宽度设置、图片设置、遮罩效果

1. 主题颜色（已恢复默认）

修改 themes/butterfly/_config.yml 的 theme_color 部分，启用并设置为深紫色系配色方案。
当前状态：恢复为 Butterfly 主题默认蓝色 (#49B1F5)，以保证远程部署样式一致性。

2. 页面宽度设置

修改 themes/butterfly/source/css/_page/common.styl 的 .layout 部分：

1
max-width: 70%  # 将原来的 1200px 改为 70%

3. 图片设置

修改 themes/butterfly/_config.yml 的图片相关配置：

  • favicon: /img/favicon.png - 网站图标
  • avatar.img: /img/avatar.png - 头像
  • avatar.effect: true - 启用头像特效
  • default_top_img: /img/banner.jpg - 所有页面通用横幅
  • index_img: /img/banner.jpg - 首页横幅（同上）
  • archive_img: /img/banner.jpg - 归档页横幅（同上）
  • tag_img: /img/banner.jpg - 标签页横幅（同上）
  • category_img: /img/banner.jpg - 分类页横幅（同上）
  • footer_img: rgba(45, 10, 61, 0.2) - 页脚背景
  • background: /img/background.jpg - 网站背景
  • cover.default_cover: /img/default-cover.png - 默认封面
  • error_img.flink: /img/flink-404.jpg - 友链错误图
  • error_img.post_page: /img/post-404.jpg - 文章页错误图
  • error_404.background: /img/404-bg.png - 404页面背景

4. 遮罩效果

修改 themes/butterfly/_config.yml 的 mask 部分：

1
2
3
mask:
  header: false  # 关闭页头遮罩
  footer: false  # 关闭页脚遮罩

5. 深色模式背景优化 (New)

修改 source/css/custom.css，避免深色模式下背景纯黑：

1
2
3
[data-theme="dark"] {
  --light_bg_color: rgba(18, 18, 18, 0.86);
}

所需图片文件（放在 source/img/ 目录下）：

  • favicon.png - 网站图标（浏览器标签页图标，32x32）
  • avatar.png - 侧边栏头像（200x200）✅ 已添加
  • background.jpg - 网站主背景（1920x1080）✅ 已添加
  • banner.jpg - 通用顶部横幅（1920x600）✅ 已添加
  • default-cover.png - 文章默认封面（1200x600，文章卡片缩略图）
  • flink-404.jpg - 友链页面加载失败图（400x300）
  • post-404.jpg - 文章页面加载失败图（800x600）
  • 404-bg.png - 404错误页面背景（1920x1080）

共需8张图片
已添加（3/8）：

  • ✅ avatar.png - 头像
  • ✅ banner.jpg - 横幅
  • ✅ background.jpg - 背景

导航栏设置

1. 网站基本信息设置

修改根目录 _config.yml：

  • 设置网站标题、副标题、描述、关键词
  • 配置 abbrlink 为 hex 格式
  • 添加 nofollow 配置

2. 导航栏配置

修改 themes/butterfly/_config.yml 的 nav 和 menu 部分：

  • logo: /img/favicon.png - 导航栏Logo
  • fixed: true - 固定导航栏
  • bg: default - 导航栏背景色（已恢复默认）
  • text_color: default - 文字颜色
  • hover_color: default - 悬停颜色

3. 菜单项配置

1
2
3
4
5
6
7
menu:
  首页: / || fas fa-home
  归档: /archives/ || fas fa-archive
  分类: /categories/ || fas fa-folder-open
  标签: /tags/ || fas fa-tags
  留言板: /comments/ || fas fa-comments
  关于: /about/ || fas fa-user

4. 创建页面

1
2
3
4
hexo new page categories  # 分类页
hexo new page tags        # 标签页
hexo new page comments    # 留言板
hexo new page about       # 关于页

在对应的 index.md 文件添加 type 字段：

  • source/categories/index.md: type: "categories"
  • source/tags/index.md: type: "tags"

5. 安装插件

1
2
3
4
npm install hexo-generator-search --save       # 搜索插件
npm install hexo-autonofollow --save          # 外链nofollow
npm install hexo-generator-tag --save         # 标签聚合页
npm install hexo-generator-category --save    # 分类聚合页

6. 搜索功能配置

修改 themes/butterfly/_config.yml 的 search 部分：

  • use: local_search - 使用本地搜索
  • preload: true - 页面加载时预加载搜索数据

7. 文件修改

  • ✅ themes/butterfly/layout/includes/header/nav.pug - 导航栏布局（已修改）
  • ⚠️ themes/butterfly/source/css/_layout/head.styl - 导航栏样式（需手动修改）
  • ⚠️ themes/butterfly/source/css/_search/local-search.styl - 搜索样式（需手动修改）

注意: 样式文件较大，建议参考原教程手动修改或等待进一步指示。

白天黑夜转换

【Hexo博客】添加Butterfly主题昼夜模式转换动画 | 百里飞洋

操作步骤

  1. 新建文件

    • themes/butterfly/layout/includes/sun_moon.pug - SVG图标
    • themes/butterfly/source/css/_layout/sun_moon.styl - 动画样式
    • themes/butterfly/source/js/sun_moon.js - 切换逻辑

  2. 修改模板文件

    • themes/butterfly/layout/includes/head.pug - 末尾添加 include ./sun_moon.pug
    • themes/butterfly/layout/includes/rightside.pug - 替换原昼夜切换按钮为新按钮

  3. 修改配置文件

    • themes/butterfly/_config.yml - 在 inject.bottom 添加 <script src="/js/sun_moon.js"></script>

  4. 重新生成

    1
    hexo clean && hexo g && hexo s

自定义背景图

修改 themes/butterfly/source/css/_mode/darkmode.styl，在第49行左右添加：

1
2
3
4
#web_bg
  background-image: url(/img/wallpaper-dark.jpg)
  background-size: cover
  background-repeat: no-repeat center

将图片放在 themes/butterfly/source/img/ 目录下，修改路径即可。

鼠标右键

‍

首页

网站副标题

修改 themes/butterfly/_config.yml 的 subtitle 部分：

  • enable: true - 启用副标题
  • effect: true - 启用打字机效果
  • loop: true - 循环播放
  • source: false - 不使用第三方API（可选 1-hitokoto.cn, 2-api.aa1.cn, 3-jinrishici.com）
  • sub - 副标题内容列表（支持HTML，可添加图标）

效果: 首页横幅下方会显示打字机效果的副标题，内容循环播放。✅

‍

侧边栏

‍

友链

‍

组件

‍

字体&&字数统计

1. 字数统计

安装插件：

1
npm install hexo-wordcount --save

修改 _config.butterfly.yml 的 wordcount 部分：

1
2
3
4
5
wordcount:
  enable: true
  post_wordcount: true
  min2read: true
  total_wordcount: true

电子时钟插件

功能说明

在侧边栏显示动态电子时钟卡片，包含：

  • ⏰ 实时日期和时间
  • 🌡️ 当前温度和天气状况
  • 💧 湿度信息
  • 📍 地理位置（基于IP自动获取，支持设置默认位置）

技术实现

  • Hexo 插件：hexo-butterfly-clock-anzhiyu（新版，功能更强）
  • 天气数据源：和风天气 API (QWeather)
  • 地理定位：高德地图 API (Gaode Map)
  • 数据更新：实时自动更新
  • CDN 加速：使用 cdn.cbd.int 加速资源加载

1. 安装插件

卸载旧版（如果有）：

1
npm uninstall hexo-electric-clock

安装新版插件：

1
npm install hexo-butterfly-clock-anzhiyu --save

2. 申请 API 密钥

和风天气 API（必需）：

  1. 访问 https://dev.qweather.com/ 注册账号
  2. 登录控制台 https://console.qweather.com/
  3. 创建项目 → 选择 Web API 类型
  4. 复制 API KEY（免费版：1000次/天）

高德地图 API（必需）：

  1. 访问 https://console.amap.com/dev/key/app 注册账号
  2. 创建应用 → 选择 Web服务 类型
  3. 添加 Key 并复制保存

3. 配置

在根目录 _config.yml 添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
electric_clock:
  enable: true # 开关
  priority: 5 # 过滤器优先权
  enable_page: all # 应用页面
  exclude:
    # - /posts/  # 可选：屏蔽某些页面
    # - /about/
  layout: # 挂载容器类型
    type: class
    name: sticky_layout
    index: 0
  loading: https://cdn.cbd.int/hexo-butterfly-clock-anzhiyu/lib/loading.gif
  clock_css: https://cdn.cbd.int/hexo-butterfly-clock-anzhiyu/lib/clock.min.css
  clock_js: https://cdn.cbd.int/hexo-butterfly-clock-anzhiyu/lib/clock.min.js
  ip_api: https://widget.qweather.net/simple/static/js/he-simple-common.js?v=2.0
  # 和风天气API密钥
  qweather_key: 你的和风天气密钥
  # 高德地图API密钥
  gaud_map_key: 你的高德地图密钥
  # 是否使用固定位置（true=使用rectangle位置，false=自动获取访问者位置）
  default_rectangle: false
  # 默认位置或备用位置（格式：经度,纬度）
  rectangle: 112.982279,28.19409

4. 参数说明（简要）

  • enable: 是否启用插件（true/false）
  • priority: 过滤器优先级（数字越小执行越早，默认 10）
  • enable_page: 生效页面（all=全局，/=首页，/posts/=文章页）
  • exclude: 排除页面（数组，可屏蔽指定页面）
  • layout.type: 挂载类型（class 或 id）
  • layout.name: 挂载容器名称（sticky_layout）
  • layout.index: class 容器的索引位置（从 0 开始）
  • loading: 加载动画图片 URL
  • clock_css: 时钟样式 CDN 地址
  • clock_js: 时钟脚本 CDN 地址
  • ip_api: 获取 IP 和位置的 API
  • qweather_key: 和风天气 API 密钥（必需）
  • gaud_map_key: 高德地图 API 密钥（必需）
  • default_rectangle: 是否使用固定位置（false=自动获取访问者位置）
  • rectangle: 默认位置坐标（访问者位置获取失败时使用）

5. 参数详细释义表

参数 备选值/类型 释义
priority number 【可选】过滤器优先级，数值越小，执行越早，默认为 10
enable true/false 【必选】控制开关
enable_page path/all 【可选】填写想要应用的页面的相对路径（即路由地址），如根目录填 /，分类页面填 /categories/。若要应用于所有页面，填 all，默认为 all
exclude path 【可选】填写想要屏蔽的页面，可以多个。原理是将屏蔽项的内容逐个放到当前路径去匹配，若当前路径包含任一屏蔽项，则不会挂载
layout.type id/class 【可选】挂载容器类型，填写 id 或 class，不填则默认为 id
layout.name text 【必选】挂载容器名称
layout.index 0 和正整数 【可选】前提是 layout.type 为 class，因为同一页面可能有多个 class，此项用来确认究竟排在第几个顺位
loading URL 【可选】电子钟加载动画的图片
clock_css URL 【可选】电子钟样式 CDN 资源
clock_js URL 【可选】电子钟执行脚本 CDN 资源
ip_api URL 【可选】获取时钟 IP 的 API
qweather_key text 【可选】和风天气 key（实际使用中为必需）
gaud_map_key text 【可选】高德地图 web 服务 key（实际使用中为必需）
default_rectangle true/false 【可选】开启后将一直显示 rectangle 位置的天气，否则将获取访问者的地理位置与天气
rectangle text 【可选】获取访问者位置失败时会显示该位置的天气，同时该位置为开启 default_rectangle 后的位置。格式：经度,纬度（如：112.982279,28.19409）

效果: 在侧边栏显示电子时钟和天气信息 ✅

注意事项：

  • 两个 API 都是免费的，个人博客使用无压力
  • 如果显示 undefined，检查 API 密钥是否正确填写
  • 天气数据每隔一段时间自动刷新

页脚美化

1. 自定义页脚内容

修改 _config.butterfly.yml 的 footer 部分：

  • 禁用 owner 和 copyright
  • 使用 custom_text 自定义 HTML 结构
  • 添加 Busuanzi 统计标签
1
2
3
4
5
6
7
8
9
10
11
12
13
footer:
  nav:
  owner:
    enable: false
    since: 2025
  # Copyright of theme and framework
  copyright:
    enable: false
    version: true
  custom_text: |
    <div>2025 Q7h2q9 - 所有权利保留</div>
    <div>> stay subside <</div>
    <div>访问量:<span id="busuanzi_value_site_pv"></span> | 你是第<span id="busuanzi_value_site_uv"></span>位今日访客</div>

GitHub 贡献度日历

  1. 安装插件：
1
npm i hexo-githubcalendar --save
  1. 修改根目录 _config.yml (不是主题配置)，添加以下内容（已恢复默认绿色）：
1
2
3
4
5
6
7
8
9
10
11
12
# Hexo Github Calendar
githubcalendar:
  enable: true
  enable_page: /
  user: Q7h2q9
  layout_id: recent-posts
  githubcalendar_html: '<div class="recent-post-item" style="width:100%;height:auto;padding:10px;"><div id="github_loading" style="width:10%;height:100%;margin:0 auto;display: block"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"  viewBox="0 0 50 50" style="enable-background:new 0 0 50 50" xml:space="preserve"><path fill="#d0d0d0" d="M25.251,6.461c-10.318,0-18.683,8.365-18.683,18.683h4.068c0-8.071,6.543-14.615,14.615-14.615V6.461z" transform="rotate(275.098 25 25)"><animateTransform attributeType="xml" attributeName="transform" type="rotate" from="0 25 25" to="360 25 25" dur="0.6s" repeatCount="indefinite"></animateTransform></path></svg></div><div id="github_container"></div></div>'
  pc_minheight: 280px
  mobile_minheight: 0px
  color: "['#ebedf0', '#f0fff4', '#dcffe4', '#bef5cb', '#85e89d', '#34d058', '#28a745', '#22863a', '#176f2c', '#165c26', '#144620']"
  api: https://python-github-calendar-api.vercel.app/api
  calendar_js: https://cdn.jsdelivr.net/gh/Zfour/[email protected]/hexo_githubcalendar.js

评论系统 (Giscus)

修改 _config.butterfly.yml (以及主题配置文件)：

  1. 启用 Giscus：
1
2
comments:
  use: Giscus
  1. 配置 Giscus 参数（已恢复官方主题）：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
giscus:
  repo: Q7h2q9/Q7h2q9.github.io
  repo_id: R_kgDOQrfy5A
  category_id: DIC_kwDOQrfy5M4C0O_x
  light_theme: light  # 官方亮色主题
  dark_theme: dark    # 官方暗色主题
  js: https://giscus.app/client.js
  option:
    data-category: Announcements
    data-mapping: pathname
    data-strict: 0
    data-reactions-enabled: 1
    data-emit-metadata: 0
    data-input-position: bottom
    data-lang: zh-CN

故障排查 (Troubleshooting)

远程部署仍显示旧样式（紫色）

现象：本地修改配置为蓝色后，远程部署仍显示旧的紫色样式。
原因：Hexo 的 public 缓存未清除，导致 CSS 文件中残留旧的 Hex 颜色代码（如 #6a0dad）。
解决：

  1. 删除 public 文件夹和 db.json。
  2. 重新运行生成和部署命令：
1
hexo clean && hexo generate && hexo deploy

深色模式下卡片过黑

现象：深色模式下，文章卡片和侧边栏卡片背景色接近纯黑，视觉效果不佳。
原因：source/css/custom.css 中深色模式背景色设置过暗。
解决：修改 source/css/custom.css：

1
2
3
[data-theme="dark"] {
  --light_bg_color: rgba(40, 42, 46, 0.85);  /* 从 rgba(18, 18, 18, 0.86) 调整 */
}

首页不蒜子统计不显示数值

现象：文章页底部统计显示正常，但首页只显示文字不显示具体数值。
原因：不蒜子脚本未正确加载。
解决：在 _config.butterfly.yml 和 themes/butterfly/_config.yml 的 inject.bottom 添加：

1
2
3
inject:
  bottom:
    - <script async src="//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>

注意：需要同时修改两个配置文件以确保远程部署生效。

电子时钟显示 undefined

现象：电子时钟显示 undefined *C、💧 undefined、位置显示为 Unknownlocation。
原因：未配置天气和地图 API 密钥。
解决：

  1. 申请和风天气 API：https://dev.qweather.com/
  2. 申请高德地图 API：https://console.amap.com/dev/key/app
  3. 在 _config.yml 中填入密钥：
1
2
3
electric_clock:
  qweather_key: 你的和风天气API密钥
  gaud_map_key: 你的高德地图API密钥
  1. 重新生成：hexo clean && hexo g && hexo s

备注：两个 API 都是免费的，注册即可使用。

参考资料

从零开始 | Butterfly主题美化教程

‍

‍