GitHub 首页 DIY：花里胡哨指数++

写代码之外，程序员还有一种稳定的快乐来源：把自己每天会看到的东西，折腾得更顺眼一点。

写在前面

这个坑其实我早就挖了。

上学期我只是把 GitHub 首页先“CV”了一版过来，能看是能看，但很多内容并不是自己真正理解之后搭出来的。趁着放假回家时间稍微宽裕一点，我终于把这个坑补上了：重新整理、重新配置、重新踩坑，顺手把 GitHub Profile 这一套也认真收拾了一遍。

说到底，GitHub 首页 DIY 这件事没什么生产力上的刚需，但它就是很容易让人上头。就像折腾 IDE 主题、挑桌面壁纸、改终端配色一样，很多人都会下意识地想把自己最常待的环境弄得更舒服一点。GitHub 主页也是一样，它不只是一个页面，有时候也是你的公开门面、项目索引，甚至是“我最近在折腾什么”的动态展示板。

先说一句大实话

网上关于 GitHub Profile 的系统教程其实不算多。不是因为它难到离谱，而是因为这东西很散：有的是纯 Markdown，有的是第三方图片服务，有的是 GitHub Actions 定时生成数据，还有一堆参数、Token、权限和工作流配置混在一起。真正写起来，确实不太好写。

所以这篇文章更像一份我自己折腾完之后的整理笔记。不求面面俱到，但尽量把我觉得有用、而且确实能直接抄起来用的部分留下来。

先看成果，再决定要不要折腾

先放我的 GitHub 主页和完整截图。

GitHub Profile

我的 GitHub 首页，下面提到的大部分内容都能在这里看到实际效果。

完整截图（建议点开放大看）

如果你只是想要一个干净一点的个人主页，那完全没必要像我这样堆这么多东西。说实话，我这版已经有点偏“花里胡哨过量”了。更合理的做法应该是按需取用：你喜欢哪块就加哪块，不喜欢就删，别为了炫技把首页搞成信息瀑布。

不过如果你喜欢这种折腾感，那 GitHub Profile 的可玩性确实挺高。

GitHub 首页 DIY，本质上就是在折腾一个 `README.md`

准备工作其实非常简单。

你只需要新建一个和自己 GitHub 用户名同名的仓库，并勾选初始化 README.md。GitHub 会自动把这个仓库识别为你的 Profile 仓库，然后这个仓库里的 README.md 就会显示在你的个人主页顶部。

准备工作示意

所以这件事说穿了，其实没那么玄乎：

GitHub 首页 DIY，本质上就是对这个特殊仓库里的 README.md 做排版、做拼接、做自动更新。

如果你有 HTML、CSS 和 Markdown 的基础，这件事会更顺手；即使不熟，也完全可以从复制现成组件开始，再一点点改成自己的风格。

第一类玩法：不需要 Token，复制链接就能用

这部分是最适合先上手的。它们基本不依赖 GitHub Actions，也不用你去配 Secret，通常就是改改用户名、主题、颜色参数，然后把图片链接塞进 README.md 就能显示。

先提醒一句

下面很多示例里用的都是我的用户名 JJLibra，你直接替换成自己的用户名就行。

开头打字特效

这个应该算是最常见、也最容易让人第一眼注意到的组件之一。

我当时用的是 readme-typing-svg，它提供了在线 Demo，参数调起来也比较直观，适合一边预览一边改。

README.htmlhtml

<h1 align="center">
  <a href="https://blog.xxfer.cn/">
    <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&pause=1000&width=435&lines=console.log(%22Hello%2C%20World%22);小李今天又在努力变强鸭~&center=true&size=27">
  </a>
</h1>

GitHub 统计卡片

这一类我用得最多的还是 github-readme-stats，可以直接在 README 里生成统计卡片。

README.htmlhtml

<img height="190px" width="100%" src="https://github-readme-stats.vercel.app/api?username=JJLibra&theme=radical&show_icons=true&count_private=true" />

同一个项目还可以顺手展示最常用语言：

README.htmlhtml

<img height="190px" width="100%" src="https://github-readme-stats-git-masterrstaa-rickstaa.vercel.app/api/top-langs/?username=JJLibra&theme=radical&show_icons=true&count_private=true&layout=compact" />

连续提交、奖杯、活动图

如果你比较在意“动态展示感”，这几个也挺常见。

先是连续提交天数：

README.htmlhtml

<img src="https://github-readme-streak-stats.herokuapp.com/?user=JJLibra&theme=default&hide_border=true" />

再是奖杯墙：

GitHub Profile Trophy

README.htmlhtml

<img src="https://github-profile-trophy.vercel.app/?username=JJLibra&theme=juicyfresh&column=9&rank=-U" />

还有活动图：

README.htmlhtml

<img src="https://github-readme-activity-graph.vercel.app/graph?username=JJLibra&custom_title=Xxfer's%20GitHub%20Activity%20Graph&bg_color=141321&color=A9FEF7&line=626069&point=F8D847&area_color=FE428E&title_color=FE428E&area=true" />

