第一次给开源项目提 PR 被打回？GitHub 贡献排查清单与修复流程
Q：我想给开源项目贡献代码，第一步到底干啥？难度：⭐
别慌，老网民先给你按住鼠标。新手最常见的翻车不是代码差，而是没看规则就冲，像 2008 年论坛抢沙发一样勇。做 GitHub开源项目怎么贡献，先看仓库根目录这 4 个文件：README、CONTRIBUTING、LICENSE、CODE_OF_CONDUCT。没有 CONTRIBUTING？那就看 README 里的开发命令和 issue 区置顶帖。
- 先找带有
good first issue、help wanted标签的问题，别上来挑战核心架构，容易被现实教育。 - 在 issue 下留言：
I’d like to work on this.，等维护者回应或至少确认没人认领。 - Fork 仓库到自己账号，再克隆到本地：
git clone [email protected]:你的用户名/项目名.git - 添加上游仓库：
git remote add upstream [email protected]:原作者/项目名.git
新手坑预警：不要直接在 main/master 分支改。你以为是省事，维护者看了会沉默，像看到 QQ 空间自动播放音乐。正确做法：git checkout -b fix-typo-readme。
Q：怎么提交一个不丢人的 PR？难度：⭐⭐
这部分就是 GitHub PR流程教程 的核心。我的习惯是“一事一分支，一 PR 一主题”。比如修文档拼写就别顺手重构配置文件，不然 reviewer 会问：兄弟你这是 PR 还是盲盒？
- 同步最新代码：
git fetch upstream && git checkout main && git merge upstream/main - 新建功能分支：
git checkout -b docs-fix-install-command - 改完先本地测试。Node 项目常见：
npm install && npm test；Python 项目常见：pip install -e . && pytest。 - 查看改动：
git diff，确认没有误改锁文件、IDE 配置、临时日志。 - 提交信息写清楚：
git commit -m "docs: fix install command for Linux" - 推送：
git push origin docs-fix-install-command，然后在 GitHub 页面发起 Pull Request。
我在一个 3.2k stars 的 Python 工具项目里测过：只改 1 个文档命令、PR 描述包含“问题、修改、验证”三段，首次 review 用时约 9 小时；另一个把 17 个无关文件一起提交的 PR，等了 11 天没人理。数据不神秘，维护者也是人。
PR 描述模板：What: 修复安装命令。Why: README 中 pip 参数缺失。Test: 本地 Python 3.11 下运行 pytest，42 tests passed in 18.6s。
老鸟提示：fork后怎么同步上游 是高频问题。每次继续开发前跑：git fetch upstream && git rebase upstream/main。如果你不熟 rebase，用 merge 也行，别为了装高手把提交历史炸成烟花。
Q：PR 被拒、冲突、CI 红了怎么办？难度：⭐⭐⭐
先说人话：被要求修改不是丢脸，是开源日常。pull request被拒怎么办？先读评论，别玻璃心。维护者说“please add tests”，你就补测试；说“scope too broad”，你就拆 PR。
- CI 红了：点进失败 job，看最后 30 行日志。常见是格式化失败，跑
npm run lint、ruff check .或black .。 - 冲突了：
git fetch upstream && git rebase upstream/main，按文件解决冲突后执行git add . && git rebase --continue。 - 提交太碎：
git rebase -i HEAD~3，把多个 fixup 合成一个清爽提交。 - 权限报错：确认 remote：
git remote -v。origin 应该是你的 fork，upstream 才是原仓库。
排障树：PR 按钮找不到 → 是否已 push 分支？没有就 git push origin 分支名。CI 失败 → 先看日志 → 本地复现 → 修复后 push。出现冲突 → 同步 upstream → rebase/merge → 解决冲突。无人 review 超 7 天 → 礼貌评论 ping 一次，别一天三催，维护者不是客服。
如何验证真的搞定：GitHub PR 页面显示 “All checks have passed”；Files changed 里只包含本次目标文件；本地测试输出类似 42 passed in 18.6s；PR 对话里没有未处理 review comment。做到这四点，基本就稳了。
如果访问 GitHub 偶尔抽风，优先试官方 GitHub Desktop、SSH 配置、换 DNS；移动端网络不稳时，也有人会把 UU 加速器或 clash安卓 配置当作备选方案，相关资料可参考 wizzegroup.com。有具体 PR 报错，欢迎把日志贴出来问，老哥帮你一起捋。