🤖 AI 跟我学 新手入门

Gemini GitHub 教程：读代码库当你的 AI 同事

Gemini GitHub 教程：手把手教你把 GitHub 仓库授权给 Gemini 做代码库分析，覆盖 Gemini 读代码、GitHub Gemini、代码库分析全流程

发布 2026/05/20 📎 参考官方文档

30 秒了解：Gemini GitHub 是什么

Gemini GitHub 扩展是 2026 年 Google 给 Gemini 加的「连接你 GitHub 账号、直接读你公开和私有仓库」的能力：开了之后，你可以直接在 Gemini 对话框里输入仓库地址（github.com/yourname/repo），让它做整库 review、找 bug、写测试、解释陌生代码、补文档，甚至帮你写 PR 描述。 不用再复制粘贴文件，也不用挂 IDE 插件，Gemini 端到端读完整仓库。

Gemini GitHub 和 Cursor / Claude Code 这种「IDE 内代码助手」的关键差别：

  • Cursor / Claude Code：跑在本地 IDE 里，改代码 + 看 git diff，专为「写新代码」优化
  • Gemini GitHub：跑在 Gemini App 里，主要做「读懂 + 解释 + 评审 + 补全文档」，专为「理解陌生代码 + 整库分析」优化

适合场景：

  • 新加入团队，要快速搞懂老项目
  • 接手开源仓库做二次开发，先要读懂架构
  • code review 前自动跑一遍找出明显问题
  • 写技术文档 / API 文档
  • 学习开源项目（react、langchain、playwright 等）

下面把入口、授权步骤、5 个高频玩法、5 个常见坑讲完。

准备工作

  • 入口：Gemini 网页版设置 → Apps → GitHub
  • 账号：免费版可用，AI Plus / Pro 解锁更大仓库和更多并发查询
  • GitHub 权限：第一次会跳 GitHub 授权页，可选只授权某几个仓库（推荐），也可全量
  • 仓库大小：单仓库代码量上限约 10 万行，超出会自动截取核心目录
  • 网络：跟主 Gemini 一样需海外网络环境，详见 Gemini 国内可以用吗

如果你想了解 AI 编程整体方向，先看 AI 编程教程 cluster。

详细操作步骤

第 1 步：开启 GitHub Connected App

进入 gemini.google.com 设置 → Apps → 找到 GitHub → 点开关。

[此处放截图：Apps 设置页 GitHub 行]

弹出 GitHub 授权页，你能看到 Gemini 申请的权限范围：

  • Read access to code, metadata, issues, pull requests
  • Read access to commit statuses
  • 默认不要写权限

重要选择：

  • All repositories：所有公开 + 私有仓库都给 Gemini 读（方便但范围大）
  • Only select repositories：只勾你想给的几个（推荐，公司机密代码别全放）

点 Authorize，回到 Gemini 设置页，GitHub 开关已变蓝。

第 2 步：在对话框引用仓库

回到 Gemini 主对话框，输入：

@github yourname/your-repo 这个仓库主要做什么的？给我画一份架构图。

Gemini 会自动调 GitHub extension 拉仓库结构 + 文件内容做分析。

或者直接粘整个 GitHub URL：

帮我读 https://github.com/langchain-ai/langchain 看看它的核心模块是怎么组织的。

[此处放截图：对话框里粘 GitHub 链接后的回复]

第 3 步：限定到具体文件 / 分支

整库太大时定位到具体路径：

看一下 yourname/repo 里 src/auth/ 目录下所有文件，找出潜在的安全问题。

或者指定分支：

对比 yourname/repo 的 main 和 feature/new-payment 分支差异，总结这个 PR 做了什么。

第 4 步：让 Gemini 写 PR / Issue

读完代码可以让 Gemini 起草：

基于刚才看到的 feature/new-payment 分支，帮我写一份 PR 描述，包括：背景、改动列表、测试覆盖、上线 checklist。

或者：

基于 src/billing.py 第 145-180 行的潜在 bug，帮我写一份 GitHub Issue：标题、复现步骤、预期 vs 实际、可能修复方案。

Gemini 给出 markdown 草稿，你复制到 GitHub 创建 issue / PR。

第 5 步：撤销授权

不想给 Gemini 读了：

  • 临时：Settings → Apps → 关 GitHub 开关
  • 彻底：去 github.com/settings/applications 找到 Gemini，点 Revoke

5 个 Gemini GitHub 进阶玩法

玩法 1：新人入职 1 小时摸清项目

刚加入团队，老项目代码 50k 行：