这些东西的共同特点就是：不难，但参数多。真正花时间的不是“能不能用”，而是“你想把它调成什么样”。

徽章、访问量和一些杂项

这部分就更偏“装饰”和“补信息”了。

比如 Shields 可以生成各种技术栈徽章：

README.htmlhtml

<img src="https://img.shields.io/badge/-HTML5-E34F26?style=flat-square&logo=html5&logoColor=white" />
<img src="https://img.shields.io/badge/-CSS3-1572B6?style=flat-square&logo=css3" />
<img src="https://img.shields.io/badge/-JavaScript-orange?style=flat-square&logo=javascript" />

访问量徽章也很常见：

README.htmlhtml

<img src="https://komarev.com/ghpvc/?username=JJLibra&label=Views&color=0e75b6&style=flat" alt="访问量统计" />

还有一些可选的组件，比如 IT 笑话、名人名言、Spotify、社交数据统计之类：

Joke：随机 IT 笑话
Quotes：随机名言
Spotify：最近在听的歌
社交统计：如 LeetCode 等站点的数据

这类组件更偏“增味剂”。有没有都不影响主页结构，但加得合适，确实会让页面看起来没那么死板。

第二类玩法：需要 GitHub Actions，动态数据会更多

到了这一步，GitHub Profile 的玩法就开始从“贴图片链接”升级成“定时生成内容”。

原理其实不复杂：
你配置一个 GitHub Actions 工作流，让它定时运行，生成 SVG、更新 README 或者写回某些文件；而你的 Profile README 再去引用这些文件。这样页面看起来就像在“自动更新”。

但麻烦也从这里开始了。你会开始接触：

GitHub Actions 工作流
Secrets / Token
仓库权限
定时任务 cron
README 中的占位注释

所以这部分我建议别一口气全上，挑最感兴趣的先折腾。

3D Contribution

这是把贡献日历做成立体效果的那种玩法。

原理就是 GitHub Actions 定时生成 SVG，然后 README 去引用这个 SVG。

.github/workflows/3D-contrib.ymlyml

name: 3D Contrib

on:
  schedule:
    - cron: "0 21 * * *"
  workflow_dispatch:

permissions:
  contents: write
  pages: write

jobs:
  build:
    runs-on: ubuntu-latest
    name: generate-github-profile-3d-contrib
    steps:
      - uses: actions/checkout@v2
      - uses: yoshi389111/github-profile-3d-contrib@0.7.0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          USERNAME: ${{ github.repository_owner }}
      - name: Commit & Push
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add -A .
          git commit -m "generated"
          git push

README 里引用：

README.htmlhtml

<img src="https://cdn.jsdelivr.net/gh/JJLibra/JJLibra/profile-3d-contrib/profile-night-rainbow.svg" />

这个相对省心，因为它直接用工作流自动提供的 GITHUB_TOKEN，不用你额外手搓 Token。

Snake Contribution

这个就是很多人都玩过的“贪吃蛇吃贡献格子”。

我当时用的是下面这个工作流：

.github/workflows/Snake-contrib.ymlyml

name: Snake Contrib

on:
  schedule:
    - cron: "0 20 * * *"
  workflow_dispatch:

jobs:
  generate:
    runs-on: ubuntu-latest
    environment:
      name: GH_TOKEN
    timeout-minutes: 10

    steps:
      - name: generate github-contribution-grid-snake.svg
        uses: aelassas/snk/svg-only@main
        with:
          github_user_name: ${{ github.repository_owner }}
          outputs: |
            dist/profile-snake-contrib/github-contribution-grid-snake.svg
            dist/profile-snake-contrib/github-contribution-grid-snake-dark.svg?palette=github-dark

      - name: push github-contribution-grid-snake.svg to the output branch
        uses: crazy-max/ghaction-github-pages@v3.1.0
        with:
          target_branch: main
          build_dir: dist
          keep_history: true
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}

README 引用：

README.htmlhtml

<img alt="github-snake" src="https://cdn.jsdelivr.net/gh/JJLibra/JJLibra/profile-snake-contrib/github-contribution-grid-snake-dark.svg" />

这个我当时踩坑比较多，主要集中在三件事上：

这里最容易翻车的地方

Environment secrets 的名字要和工作流里写的一致，比如这里的 GH_TOKEN
仓库权限要允许 Actions 读写
工作流运行成功后，如果本地仓库没同步，后续自己再 push 时可能会出现提交冲突

我当时本地处理冲突用的是：

git-fix.shbash

git add .
git commit -m "update"
git fetch
git merge origin FETCH_HEAD
git push

Fork / Star 统计

这个玩法不显示在 README 图片里，而是直接修改仓库介绍文字，用来展示仓库当前的 star 和 fork 数据。

.github/workflows/fork-star.ymlyml

name: Update Fork Star

on:
  fork:
  watch:
    types:
      - started
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    environment:
      name: ACCESS_TOKEN
    steps:
      - name: This repo has x stars y forks
        uses: ouuan/This-repo-has-x-stars-y-forks-action@v2
        with:
          token: ${{ secrets.ACCESS_TOKEN }}
          template: "Xxfer's profile with <starCount> stars and <forkCount> forks 🎉"

