本文介绍如何通过轻量级方案（如 repo.js）将 github 仓库信息嵌入网页，重点解决因 github 默认分支更改为 `main` 导致的加载失败问题，并提供可立即运行的配置示例与调试方法。
在个人作品集、技术博客或项目主页中直接展示 GitHub 仓库状态（如名称、描述、星标数、最新提交、文件列表等），能显著提升可信度与用户体验。虽然 GitHub 官方不提供原生“iframe 嵌入”功能，但借助成熟的第三方库（如 Repo.js）可快速实现响应式仓库卡片嵌入。
✅ 正确使用 Repo.js 的关键步骤
Repo.js 是一个基于 jQuery 的轻量 JavaScript 库，通过调用 GitHub REST API（v3）动态渲染仓库信息。其最常见失败原因并非代码错误，而是未显式指定仓库分支——自 2020 年起，GitHub 新建仓库默认主分支名已从 master 改为 main，而 Repo.js 旧版默认仍尝试请求 /master 分支，导致 API 返回空数据，进而引发 Cannot read property 'length' of undefined 等控制台报错。
请务必按以下方式显式声明 branch: 'main'（或你仓库实际的默认分支名，如 main、develop、trunk）：
<!-- 1. 引入 jQuery（Repo.js 依赖） -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<!-- 2. 引入 Repo.js -->
<script src="https://cdn.jsdelivr.net/npm/repo.js@1.0.4/dist/repo.min.js"></script>
<!-- 3. 创建容器 -->
<div id="my-repo"></div>
<!-- 4. 初始化（注意：必须指定 branch） -->
<script>
$(function() {
$('#my-repo').repo({
user: 'your-github-username', // 替换为你的 GitHub 用户名
name: 'your-repo-name', // 替换为仓库名（不含用户名）
branch: 'main', // ✅ 关键！必须与仓库实际默认分支一致
show: ['name', 'description', 'stars', 'forks', 'updated'], // 可选：控制显示字段
limit: 5 // 可选：限制文件列表数量
});
});
</script>⚠️ 注意事项与调试建议
- 开启浏览器开发者工具（F12）→ Console 标签页：这是排查嵌入失败的第一步。若出现 404 Not Found，检查 user/name 拼写；若出现 403 Forbidden，说明触发了 GitHub API 限流（未授权请求约 60次/小时），此时建议添加 Personal Access Token（Repo.js 支持 token 参数）；
- CORS 限制：Repo.js 直接调用 GitHub API，现代浏览器会阻止跨域请求（除非 GitHub API 响应头含 Access-Control-Allow-Origin）。幸运的是，GitHub API 默认支持 CORS，但需确保请求 URL 正确（Repo.js 内部已处理）；
-
替代方案参考：
- 若仅需展示 README：可用 <iframe src="https://github.com/username/repo/blob/main/README.md?raw=true" style="width:100%; height:500px;"></iframe>（需配合 ?raw=true，但样式受限）；
- 若需更高定制性：建议直接调用 GitHub REST API（GET https://api.github.com/repos/{owner}/{repo}）+ 自定义渲染，配合 fetch() 和现代框架（如 Vue/React）；
- 若仅嵌入代码片段：优先使用 GitHub Gist 或官方 Embeddable Snippets。
✅ 总结
嵌入 GitHub 仓库无需复杂后端，Repo.js 仍是快速落地的优选方案。核心要点只有两个：一是在初始化时显式传入正确的 branch 参数；二是始终通过浏览器控制台验证 API 请求状态与错误信息。正确配置后，你将获得一个自动更新、无需维护的仓库信息卡片——它不仅展示项目本身，更是你工程严谨性的无声注脚。