📋 Prompt 模板 
我刚加入团队，需要快速摸清 yourcompany/main-app 这个项目。请：
    

  1. 整体架构图：核心模块、它们之间的依赖关系，用 mermaid 语法
    2. 

  2. 技术栈清单：后端语言 / 框架、前端框架、数据库、第三方依赖 top 10
    3. 

  3. 代码风格：用了什么 lint / formatter、命名约定
    4. 

  4. 关键业务流程：列出 3 个最核心的业务流（如登录 / 下单 / 支付），每个流的入口文件、关键函数
    5. 

  5. 测试情况：测试覆盖率估计、测试框架、测试目录结构
    6. 

  6. 我作为新人，第一周应该读哪 5 个文件？为什么？
    7. 

中文输出，markdown 格式。

1 小时上手新项目的最快方式。

玩法 2：PR 自动 review

提 PR 前让 Gemini 先过一遍：

📋 Prompt 模板 
对比 yourname/repo 的 main 分支和 feature/xxx 分支差异，做一次 PR review：
    

  1. 改动概览：增 / 改 / 删的文件总数、代码行数
    2. 

  2. 主要逻辑变化：用大白话解释每个改动的意图
    3. 

  3. 潜在 bug：可能的 null / 越界 / 死循环 / SQL 注入 / 并发问题
    4. 

  4. 代码质量问题：命名、重复、可读性、缺测试
    5. 

  5. 是否破坏了现有 API：向后兼容性分析
    6. 

  6. 上线风险等级评估（低 / 中 / 高）+ 建议的回滚方案
    7. 

  7. 5 个 reviewer 应该重点看的问题
    8. 

中文输出。

正式提 PR 前自己跑一遍，省 reviewer 30 分钟。

玩法 3：开源项目深度学习

学一个开源项目源码（比如 langchain）：

📋 Prompt 模板 
我想深度学习 langchain-ai/langchain 这个项目，希望搞懂 LangChain 的核心抽象。请：
    

  1. 解释 LangChain 的 6 个核心概念（LLM / PromptTemplate / Chain / Agent / Memory / Tool）每个对应的源码位置 + 一句话职责
    2. 

  2. 选 1 个具体的 chain 实现（如 LLMChain），从源码角度讲清楚它的调用流程：用户 invoke 后，代码内部走了哪些步骤
    3. 

  3. 这个项目的设计模式：用了哪些经典 OOP 模式（工厂 / 策略 / 模板方法等）
    4. 

  4. 我作为开发者要扩展自定义 Tool / Chain，最应该读的 3 个文件是什么
    5. 

中文输出，含代码片段引用。

比看 10 篇博客学的扎实，源码不撒谎。

玩法 4：技术债扫描

老项目里找历史包袱：

📋 Prompt 模板 
扫描 yourcompany/old-project 整库，找出所有技术债：
    

  1. 标记 // TODO / // FIXME / // HACK 的注释，按数量排序的文件 top 10
    2. 

  2. 重复代码：找出 3+ 处明显重复的逻辑
    3. 

  3. 过时依赖：package.json / requirements.txt 里有没有已废弃 / 多年未更新的库
    4. 

  4. 死代码：可能从未被调用的函数（基于调用图分析）
    5. 

  5. 测试缺失：哪些核心模块没有对应测试文件
    6. 

  6. 文档缺失：哪些公共 API 缺 docstring
    7. 

  7. 给一份「下一季度还技术债优先级清单」（按 ROI 排）
    8. 

中文输出。

技术主管季度规划时跑一份，比 SonarQube 直观。

玩法 5：API 文档自动生成

老代码缺文档：

📋 Prompt 模板 
读 yourname/repo 里 src/api/ 目录的所有路由文件，自动生成一份 RESTful API 文档：
    

  1. 按资源分组（用户 / 订单 / 商品 …）
    2. 

  2. 每个 endpoint 给出：

      

    • HTTP 方法 + 路径
      • 

    • 请求参数（query / body / path）的类型和含义
      • 

    • 响应结构（成功 + 失败）
      • 

    • 鉴权要求
      • 

    • 错误码列表
      • 

    

    3. 

  3. 推荐用 OpenAPI 3.0 yaml 格式输出，方便导入 Swagger / Postman
    4. 

  4. 中文注释，对每个字段加一句业务含义
    5. 

输出 markdown 或 yaml。

零基础接手老项目的同学第一周必备。

5 个 Gemini GitHub 常见坑

坑 1：仓库太大，分析不完整

10 万行以上仓库，Gemini 只看了一部分。

解法：

  • 在 prompt 里明确限定目录：「只看 src/core/ 这个目录」
  • 分多次问，每次聚焦一个模块
  • 用 .gemini-ignore 文件（如果支持）排除无关目录（如 node_modules、dist、tests/fixtures）
  • 重度场景考虑 Claude Code 教程 等本地 IDE 工具，全代码索引更稳

坑 2：私有仓库报无权限

明明授权了，Gemini 说找不到仓库。

