在 GitHub 上，一个精心设计的个人主页不仅可以展示你的项目、技术栈，还能通过动态数据和动画效果提升个人品牌形象。本文将分享两个经典模块的自动化集成方法：
- WakaTime 数据展示：自动统计 Coding 时间、提交数据以及其他指标。
- 贪吃蛇动画：让你的贡献热力图“变身”成贪吃蛇动画，增添趣味性。
利用 GitHub Actions 你可以让这两部分数据每天定时更新，也可以手动触发更新。下面是详细的部署步骤和注意事项。
一、WakaTime 数据集成
1.1 获取必备密钥
-
WakaTime API Key
登录 WakaTime 后，从你的 Account Settings 中获取 API Key。 -
GitHub Personal Access Token (PAT)
为了获取额外的提交数据（例如 commit stats），你可能需要生成一个拥有repo和user权限的 PAT。
1.2 配置仓库 Secrets
在你的仓库（例如 IHKYoung/IHKYoung）中，进入 Settings → Secrets and variables → Actions 页面，新建以下 Secrets：
WAKATIME_API_KEY：你的 WakaTime API KeyGH_TOKEN：你的 GitHub 个人访问令牌（或使用默认的 GITHUB_TOKEN，但建议在需要更多权限时使用 PAT）
1.3 创建 GitHub Action 工作流文件
在仓库的 .github/workflows/ 目录下创建一个文件，例如 waka.yml，内容如下（注意：这里根据你的需求只保留了总时长和部分统计，隐藏了其他模块的信息；同时分支提交设置为你的默认分支，这里以 baseline 为例）：
name: Waka Readme
on:
schedule:
# 每天北京时间 0:30 运行一次，即 UTC 16:30
- cron: '30 16 * * *'
workflow_dispatch:
jobs:
update-readme:
name: Update Readme with WakaTime Metrics
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
# 如果需要，可以显式指定分支（默认会使用仓库的默认分支）
# with:
# ref: baseline
- name: Update WakaTime Stats
uses: anmol098/waka-readme-stats@master
with:
WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
GH_TOKEN: ${{ secrets.GH_TOKEN }}
# 以下 Flag 根据需求设置：
SECTION_NAME: "waka"
SHOW_OS: "False"
SHOW_PROFILE_VIEWS: "False"
SHOW_PROJECTS: "False"
SHOW_COMMIT: "False"
SHOW_LINES_OF_CODE: "False"
SHOW_TOTAL_CODE_TIME: "False" # 根据你的需求调整，这里你设置为 False，如果只保留其他信息可以调整
SHOW_LANGUAGE: "False"
SHOW_TIMEZONE: "False"
SHOW_DAYS_OF_WEEK: "True"
SHOW_EDITORS: "False"
SHOW_LANGUAGE_PER_REPO: "False"
SHOW_SHORT_INFO: "False"
SHOW_LOC_CHART: "False"
SHOW_UPDATED_DATE: "False"
IGNORED_REPOS: "waka-readme-stats" # 忽略本 Action 自身仓库
- name: Commit & Push changes
uses: EndBug/add-and-commit@v7
with:
branch: baseline
message: 'Update WakaTime Stats'
注意：
-
SECTION_NAME：README 中必须预留一对标记，用于 Action 替换数据。你需要在 README.md 中加入如下内容：
<!--START_SECTION:waka--> <!--END_SECTION:waka--> -
Flag 设置决定了展示哪些数据。上面的配置隐藏了大部分信息，仅显示了你希望展示的部分（例如这里只保留了某项数据，如“SHOW_DAYS_OF_WEEK”为 True，可根据实际需要调整）。
1.4 更新 README
在你的 README.md 中，添加如下占位符区域（放置在你希望显示 WakaTime 数据的部分）：
## Coding Activity
<!--START_SECTION:waka-->
<!--END_SECTION:waka-->
工作流运行后，WakaTime 数据会自动填充到这对标记之间。
二、贪吃蛇动画集成
贪吃蛇动画利用你的贡献热力图生成一个动态的 SVG 动画（或 GIF 动画），增加主页的趣味性。
2.1 配置生成工作流
在 .github/workflows/ 目录下创建一个文件，例如 snake.yml，内容如下。此示例中使用 Platane/snk 的 svg-only 版本来生成贪吃蛇动画，并将生成的文件保存到 dist 目录，随后使用 crazy-max/ghaction-github-pages Action 将 dist 目录内容推送到 output 分支，以便在线访问。
name: Generate Snake Animation
on:
# run every day at 16:00 UTC
schedule:
- cron: "0 16 * * *"
workflow_dispatch:
# run on every push on these branches
push:
branches:
- master
- baseline
- main
jobs:
generate:
permissions:
contents: write
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
# 生成贪吃蛇动画的 SVG 文件
- name: generate github-contribution-grid-snake.svg
uses: Platane/snk/svg-only@v3
with:
github_user_name: ${{ github.repository_owner }}
outputs: |
dist/github-contribution-grid-snake.svg
dist/github-contribution-grid-snake-dark.svg?palette=github-dark
# 将 dist 目录内容推送到 output 分支，以便通过 URL 访问生成的文件
- name: push github-contribution-grid-snake.svg to the output branch
uses: crazy-max/ghaction-github-pages@v3.1.0
with:
target_branch: output
build_dir: dist
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
说明：
-
触发器（on 部分）：
schedule：定时运行（此处设置为每天 16:00 UTC，即北京时间 0:00 或根据实际需要调整）。workflow_dispatch：允许你手动触发工作流。push：当对指定的分支（master、baseline、main）进行 push 时也会触发此工作流。注意：即使你主要在 baseline 工作，也保留其它常用分支名称以提高兼容性。
-
生成步骤：
使用Platane/snk/svg-only@v3Action，根据 GitHub 用户的贡献图生成两份 SVG 文件（普通和 dark 模式），并将输出路径指定为dist/目录。 -
推送步骤：
使用crazy-max/ghaction-github-pages@v3.1.0Action，将dist目录的内容推送到目标分支 output。
推送后，你可以通过以下 URL 格式访问文件（替换为你的 GitHub 用户和仓库名）：https://raw.githubusercontent.com/IHKYoung/IHKYoung/output/github-contribution-grid-snake.svg注意： 请确保仓库根目录下存在或能创建
dist文件夹。该文件夹用于存放生成的动画文件。
三、经验总结与注意事项
-
触发器设置
- push 触发器： 指定了多个分支（master、baseline、main），这意味着当你对这些分支进行代码提交时，相关工作流都会触发。你可以根据实际情况保留或修改此列表。如果你只在默认分支（例如 baseline）上操作，可以只列出 baseline，但添加其他常用分支可以增加兼容性。
- schedule 与 workflow_dispatch： 定时任务保证数据每天自动更新，workflow_dispatch 则允许手动触发，方便测试和即时更新。
-
目录结构要求
- 对于 WakaTime 模块，你只需要在 README.md 中预留占位符区域，工作流会自动替换数据。
- 对于贪吃蛇动画模块，建议在仓库根目录下创建
dist目录（或确认 Action 能自动创建），以便生成的动画文件保存于此，并最终通过指定的目标分支（如 output）进行展示。
-
分支管理与权限问题
- 如果你的仓库默认分支不是常见的 main，而是 baseline，务必在工作流的“push”步骤中指定正确的分支。
- 推送过程中，确保使用的 GITHUB_TOKEN 或自定义 PAT 拥有足够权限，且仓库分支保护规则允许自动提交。
-
调试与测试
- 首次配置后，可以通过手动触发（workflow_dispatch）来验证工作流是否按预期运行，检查生成的统计数据和动画文件是否正确更新。
- 如果遇到权限或路径错误，请检查 Secrets 配置、仓库保护规则以及指定的文件夹路径是否存在。
结语
通过本文的配置，你可以实现以下目标：
- WakaTime 数据自动更新：每天自动将最新的 Coding 时间和统计信息更新到你的 README 中，且只显示你需要的数据部分（例如只显示每日提交情况）。
- 贪吃蛇动画展示：利用贡献热力图生成动态贪吃蛇动画，并通过推送到 output 分支让外部可以访问和嵌入到 README 中。