概述

相关源文件

• .gitignore
• .vercelignore
• .vscode/extensions.json
• .vscode/settings.json
• CONTRIBUTING.md
• docs/readme_de.md
• docs/readme_es.md
• docs/readme_fr.md
• readme.md
• src/cards/types.d.ts

GitHub Readme Stats 是一个项目，用于为 README 文件生成动态可定制的 GitHub 统计卡片。这些 SVG 卡片展示了各种 GitHub 指标，如 star、commit、PR、issue 和编程语言。用户可以将它们嵌入到他们的 GitHub 个人资料 README 中，以视觉吸引力的方式展示他们的活动和项目。

有关设置开发环境的信息，请参阅 开发指南。

来源: readme.md1-7 CONTRIBUTING.md28-41

系统架构

GitHub Readme Stats 遵循模块化架构，旨在从 GitHub 和可选的 WakaTime API 中获取数据，对其进行处理并生成 SVG 图像。

高层架构

系统的核心组件是

1. API 端点：处理 HTTP 请求和参数解析的入口点
2. 数据获取器：从外部 API（GitHub/WakaTime）检索数据的模块
3. 卡片渲染器：将数据转换为 SVG 图像的组件
4. 主题系统：提供一致的样式选项
5. 国际化系统：处理多语言文本翻译

来源: readme.md85-132 src/cards/types.d.ts1-64

API 端点和卡片类型

每种卡片类型都有其从 API 端点到数据获取，再到最终 SVG 渲染的请求流程。

来源: readme.md133-639

卡片类型

GitHub Readme Stats 提供五种不同的卡片类型，每种都有不同的用途

GitHub Stats 卡

GitHub Stats 卡显示用户统计信息，包括 star、commit、PR、issue 和贡献。它还可以根据这些统计信息显示排名。

仓库卡片

Repository 卡（也称为“GitHub Extra Pins”）允许用户展示 GitHub 默认允许的六个固定仓库之外的仓库。

热门语言卡片

Top Languages 卡根据仓库字节数或仓库数量可视化用户最常使用的编程语言。

WakaTime 卡片

WakaTime 卡与 WakaTime API 集成，显示过去一周在不同语言上花费的编码时间。

Gist 卡片

Gist 卡允许用户突出显示特定的 GitHub Gist。

来源: readme.md134-639

类型系统

该项目使用 TypeScript 通过类型层级来定义卡片选项结构

每种卡片类型都用自己特定的选项扩展了 CommonOptions 接口。

来源: src/cards/types.d.ts4-64

自定义系统

GitHub Readme Stats 通过 URL 参数提供广泛的自定义选项。这些选项分为通用选项（适用于所有卡片）和特定卡片选项。

通用选项

选项	描述	类型	默认
title_color	卡片标题颜色	十六进制颜色	2f80ed
text_color	正文文本颜色	十六进制颜色	434d58
icon_color	图标颜色	十六进制颜色	4c71f2
bg_color	卡片背景颜色	十六进制颜色或渐变	fffefe
theme	主题名称	枚举	默认
border_radius	圆角半径	数字	4.5
border_color	卡片边框颜色	十六进制颜色	e4e2e2
locale	卡片语言	枚举	en
hide_border	隐藏卡片边框	布尔值	false

特定卡片选项

每种卡片类型也有其特有的选项

统计卡片选项

诸如 hide、show_icons、hide_rank、include_all_commits、custom_title 等选项。

仓库卡片选项

诸如 show_owner 和 description_lines_count 等选项。

热门语言卡片选项

诸如 layout、langs_count、hide_progress 和算法配置等选项。

WakaTime 卡片选项

诸如 layout、langs_count、api_domain 和 display_format 等选项。

Gist 卡片选项

诸如 show_owner 等选项。

来源: src/cards/types.d.ts4-64 readme.md285-439

主题系统

主题系统提供可应用于任何卡片的可预定义配色方案。主题为标题、文本、图标和背景定义了一组颜色。

内置主题包括：dark、radical、merko、gruvbox、tokyonight、onedark、cobalt、synthwave、highcontrast、dracula 和 transparent。

来源: readme.md177-283

国际化

该项目通过其翻译系统支持多种语言的本地化。目前支持的语言包括中文、德语、西班牙语、法语、意大利语、日语、韩语、荷兰语以及许多其他语言。

翻译系统允许卡片中的所有文本元素以用户偏好的语言显示。

来源: readme.md313-366

部署选项

虽然大多数用户可以使用公共实例 github-readme-stats.vercel.app，但有一些重要的注意事项

1. GitHub API 速率限制：GitHub API 每小时每个用户限制 5000 个请求
2. 自托管：用户可以在 Vercel 上部署自己的实例来
   • 避免速率限制
   • 访问私有仓库统计信息
   • 进行自定义修改

部署过程使用 Vercel，并且只需要少量配置。

来源: readme.md759-809 CONTRIBUTING.md28-39

系统约束和注意事项

存在几个重要的技术约束

1. API 速率限制：公共实例受 GitHub 速率限制的约束
2. 缓存：卡片被缓存以减少 API 调用（默认：6 小时）
3. 私有数据：只有自托管实例才能访问私有仓库数据
4. 仓库限制：由于 API 限制，Top Languages 卡仅处理前 100 个仓库

来源: readme.md125-502

使用示例

要使用 GitHub Readme Stats，用户需要将其 API URL 嵌入到他们的 GitHub README 中

可以添加参数进行自定义

可以使用 HTML 对齐方式将多个卡片并排放置

来源: readme.md136-736