引言

在追求个人成长和习惯养成的过程中，每日打卡是一种简单有效的自我监督方式。为了方便记录和追踪打卡进度，我在bigpeter博客中开发了一个基于GitHub Issues的打卡功能。本文将详细介绍该功能的使用方法、技术原理以及常见问题解决方案。

功能亮点

  • 每日打卡记录：轻松记录每天的打卡情况
  • 多设备同步：通过GitHub Issues实现数据云端存储
  • 智能统计：自动计算总天数、连续打卡、最长连续、本月打卡等数据
  • 历史回顾：按时间倒序查看所有打卡记录
  • 多用户支持：系统根据GitHub令牌自动区分不同用户的数据
  • 响应式设计：适配手机、平板和电脑等多种设备

快速开始

1. 创建GitHub Issue作为数据存储

打卡功能使用GitHub Issues的评论来存储打卡记录。你需要先创建一个专用的Issue：

  1. 访问你的GitHub仓库：https://github.com/holyshite/bigpeter-blog（或你自己的仓库）
  2. 点击”Issues”标签页
  3. 点击”New issue”按钮
  4. 标题输入：打卡记录存储
  5. 内容输入：此Issue用于存储每日打卡记录，请不要关闭或删除。
  6. 创建Issue

  7. 记住Issue编号（URL中的数字，例如：https://github.com/holyshite/bigpeter-blog/issues/1中的1）

    提示：你也可以不创建Issue，直接使用默认的Issue（编号2）。系统默认配置了holyshite/bigpeter-blog仓库的Issue #2作为打卡记录存储位置。

2. 获取GitHub个人访问令牌

打卡功能需要访问GitHub API，你需要创建一个个人访问令牌：

  1. 访问GitHub设置：https://github.com/settings/tokens
  2. 点击”Generate new token” → “Generate new token (classic)”
  3. 输入令牌描述：博客打卡功能
  4. 选择权限：
    • repo（完全控制仓库，包括issues）
    • 或者至少选择public_repo（如果仓库是公开的）
  5. 点击”Generate token”
  6. 重要提示：立即复制生成的令牌，关闭页面后将无法再次查看

3. 配置打卡功能

在浏览器中配置打卡功能：

  1. 访问博客的打卡页面：https://bigpeter.top/checkin.html
  2. 打开浏览器开发者工具（按F12键）
  3. 在控制台(Console)中输入： 
    localStorage.setItem('github_token', '你的令牌');
  4. 刷新打卡页面

4. 高级配置（可选）

如果你使用不同的GitHub仓库或Issue编号，可以在打卡页面的配置区域进行设置：

  1. 点击右下角的”⚙️ 配置GitHub访问”按钮
  2. 在弹出窗口中输入：
    • GitHub用户名（仓库所有者）
    • 仓库名称
    • Issue编号
  3. 点击”保存并验证”按钮

建议：为获得最佳体验，每个用户应配置自己的GitHub Issue来存储数据，这样可以避免数据混淆。

使用方法

打卡操作

  1. 访问打卡页面（确保已配置GitHub令牌）
  2. 点击”立即打卡”按钮（蓝色大按钮）
  3. 等待成功提示
  4. 完成！系统会自动更新统计数据和历史记录

查看统计信息

打卡页面顶部显示四个关键统计指标：

  • 总打卡天数：累计打卡的总天数
  • 连续打卡：当前连续打卡的天数（断签后重置）
  • 最长连续：历史上最长的连续打卡记录
  • 本月打卡：本月内已打卡的天数

查看历史记录

页面下方按时间倒序显示所有打卡记录，包含：

  • 日期和具体时间
  • 星期几
  • 备注信息（如果有）

技术原理

数据存储机制

打卡功能采用混合存储策略：

  1. 云端存储：每个打卡记录作为JSON对象存储在GitHub Issue的评论中
    • 数据格式：{"type": "checkin", "date": "YYYY-MM-DD", "timestamp": 毫秒时间戳（实际打卡时间）, "note": "备注", "userId": "GitHub用户名（可选）"}
    • 多用户支持：系统会自动添加userId字段标识打卡用户。当多个用户共享同一个Issue时，每个用户只能看到自己的打卡记录。
  2. 本地缓存：打卡记录缓存在浏览器的localStorage中（按用户过滤），用于：
    • 网络不可用时显示历史记录
    • 提高页面加载速度
    • 减少GitHub API调用次数

