GitHub Contributions Chart 项目安装和配置指南
项目地址: https://gitcode.com/gh_mirrors/gi/github-contributions-chart 还在为无法直观展示GitHub贡献记录而烦恼吗？想要一张精美的贡献图表用于社交媒体分享吗？GitHub Contributions Chart项目正是你需要的解决方案！本文将为你提供完整的安装和配置指南，让你快速搭建属于自己的贡献图表生成器。
📋 项目概述
GitHub Contributions Chart是一个基于Next.js的开源项目，能够生成用户GitHub贡献历史的可视化图表。它通过获取GitHub贡献页面数据，使用Canvas技术绘制出美观的贡献热力图，支持多种主题和导出功能。
核心特性
- 🎨 多种主题选择
- 📊 完整的贡献数据统计
- 💾 PNG图片导出
- 📋 JSON数据下载
- 📱 响应式设计
- 🔗 社交媒体分享
🛠️ 环境要求
在开始安装前，请确保你的系统满足以下要求：
| 组件 | 最低版本 | 推荐版本 |
|---|---|---|
| Node.js | 16.x | 18.x或更高 |
| npm | 7.x | 9.x或更高 |
| Git | 2.x | 2.30+ |
📥 安装步骤
1. 克隆项目仓库
首先，你需要将项目克隆到本地：
git clone https://gitcode.com/gh_mirrors/gi/github-contributions-chart.git
cd github-contributions-chart
2. 安装依赖包
项目使用npm作为包管理器，安装所有必要的依赖：
npm install
安装过程会下载以下核心依赖：
3. 配置环境变量（可选）
项目支持以下环境变量配置：
// 在根目录创建.env.local文件
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_GA_TRACKING_ID=你的Google Analytics ID
🚀 运行项目
开发模式运行
使用以下命令启动开发服务器：
npm run dev
服务器将在 http://localhost:3000 启动，支持热重载功能。
生产环境构建
构建生产版本：
npm run build
npm start
⚙️ 配置详解
API路由配置
项目的核心API位于 src/pages/api/v1/[username].js：
// API请求处理流程
sequenceDiagram
participant Client as 客户端
participant API as API路由
participant Fetch as 数据获取
participant GitHub as GitHub
Client->>API: GET /api/v1/username
API->>Fetch: fetchDataForAllYears(username)
Fetch->>GitHub: 请求贡献数据
GitHub-->>Fetch: 返回HTML内容
Fetch->>Fetch: 解析数据
Fetch-->>API: 格式化数据
API-->>Client: JSON响应
数据获取机制
项目使用cheerio库解析GitHub页面：
// 数据解析示例
async function fetchDataForYear(url, year, format) {
const data = await fetch(`https://github.com${url}`);
const $ = cheerio.load(await data.text());
// 解析贡献天数
const $days = $("table.ContributionCalendar-grid td.ContributionCalendar-day");
return {
year,
total: contribCount,
contributions: $days.get().map((day, index) => {
return {
date: $(day).attr("data-date"),
count: index === 0 ? contribCount : 0,
color: COLOR_MAP[$(day).attr("data-level")],
intensity: $(day).attr("data-level") || 0
};
})
};
}
主题配置
主题配置位于 src/components/themes.js：
const themes = [
{ value: "standard", label: "Standard" },
{ value: "githubDark", label: "GitHub Dark" },
{ value: "halloween", label: "Halloween" },
{ value: "teal", label: "Teal" },
{ value: "leftPad", label: "Left Pad" },
{ value: "dracula", label: "Dracula" },
{ value: "blue", label: "Blue" },
{ value: "panda", label: "Panda" },
{ value: "sunny", label: "Sunny" },
{ value: "pink", label: "Pink" },
{ value: "yelp", label: "Yelp" }
];
🔧 自定义配置
修改默认端口
如需修改开发服务器端口，在package.json中添加：
{
"scripts": {
"dev": "next dev -p 3001",
"start": "next start -p 3001"
}
}
添加自定义主题
- 首先在 github-contributions-canvas 仓库中添加主题
- 然后在本项目的 themes.js 中添加主题选项
配置网络请求（如需要）
如果遇到GitHub API限制，可以配置请求参数：
// 在fetch.js中修改请求配置
const data = await fetch(`https://github.com${url}`, {
headers: {
"x-requested-with": "XMLHttpRequest",
"User-Agent": "你的自定义User-Agent"
},
// 连接配置
agent: new https.Agent({
keepAlive: true,
maxSockets: 10
})
});
🐛 常见问题解决
1. 安装依赖失败
问题: npm install 失败 解决方案:
# 清除npm缓存
npm cache clean --force
# 使用yarn替代
yarn install
2. 开发服务器无法启动
问题: 端口被占用 解决方案:
# 查找占用端口的进程
lsof -ti:3000
# 终止进程
kill -9 <PID>
# 或使用其他端口
npm run dev -- -p 3001
3. GitHub数据获取失败
问题: 403 Forbidden错误 解决方案:
- 检查GitHub账号的贡献设置为公开
- 添加适当的请求延迟
- 调整请求频率
4. Canvas绘制问题
问题: 图表显示异常 解决方案:
// 在draw函数中添加错误处理
const draw = async () => {
try {
const { drawContributions } = await import("github-contributions-canvas");
drawContributions(canvasRef.current, {
data,
username: username,
themeName: theme,
footerText: "Made by @sallar & friends"
});
} catch (error) {
console.error("Canvas绘制错误:", error);
setError("图表生成失败，请重试");
}
};
📊 性能优化建议
1. 缓存策略优化
// 在API路由中添加缓存头
res.setHeader('Cache-Control', 's-maxage=86400, stale-while-revalidate')
2. 图片懒加载
// 使用Next.js Image组件优化图片加载
import Image from 'next/image';
<Image
src="/loading.gif"
alt="Loading..."
width={200}
height={200}
priority={false}
/>
3. 代码分割
// 动态导入heavy模块
const { drawContributions } = await import("github-contributions-canvas");
🚀 部署方案
Vercel部署（推荐）
- 连接GitHub仓库到Vercel
- 自动部署每次git push
- 享受全球CDN加速
自有服务器部署
# 构建生产版本
npm run build
# 使用PM2管理进程
pm2 start npm --name "contributions-chart" -- start
# 配置Nginx反向代理
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
📈 监控和维护
健康检查配置
// 添加健康检查端点
// pages/api/health.js
export default async function handler(req, res) {
res.status(200).json({
status: 'ok',
timestamp: new Date().toISOString(),
uptime: process.uptime()
});
}
日志记录
// 添加请求日志中间件
export default async function handler(req, res) {
console.log(`[${new Date().toISOString()}] API Request: ${req.url}`);
// ...处理逻辑
}
🎯 总结
通过本指南，你已经掌握了GitHub Contributions Chart项目的完整安装和配置流程。这个项目不仅提供了美观的贡献图表生成功能，还具备高度的可定制性和扩展性。
关键收获：
- ✅ 掌握了项目环境搭建和依赖安装
- ✅ 理解了数据获取和图表生成的原理
- ✅ 学会了自定义配置和主题扩展
- ✅ 掌握了常见问题的解决方法
- ✅ 了解了性能优化和部署方案
现在就开始行动，搭建属于你自己的GitHub贡献图表生成器吧！如果在实施过程中遇到任何问题，欢迎查阅项目文档或寻求社区帮助。
记得给项目点个Star⭐支持开源开发，也欢迎提交PR贡献你的改进方案！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