这个思路挺有意思，但说实话，更偏“有趣”而不是“必要”。

Metrics

如果你想把 GitHub 首页玩得更细、更满、更像一块信息面板，那 metrics 基本绕不过去。

它能生成的东西非常多，比如：

基础信息总览
全年等轴贡献日历
语言分析
stargazers
stars 列表
habits 图表
pinned repositories
achievements
recent activity

我当时的配置比较长，所以这里只保留一个最基础的示例思路。更完整的玩法还是建议直接看你自己项目里的配置文件。

.github/workflows/metrics.ymlyml

name: Metrics
on:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

jobs:
  github-metrics:
    runs-on: ubuntu-latest
    environment:
      name: METRICS_TOKEN
    permissions:
      contents: write
    steps:
      - name: base
        uses: lowlighter/metrics@latest
        with:
          filename: github-metrics/base.svg
          token: ${{ secrets.METRICS_TOKEN }}
          user: JJLibra
          template: classic
          config_timezone: Asia/Shanghai
          base: "header, activity, community, repositories"
          plugin_traffic: yes
          plugin_lines: yes
          plugin_introduction: yes
          plugin_gists: yes

README 里引用：

README.htmlhtml

<img src="https://cdn.jsdelivr.net/gh/JJLibra/JJLibra/github-metrics/base.svg" />

我的建议是：
别一上来就把 Metrics 所有插件全开。
不然你会得到一堆 SVG、一堆工作流、一堆配置，然后自己先把自己绕晕。

这两个属于“把 GitHub 之外的数据接进来”。

一个是展示你的日常编程时间统计，一个是展示博客或豆瓣之类的动态。

WakaTime 的核心是把官网后台的 Secret API Key 配到仓库 Secret 里，然后用 Action 自动把数据写进 README 指定区域。它的特点是：不是引用一张图，而是直接往注释区间里插内容。

比如 README 里要预留：

README.htmlhtml

<!--START_SECTION:waka-->

<!--END_SECTION:waka-->

Social Readme 也是类似思路，可以把博客 RSS、豆瓣动态之类拉进来：

README.htmlhtml

<!-- START_SECTION:blog -->

<!-- END_SECTION:blog -->
<!-- START_SECTION:douban -->

<!-- END_SECTION:douban -->

这类东西挺适合本身就有博客、书影音记录或者外部内容输出的人。没有的话，也不用硬上。

关于 Token、权限和踩坑

如果你只是玩第一类“静态组件”，其实不会遇到太多权限问题。真正麻烦的，基本都出现在 GitHub Actions 这边。

我自己当时最常遇到的坑，无非就是下面几种：

Secret 名字和工作流里写的不一致
Token 放错位置，Repository secrets 和 Environment secrets 混了
Actions 没开写权限，导致生成文件后无法提交
工作流写回仓库后，本地仓库和远程不同步

其中有一个设置最好提前改好，不然很多工作流会直接卡住：

一个很关键的权限设置

仓库的 Settings -> Actions -> General 里，把工作流权限改成 Read and write permissions。
不然有些需要回写文件的 Action 根本推不上去。

如果你对 GitHub Token、API、Actions 这些东西本身还不太熟，建议单独先补一下基础，不然这篇文章里后半部分会越看越乱。

最后放两个我觉得挺有参考价值的仓库

真正要找灵感，还是多看别人怎么排版、怎么组合、怎么控制密度。

awesome-github-profile-readme

收录了大量 GitHub Profile README 案例，适合找风格和布局灵感。

awesome-github-profile-readme-chinese

中文向整理版本，阅读门槛更低一点。

另外，我当时也参考过这篇文章：

打造个性化的 GitHub 首页

一篇比较早但很有参考价值的 GitHub Profile 折腾记录。

写在最后

折腾 GitHub 首页这件事，严格来说并不重要。

它不会直接提升你的算法水平，不会自动让项目变多，也不会因为多几个炫酷卡片就让人高看你一眼。但它确实能让你把“自己的公开主页”慢慢收拾成一个更像自己的地方。你可以把作品、状态、偏好、甚至一点点审美，都塞进这个 README 里。

对我来说，这件事最有意思的地方不只是“好看”，而是它把很多原本零散的东西串起来了：Markdown、HTML、第三方服务、GitHub Actions、Token、SVG、自动更新。折腾完以后回头看，会发现自己其实顺手把不少东西也摸了一遍。

GitHub 首页 DIY 的乐趣，不在于把页面堆得多满，
而在于你终于能把这个地方，慢慢改成自己的样子。

如果你只是想快速搭一个能看的版本，那这篇前半部分就已经够用；如果你想把动态数据、自动更新、各种花活都塞进去，那后半部分大概能帮你少踩几个坑。

当然，最后还是老规矩：
要是这篇文章或者我的 GitHub 首页对你有一点点帮助，欢迎顺手点个免费的 Star。

GitHub 首页 DIY：花里胡哨指数++

评论区