GitHub 常见高频问题与解决方案（实用手册）

1.Push 提示权限错误（Permission denied）

问题：

Bash                   Permission denied (publickey)                   fatal: Could not read from remote repository.

原因： 没有配置 SSH key 或使用了 HTTPS 而没有权限。

解决方法：

Bash                   生成 SSH 密钥（如果还没有）                   ssh-keygen -t rsa -C "你的邮箱"                   将生成的 ~/.ssh/id_rsa.pub 添加到 GitHub：Settings → SSH and GPG Keys

2.push 报错：rejected non-fast-forward

问题：

Bash                   error: failed to push some refs to ...                   hint: Updates were rejected because the tip of your current branch is behind ...

原因： 本地代码落后于远程，需要先 pull。

解决方法：

Bash                   git pull origin main --rebase                   然后再 push                   git push origin main

3.忘记添加 .gitignore，上传了无关文件

解决方法：

1.添加或修改 .gitignore 文件

2.移除已跟踪的无用文件：

Bash                   git rm -r --cached .                   git add .                   git commit -m "更新 .gitignore"                   git push

4. 撤销最近一次 commit

方法 1：只改 commit 信息，不改内容

Bash                   git commit --amend

方法 2：撤回 commit

Bash                   git reset --soft HEAD~1  # 回退提交但保留改动

5.clone 太慢或失败

解决方法：

• 使用国内镜像（如 GitHub 镜像或代理）

• 或使用 SSH 克隆：

Bash                   git clone [e-mail]:xxx/xxx.git

6.如何切换/创建分支

Bash                   创建并切换新分支                   git checkout -b dev                   切换已有分支                   git checkout main

7.如何合并分支

Bash                   git checkout main         # 切换到主分支                   git merge dev             # 合并 dev 分支

有冲突时：

• 手动解决文件冲突

• git add . → git commit

8.如何删除远程分支

Bash                   git push origin --delete 分支名

9.如何 Fork + PR（Pull Request）参与开源项目？

1.点击项目页面右上角 Fork

2.克隆到本地 → 创建新分支开发

3.提交 → Push 到自己仓库

4.打开自己仓库 → 点 "Compare & pull request"

5.提交 PR 给原项目

10.如何清除 Git 缓存的用户名密码？

Bash                   git config --global --unset credential.helper

11.克隆仓库失败 / 速度慢

常见报错：

• Connection timed out

• fatal: unable to access ...

解决方案：

• 使用 GitClone 镜像

Bash                   git clone https://gitclone.com/github.com/user/repo.git

• 或使用 SSH 克隆（加快速度）：

Bash                   [e-mail]:user/repo.git

12. GitHub 提示需要访问 Token

报错示例：

Bash                   remote: Support for password authentication was removed

原因：

• GitHub 取消了账号密码登录 Git 操作（2021年后）

解决方案：

• 生成 Personal Access Token

• 用 token 代替密码进行 git push、clone

13. 如何修改或重命名仓库

路径：

仓库首页 → Settings → Repository name → 修改 → Save

注意：

• 更改会改变仓库 URL，需要重新 clone 或更新 remote。

14. 如何同步 Fork 仓库

步骤：

Bash                   git remote add upstream https://github.com/原作者/repo.git                   git fetch upstream                   git merge upstream/main

或使用 rebase 替代 merge 保持提交整洁。

15. 误删了远程分支怎么办？

如果本地还有该分支：

Bash                   git push origin 分支名

如果本地也没有：

• 从另一个开发者获取代码

• 或查看 Pull Request 恢复提交内容

16. 如何设置仓库私密 / 公开

路径：仓库首页 → Settings → Danger Zone → Change visibility

17. 如何上传大文件（>100MB）

GitHub 限制单文件大小为 100MB

解决方案：

• 使用 Git Large File Storage（Git LFS）

Bash                   git lfs install                   git lfs track "*.zip"

18. Actions 运行失败

常见原因：

• 缺少权限（例如私有仓库）

• secrets 配置错误

• 网络原因（如下载超时）

排查建议：

• 查看 Actions logs

• 增加超时或使用国内依赖镜像源

• 设置 secrets 时确保 key/value 正确拼写

19. 删除仓库后能恢复吗？

仓库一旦删除，GitHub 不支持恢复。

建议开启删除保护（Settings → Enable delete protection）

20. Pull Request 无法合并

原因可能包括：

• 有冲突（conflict）

• 分支不是目标分支的子分支

• 权限不足（需有 write 权限）

解决方案：

Bash                   git fetch origin                   git rebase origin/main                   解决冲突后                   git push -f

21. 访问 GitHub 卡顿 / 加载慢

使用加速方式：

• https://ghproxy.com/

• https://gitclone.com/

• DNS 优化（如 223.5.5.5）

• 临时 hosts：使用 GitHub520

22. 贡献指南 CONTRIBUTING.md 不生效？

确保文件路径正确为：

Plain Text                   /.github/CONTRIBUTING.md