同步机制

  1. 页面加载时：从GitHub Issues获取最新打卡记录
  2. 打卡操作时：立即同步到GitHub，并更新本地缓存
  3. 状态检查：基于GitHub API数据判断今日是否已打卡（非本地存储）

多用户支持原理

系统通过以下方式实现多用户数据隔离：

  1. 用户识别：通过GitHub API获取当前令牌对应的用户信息
  2. 数据标记：新打卡记录自动添加userId字段
  3. 数据过滤：加载历史时只显示当前用户的数据
  4. 向后兼容：旧的无userId数据对所有用户可见

故障排除

常见问题及解决方案

1. “需要配置GitHub访问”提示一直显示

  • 检查：是否已执行localStorage.setItem('github_token', '你的令牌')
  • 检查：令牌是否有效（未过期）
  • 检查：令牌是否具有必要的权限（repo或public_repo）

2. 打卡失败

  • 检查：网络连接是否正常
  • 检查：GitHub API限制（每小时60次请求）
  • 检查：Issue是否被关闭或删除
  • 解决方案：等待一段时间后重试

3. 统计信息不正确

  • 尝试：清除本地缓存： 
    localStorage.removeItem('checkin_history_cache');
localStorage.removeItem('last_checkin_date');
  • 尝试：刷新页面重新从GitHub加载数据

4. 看到其他用户的打卡记录

  • 原因：多个用户共享同一个GitHub Issue，且旧数据没有用户标识符
  • 解决方案：
    1. 每个用户配置自己的GitHub Issue（推荐）
    2. 在配置页面设置不同的仓库或Issue编号
    3. 系统会自动为新打卡记录添加用户标识符，旧数据对所有用户可见

5. 不同设备数据不同步

  • 确保：所有设备使用相同的GitHub令牌
  • 尝试：刷新页面强制同步最新数据

浏览器兼容性

  • 需要现代浏览器支持ES6+、localStorage、Fetch API
  • 推荐：Chrome 60+、Firefox 55+、Safari 11+、Edge 79+
  • 移动端：iOS Safari、Android Chrome等主流浏览器均支持

隐私与安全

数据存储

  • 打卡记录存储在GitHub Issues中，对仓库有访问权限的人可见
  • 本地缓存仅存储在用户浏览器中，不会上传到其他服务器

令牌安全

  • GitHub令牌具有仓库访问权限，请妥善保管
  • 不要在公共电脑上配置令牌
  • 定期更新/撤销令牌
  • 如果令牌泄露，立即在GitHub设置中撤销

数据删除

要完全删除所有打卡记录：

  1. 删除GitHub Issue中的所有评论
  2. 清除浏览器localStorage： 
    localStorage.removeItem('github_token');
localStorage.removeItem('last_checkin_date');
localStorage.removeItem('checkin_history_cache');

版本更新

v1.1.0 (2026-04-06)

  • 界面优化：修复黑夜模式下按钮悬浮样式异常问题
  • 布局改进：修复配置页面与底部按钮组重叠的布局问题
  • 交互优化：调整管理按钮布局为水平排列，添加”取消”按钮
  • 数据精度：时间戳记录实际打卡时间（精确到毫秒），历史记录同时显示日期和具体时间
  • 多用户支持：系统根据GitHub令牌自动区分用户数据
    • 打卡记录添加用户标识符 (userId 字段)
    • 每个用户只能看到自己的打卡记录（共享Issue中的旧数据对所有用户可见）
    • 页面初始化时自动加载用户特定的仓库配置

v1.0.0 (2026-04-06)

  • 初始版本发布
  • 支持每日打卡
  • 支持多设备同步
  • 基础统计功能

结语

这个打卡功能是我将日常需求与技术实践结合的产物，希望通过这个工具能够帮助更多人培养良好的打卡习惯。系统基于GitHub Issues构建，既利用了现有的可靠服务，又实现了数据的持久化存储。

如果你在使用过程中遇到任何问题，或者有改进建议，欢迎在GitHub仓库中提交Issue。也欢迎访问我的博客bigpeter.top查看更多技术分享和生活记录。

坚持打卡，记录成长，每一天都算数！