解法：

  • 检查 GitHub 授权时是「All repositories」还是「Only select」，没选到这个仓库的话补勾
  • Enterprise GitHub 账号有时要管理员单独 enable Gemini Apps
  • Fork 来的仓库需要分别确认 fork 源和你的 fork 是否都在授权范围
  • 公司内部企业账号被 IT 限制了 OAuth，找 IT 解封

坑 3：代码解释「编造」函数

Gemini 描述了一个函数但仓库里其实没有。

解法：

  • prompt 末尾加「严格基于代码原文，找不到就说找不到，不要推测函数」
  • 让 Gemini 附文件路径 + 行号引用：「每个论点请附 src/foo.py:42-60 出处」
  • 复杂功能查询用 git grep / 本地 IDE 双重验证
  • 一次问太多容易混，分小问题问

坑 4：中文 vs 英文回答的代码理解差

同一个仓库用中文问回答粗糙，用英文问详细一些。

解法：

  • 技术细节深度查询用英文 prompt，结果让 Gemini 再翻译成中文
  • 关键术语保留原文（不要硬翻 dependency injection → 「依赖注入」当变量名）
  • prompt 写「Reply in Chinese but keep all class/function names in original English」

坑 5：私有 token / 密钥被读到回复里

老代码里硬编码了 API key，Gemini 总结时把它显示出来。

解法：

  • 立刻撤销那个 key（去对应平台重新生成）
  • 仓库里删掉硬编码秘钥，改用 .env + git filter-branch 清历史
  • 给 Gemini 的 prompt 加「请屏蔽任何看起来像密钥 / token / 密码的字符串，用 *** 替代」
  • 长期方案：仓库接 git-secrets / GitHub Secret Scanning，发现就拦

Gemini GitHub vs Claude Code vs Cursor vs GitHub Copilot

维度Gemini GitHubClaude CodeCursorGitHub Copilot
形态Gemini App 内对话本地 CLI / IDE独立 IDEIDE 插件
主用场景读懂 + 评审 + 文档写代码 + 改 bug写代码 + agent行内补全
整库索引强强强中
自动改文件不直接直接直接不（只补全）
多文件协同强最强强中
跑测试 / 跑代码弱强强弱
起步价AI Plus 19.99 美元API 按用量20 美元 / 月10 美元 / 月
适合阅读理解 + 文档大改代码日常写代码行内补全

结论：

  • 读懂陌生代码 + 写文档 + PR review → Gemini GitHub
  • 大改 / 重构 / 多文件协调 → Claude Code 教程
  • 日常 IDE 写代码 → Cursor / Copilot
  • 几种都可以同时用，分工不冲突

在中国能用吗

Gemini GitHub 跟主 Gemini 一样需要海外网络环境 + Google 账号。GitHub 本身国内访问不稳定，建议配合稳定网络代理。

国产替代（代码 AI 助手）：

  • 通义灵码（阿里）：免费、中文好
  • CodeGeeX（智谱）：开源、本地化
  • 百度 Comate：百度生态
  • 字节 MarsCode：豆包同源

国内私有 Git（GitLab 自部署 / Gitee / Coding）目前 Gemini 不原生支持，要把代码 export 后用 Gemini 上传 PDF 文件 替代分析。

下一步

把 GitHub 玩熟，接着看：

常见问题

Q：Gemini 会拿我的私有代码训练吗？ A：消费者版（个人 Gmail）默认会用于改善 Google 产品（除非你关 Apps Activity）。Workspace 企业版默认不训练。重要私有代码建议先用公开仓库测试。

Q：能让 Gemini 直接提交 PR 吗？ A：默认是「读权限」，不能直接 push / commit。你想让它自动改代码 + 提 PR，目前需要走 GitHub Actions + Gemini API 的工程方案，普通用户不直接支持。

Q：支持 GitLab / Bitbucket / Gitee 吗？ A：目前主要支持 GitHub。其他平台暂不直接连，要把代码 export 成 zip 后用 Gemini 上传 PDF 当文件分析。

Q：单仓库 10 万行上限怎么应对？ A：大型 monorepo 建议聚焦子目录（在 prompt 里明确路径范围）。或者用 git sparse-checkout 拉子集到一个新仓库再让 Gemini 看。

Q：支持私有 GitHub Enterprise（自部署）吗？ A：标准 GitHub Enterprise Cloud 大部分支持，自部署 GitHub Enterprise Server（GHES）需要管理员明确开放给 Gemini 的 OAuth 应用。问 IT。

Q：能让 Gemini 跑代码 / 运行测试吗？ A：Gemini App 内本身不能跑代码（不像 Claude Code 有沙箱执行）。要执行代码用 Claude Code 或本地 IDE。Gemini 能读 CI 历史 / 测试报告做分析。

Q：每天能查多少次 GitHub？ A：未官方公开具体数字。免费版高频查询会限流（出现「rate limit reached」提示），AI Plus / Pro 配额数倍提升。