【Hexo】Butterfly主题在主页添加GitHub贡献日历

時光2024-06-192026-06-16

本文介绍如何在博客添加GitHub贡献日历(github calendar)，中间踩了一些坑，特写此篇，以作记录，效果如下

2026-06-16 最新配置（推荐）

原上游项目 Barry-Flynn/python_github_calendar_api 和前端插件 @barry-flynn/hexo-github-calendar 已存在兼容性问题（Python 依赖过旧导致 Vercel 部署 500、GitHub 前端改版导致爬虫失效、Retina 屏幕下月份标签和鼠标悬浮提示错位）。以下是我基于上游 Fork 后的修复版本，项目演化链路为：Zfour/hexo-github-calendar → Barry-Flynn → 我的 Fork。

后端 API

我已在 Vercel 部署了修复后的 API，自定义域名为：

1	https://github-calendar.shiguang666.eu.org/api

如果你也想自建，Fork Shiguang-coding/python_github_calendar_api 到自己的 GitHub，然后在 Vercel 导入部署即可（Python 项目，无需配置 Node.js 版本）。部署后记得在 Vercel 项目的 Settings → Domains 绑定自定义域名（添加 CNAME 记录指向 cname.vercel-dns.com）。

相对上游的主要改动：

重写爬虫：原版正则已无法匹配 GitHub 当前 HTML 结构。改用 /users/{username}/contributions 页面的 data-date 属性获取完整日期，配合 <tool-tip> 元素提取贡献数量。
更新 Python 依赖：旧版 urllib3<2.0 在 Python 3.12 下崩溃，升级为 urllib3>=2.0.0、requests>=2.31.0。

详见仓库 README。

前端配置

在 Hexo 根目录 _config.yml 中添加：

githubcalendar:
  enable: true
  enable_page: /
  user: shiguang-coding   # 替换为你的 GitHub 用户名
  layout:
    type: id
    name: recent-posts
    index: 0
  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', '#a2f7af', '#6ce480', '#54ad63', '#469252', '#31753c', '#1f5f2a', '#13531f', '#084111', '#032b09', '#000000']"
  api: https://github-calendar.shiguang666.eu.org/api   # 替换为你自己的 API 地址
  calendar_js: /js/hexo_githubcalendar.js   # 使用本地 JS 文件（推荐）
  plus_style: ""

安装插件：

1	npm i @shiguang-coding/hexo-github-calendar --save

下载修复后的 hexo_githubcalendar.js 到主题 source/js/ 目录下。该 JS 文件修复了两个 Retina 屏幕下的 bug：

月份标签位置偏移（github_calendar_c.width 使用了缩放后的值）
鼠标悬浮提示日期错位（getMousePos 坐标转换使用了缩放后的值）

注意：如果你使用的是安知鱼主题（anzhiyu），JS 文件路径为 themes/anzhiyu/source/js/hexo_githubcalendar.js。重装 npm 插件不会覆盖本地 JS 文件。

构建并预览：

1	hexo clean && hexo g && hexo s

以下为 2024 年原版配置（仅供参考）

需要用到的插件及API （这是博主百里飞洋基于原开源插件hexo-github-calendar及APIpython_github_calendar_api改造后的，截至目前原项目工具仍有问题，避个雷）

前端Hexo插件：https://github.com/Barry-Flynn/hexo-github-calendar

后端API部署：https://github.com/Barry-Flynn/python_github_calendar_api

作者: 百里飞洋 Barry-Flynn
链接: https://blog.meta-code.top/2022/03/15/2022-41/
来源: 百里飞洋

安装依赖

推荐使用我修复后的版本（已修复 Retina 高分屏月份标签偏移和 tooltip 错位问题）：

1	npm i @shiguang-coding/hexo-github-calendar --save

或者从 GitHub 直接安装：

1	npm i github:Shiguang-coding/hexo-github-calendar --save

使用 cnpm：

1	cnpm i @shiguang-coding/hexo-github-calendar --save

添加配置

在 Hexo 项目根目录的 _config.yml 文件最后面添加如下配置（注意是在 Hexo 的配置文件中添加，而不是主题的配置文件）

# hexo-github-canlendar
  # 贡献度热力图插件 https://github.com/Shiguang-coding/hexo-github-calendar
githubcalendar:
  enable: true        # 是否启用本插件
  enable_page: /      # 要生效的页面，如 / 首页，/about/ 介绍页等
  user: shiguang-coding   # GitHub 用户名
  layout:
    type: id
    name: recent-posts
    index: 0
  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', '#a2f7af', '#6ce480', '#54ad63', '#469252', '#31753c', '#1f5f2a', '#13531f', '#084111', '#032b09', '#000000']"
  # 推荐填写你自建的API接口，公用api随时可能会失效
  # api: https://github-calendar-api.meta-code.top/api
  api: https://githubcalendarapi.shiguang666.eu.org/api
  # 推荐下载后使用本地文件
  # calendar_js: https://cdn.jsdelivr.net/gh/Shiguang-coding/hexo-github-calendar/hexo_githubcalendar.js # 在线文件，容易加载失败
  calendar_js: /js/hexo_githubcalendar.js # 本地文件，请下载到主题文件夹的source目录下
  plus_style: ""