Git工作流实战指南：从GitHub Flow到TBD的演进路径

1. 这不是教科书里的 Git而是我每天在终端里敲出来的版本控制逻辑“基于 Git 的版本控制工作流”——这八个字听起来像极了某门大学选修课的结课报告标题。但如果你真在团队里维护过三个以上长期迭代的项目就会发现Git 本身只是个工具真正决定项目生死的是人怎么用它。我做过六年的全栈开发带过四届实习生也接手过被前任“自由发挥”搞崩的遗留仓库。最深的体会是一个没明确定义的工作流比没有 Git 还危险。它不会报错但会在第 17 次合并时突然让你发现 feature/login 页面的登录按钮消失了而 git blame 显示最后修改者是三个月前离职的同事它也不会警告但会在上线前五分钟因为两个分支同时改了同一行配置触发冲突后手忙脚乱地手动删代码。所谓“工作流”说白了就是一套写进 README.md、贴在团队 Wiki 首页、新成员入职第一天就要跑通的“操作契约”。它不解决技术难题但它能防止技术人把时间浪费在救火上。这篇文章不讲git init和git commit -m fix这类入门命令也不堆砌 Git 内部对象模型blob/tree/commit/tag的理论图谱。我们只聚焦一件事当一个真实项目从 0 到 1再到持续交付不同阶段、不同角色、不同规模下到底该用哪条路走为什么这条路能少踩 80% 的坑以及当路被堵死时你手里该攥着哪把铲子。适合刚脱离单机开发、第一次参与协作项目的开发者也适合技术负责人在拍板“我们用 Git Flow 还是 GitHub Flow”之前先看清每条路的碎石和岔口。接下来的内容全部来自我亲手打过的 tag、回滚过的 release、以及在凌晨两点紧急修复生产环境时反复验证过的判断。2. 工作流不是选择题而是分阶段演进的生存策略2.1 为什么不能一上来就套用 Git Flow——从单人小项目到百人协作的三道坎很多人一接触“工作流”概念第一反应就是去搜 Git Flow 图解然后照着画分支develop、release、hotfix、feature/*……结果呢我在某次内部分享会上问过一个刚毕业的前端同学“你们组现在用 Git Flow 吗”他点头“用了master 是线上develop 是测试feature 分支做需求。”我又问“那 feature 分支平均生命周期多长”他愣了一下“大概……两周”我接着问“develop 分支每天 merge 几次”他犹豫“好像……一周一次”——这就暴露了核心矛盾Git Flow 的设计前提是存在一个稳定、高频、可预测的集成节奏。它假设你有专职 QA 在 develop 上跑自动化测试有 CI 系统自动构建预发包有产品同学能接受“本周所有功能都在 develop下周一起上线”的节奏。但现实是很多中小型项目连自动化测试都没有测试靠人工点上线靠老板微信喊“今晚发版”。在这种场景下硬套 Git Flowdevelop 分支就成了“黑洞分支”功能 A 提交了功能 B 也在开发但没人敢合因为怕影响 AA 测试完要上线了B 却还没测完于是只能 cherry-pick A 的 commit结果漏掉了一个修复样式的小提交线上按钮变蓝了……这不是流程的问题是流程和实际能力不匹配。我总结出三个关键适配门槛CI/CD 能力门槛Git Flow 要求 develop 分支始终处于“可部署”状态。这意味着每次 push 到 develop必须触发完整构建 单元测试 接口测试 UI 快照比对。如果这套链路需要人工点击 Jenkins 按钮、等 20 分钟、再手动确认那 develop 就永远不可能稳定。实测下来只有当端到端流水线能在 5 分钟内完成且失败率低于 2%Git Flow 才开始显现出价值。团队认知同步门槛Git Flow 有 5 类分支、7 种标准操作如git flow release start v1.2。新人入职第一天光记清git flow hotfix finish和git flow release finish的区别就得花半天。更麻烦的是语义混淆比如feature/login分支做完后是直接删掉还是保留如果保留下次git checkout feature/login是拉最新代码还是继续上次的脏状态这些细节一旦没对齐merge 时就会出现“咦我昨天改的代码怎么没了”的惨剧。我见过最离谱的一次是两位后端同学同时基于同一个 feature 分支开发A 提交后 B 没 pull 直接改结果 A 的 commit 被 B 的 force push 覆盖了三天的工作量。发布节奏门槛Git Flow 天然适配“固定周期发布”比如每月 1 号上线。但如果业务要求“用户提需求48 小时内上线”或者“大促期间每天发 3 个热修复”那 release 分支的创建、测试、合并、打 tag 一整套流程反而成了瓶颈。这时候一个简单的git checkout main git merge feature/pay git push origin main配合自动化灰度发布效率高出不止一倍。提示判断是否该用 Git Flow只需问自己三个问题① 我们的测试环境能否保证每次 merge 到 develop 后10 分钟内给出“通过/失败”结论② 团队里有没有人能用一句话说清“hotfix 分支和 release 分支的根本区别是什么”③ 上个月我们有多少次发布是“计划外”的如果其中任意一个问题答案是否定的那就别碰 Git Flow至少现在别碰。2.2 GitHub Flow给敏捷团队的“最小可行工作流”当 Git Flow 的齿轮咬合不上现实的齿距时GitHub Flow 就成了最自然的替代方案。它的核心就一句话所有功能开发都在 feature 分支上进行完成即 PRPull Request到 main 分支通过审查和 CI 后直接合并main 始终代表可部署的最新状态。没有 develop没有 release没有复杂的分支命名规范只有 main 和一堆短命的 feature 分支。为什么它能在中小团队快速落地因为它把“复杂性”做了精准切割复杂性交给工具PR 机制天然承载了代码审查Code Review、自动化检查CI、权限控制谁可以 approve、变更追溯谁在何时批准了什么四大功能。你不需要额外建 Confluence 文档规定“review 必须两人签字”GitHub/GitLab 的 UI 就强制了这个动作。复杂性交给时间feature 分支生命周期被压缩到极致。我给自己定的铁律是任何 feature 分支存活时间不得超过 3 天。超过 3 天要么拆成更小的可交付单元要么说明这个需求本身就有问题比如“重构用户中心”这种模糊描述必须拆成“提取用户基础信息模块”“迁移手机号验证逻辑”等具体任务。实测下来分支越短冲突概率越低review 越容易聚焦上线风险越可控。复杂性交给约定GitHub Flow 不禁止你在 main 上直接提交但它用社会性约束代替了技术性约束。比如我们团队的.github/PULL_REQUEST_TEMPLATE.md里明确写着“PR 标题格式[type] #issue-number description例如 [feat] #123 实现扫码登录”。这个看似琐碎的约定让所有人一眼就能分辨出这是新功能、Bug 修复还是文档更新也让自动化脚本能根据[type]自动打标签、触发不同流水线。更重要的是它让“随意提交”变得心理成本极高——当你想绕过 PR 直接 push 到 main 时得先删掉模板里那行“请勿跳过此步骤”这个动作本身就在提醒你“等等你是不是忘了什么”我曾用 GitHub Flow 改造过一个 5 人前端团队。改造前他们用“master dev”双分支但 dev 分支长期积压 20 未测试功能每次上线都要手动 cherry-pick平均耗时 2 小时。切换后第一周就建立了“所有改动必须经 PR”的纪律第二周接入了 Storybook 自动化视觉回归测试第三周实现了 main 分支 push 后 3 分钟内自动部署到预发环境。最直观的变化是上线会议从每周一次、每次 2 小时变成了每日站会中一句“今天 main 有 3 个新功能已自动部署大家可随时验收”。注意GitHub Flow 的致命陷阱是“PR 审查流于形式”。我见过最典型的反模式是PR 描述只写“fix bug”reviewer 点个 approve 就完事。结果上线后发现修复的只是表象根本原因比如某个全局状态管理的竞态条件依然存在。所以我们强制要求 PR 描述必须包含三要素① 问题现象附截图或日志② 根本原因分析哪怕只有一句话③ 验证方式如何复现、如何确认已修复。这三句话比写 100 行注释更能保障质量。2.3 Trunk-Based DevelopmentTBD当你的团队开始挑战“每天 50 次上线”如果说 GitHub Flow 是敏捷团队的“舒适区”那 TBD 就是面向超高速迭代的“极限运动”。它的核心信条只有一条所有开发者每天多次将小增量代码直接提交到 main 分支Trunk禁止长期存在的 feature 分支。是的你没看错——没有 feature/login没有 feature/payment所有代码都直奔 main。这听起来反直觉甚至有点疯狂。但支撑它的是一整套精密的工程实践组合拳微服务与模块化架构TBD 要求每个提交的影响范围足够小。比如支付模块的改动绝不能牵扯到用户中心的数据库 schema。这就倒逼团队必须提前完成服务拆分、API 边界定义、契约测试Consumer-Driven Contracts。我参与过的一个电商后台项目就是先用半年时间把单体应用拆成 12 个独立服务每个服务有自己的数据库和 CI 流水线才敢启动 TBD。强大的自动化防护网TBD 下main 分支的每一次提交都必须通过① 全量单元测试 2 分钟② 关键路径接口测试 5 分钟③ 生产环境影子流量比对Shadow Traffic④ 性能基线校验响应时间波动 5%。缺任何一环TBD 就是自杀式操作。我们当时为支付服务搭建的 CI 流水线光是“模拟 1000 笔并发下单并校验最终账户余额”这一项就花了两周调优。Feature Flag特性开关驱动开发这是 TBD 的灵魂。所有新功能代码必须用开关包裹if (featureFlag.isEnabled(new_checkout_flow)) { renderNewCheckout(); } else { renderLegacyCheckout(); }开发时开关默认关闭测试时打开开关验证上线时代码已在线上只需后台一键开启。这样main 分支永远只有一套代码但行为可动态切换。我们曾用这种方式让“购物车优惠券功能”在上线前一周就通过灰度 1% 用户完成了全链路压力测试而主流程完全不受影响。TBD 的收益极其显著某 SaaS 公司在采用 TBD 后平均发布前置时间Lead Time for Changes从 12 小时缩短到 22 分钟生产环境故障恢复时间MTTR从 47 分钟降到 90 秒。但它的代价同样巨大——它要求团队在架构、测试、监控、发布四个维度都达到行业 Top 10% 的水平。如果你的单元测试覆盖率还不到 60%或者 CI 平均耗时超过 10 分钟那 TBD 对你而言不是加速器而是放大器会把所有隐藏的工程债以十倍速度引爆。3. 核心细节解析分支命名、提交规范与 PR 审查的实战心法3.1 分支命名不是文艺创作而是机器可读的元数据很多人把分支命名当成个人风格展示比如feature/awesome-login-redesign或bugfix/oh-no-i-broke-the-header。这在单人项目里无伤大雅但在协作环境中它直接决定了自动化工具能否高效工作。我们团队的分支命名规则表面看是约束实则是给 CI/CD 系统喂的“结构化饲料”前缀标准化严格限定为feature/、bugfix/、docs/、chore/、refactor/五种。feature/表示新增用户可见功能bugfix/表示修复线上已知问题必须关联 Jira issuedocs/仅限文档修改chore/是纯运维操作如升级依赖refactor/是不改变外部行为的代码优化。这个分类让 Jenkins 流水线能自动触发不同测试集feature/触发全量测试 UI 快照bugfix/只触发相关模块测试 回归用例。ID 强制绑定所有分支名必须包含对应的需求/缺陷 ID格式为feature/JIRA-123-login-flow。这个 ID 不是摆设它被嵌入到 CI 脚本中当流水线检测到分支含JIRA-123会自动从 Jira API 拉取该 issue 的描述、优先级、关联的测试用例并在构建报告中高亮显示。更关键的是它让 Git 的--first-parent参数有了意义——你可以用git log --first-parent main --oneline | grep JIRA-123瞬间定位该需求从开发到上线的完整 commit 链而不用在几十个 feature 分支里大海捞针。语义清晰化禁止使用模糊词如new、update、fix。feature/JIRA-123-login-flow是合格的feature/JIRA-123-new-login就不合格。因为“new”无法表达意图——是新设计新协议还是新第三方 SDK我们要求描述必须指向具体行为“login-flow” 指明是整个登录流程“sms-verification” 指明是短信验证环节。这个细节在代码审查时价值巨大reviewer 看到分支名就能预判要重点检查哪些文件比如login-flow必然涉及auth.service.ts和login.component.html而不是盲目扫视整个 diff。实操心得我们曾因分支名不规范吃过亏。一次紧急修复后端同学建了bugfix/JIRA-456-token-expire但前端同学建了feature/JIRA-456-fix-token。结果 CI 系统以为这是两个独立需求分别触发了两套流水线导致测试环境被重复部署API 网关配置错乱。后来我们加了一条 Git Hookpre-push 阶段用正则校验分支名不合规则拒绝推送并返回提示“请使用标准前缀feature/ bugfix/ docs/ chore/ refactor/”。3.2 提交信息Commit Message是给未来自己写的说明书git commit -m fix bug这样的提交就像在图书馆里把一本书标为“有用的东西”。它对现在的你可能有意义但对三个月后排查线上问题的你就是灾难。我们团队的提交信息规范借鉴了 Angular 团队的约定但做了本土化精简type(scope): subject body footertype同分支前缀feat、fix、docs、chore、refactor。这是最关键的部分它决定了这个 commit 是否会被自动包含在 changelog 中只有feat和fix会。scope修改的影响范围必须是项目中真实存在的模块名如auth、payment、ui-button。禁止使用all、core这类虚词。这个字段让git log --grepauth能精准过滤出所有认证相关变更。subject一句话描述不超过 50 字用祈使句“add”、“remove”、“refactor”不加句号。比如feat(auth): add SMS login support而不是feat(auth): added SMS login support.。body可选但强烈建议。这里写“为什么改”而不是“改了什么”。比如Why: Current email-only login has 32% drop-off rate on mobile. How: Integrate Twilio API for OTP, fallback to email if SMS fails. Test: Added Cypress test for SMS flow, verified on iOS/Android.footer关联外部系统如Closes #123自动关闭 GitHub Issue、Jira: PROJ-456关联 Jira。这套规范的价值在于它让git log从历史记录变成了可执行的文档。有一次支付服务出现偶发性超时运维同学用git log --oneline -n 20 main快速扫描发现最近一个fix(payment): reduce Stripe timeout from 30s to 10s的提交立刻意识到问题根源——我们为了降低响应时间把超时阈值设得太低导致网络抖动时直接失败。如果没有scope和清晰的subject他得逐个点开 20 个 commit 的 diff才能找到这行关键代码。注意我们用commitlint工具在 pre-commit 阶段强制校验。它不仅能检查格式还能识别语义错误。比如如果提交信息是fix(ui-button): add new iconcommitlint会报错“addis not a valid verb for typefixplease useadd,remove,change,refactor”。这个细节把“写好提交信息”从主观意愿变成了客观可执行的标准。3.3 PR 审查不是找茬大会而是知识传递的黄金时刻PRPull Request常被误解为“领导审批流程”但在我带的团队里它被重新定义为“最小粒度的知识共享单元”。一次高质量的 PR应该让 reviewer 在 15 分钟内不仅理解“改了什么”更能掌握“为什么这么改”和“后续怎么维护”。为此我们固化了三项审查原则“三问”审查法每个 reviewer 必须回答三个问题并在评论中明确写出答案Q1这个改动是否解决了 PR 描述中提出的问题验证目标达成Q2这个改动是否引入了新的边界条件或潜在风险比如新增的空值判断是否覆盖了所有 API 返回场景Q3这个改动是否符合团队当前的技术决策比如我们已约定所有异步操作用async/await那就不该出现Promise.then().catch()“上下文”必填项PR 描述模板强制要求填写背景这个问题是从哪里来的用户反馈监控告警技术债梳理权衡为什么选这个方案而不是其他比如为什么不直接改数据库字段而要加兼容层验证如何证明它有效本地测试步骤、自动化测试用例编号、预发环境 URL“可逆性”审查所有涉及数据变更如数据库 migration、缓存清理的 PR必须提供回滚方案。比如一个添加新索引的 SQL 脚本必须配套一个DROP INDEX语句并注明“若上线后发现性能下降执行此语句回滚”。这个要求逼着开发者在动手前就必须想清楚“最坏情况怎么办”极大降低了线上事故概率。最让我欣慰的一次 PR是一个实习生提交的feat(auth): implement passwordless login via magic link。他的 PR 描述里不仅写了实现逻辑还附了一张手绘的时序图标注了每个环节的超时设置和错误处理策略在“权衡”部分他对比了 Magic Link 和 WebAuthn 方案坦诚写出“WebAuthn 更安全但 iOS 15 以下兼容性差Magic Link 能覆盖 98% 用户”在“验证”部分他提供了本地测试的 curl 命令和预期响应。这个 PR让整个后端组都跟着学了一遍邮件服务的最佳实践。4. 实操过程从零搭建一个可落地的 GitHub Flow 工作流4.1 环境初始化5 分钟搞定团队级基础配置一切工作流的起点不是写代码而是建规矩。我们用一个真实的初始化清单确保第一天就能跑通仓库初始化# 创建空仓库不带 README git init --initial-branchmain git remote add origin https://github.com/your-org/your-project.git # 创建 .gitignore基于 gitignore.io 生成包含 node_modules, dist, .env curl -sL https://www.toptal.com/developers/gitignore/api/node,typescript,vscode .gitignore git add .gitignore git commit -m chore: init repo with standard .gitignore git push -u origin main保护分支设置GitHub进入 Settings → Branches → Branch protection rules创建规则main分支✅ Require pull request reviews before merging最少 1 人 approve✅ Require status checks to pass before merging勾选ci/test和ci/build✅ Include administrators连管理员也必须走 PR✅ Require linear history禁止 merge commit强制 rebase✅ Restrict who can push to matching branches只允许 CI 机器人推送PR 模板配置 创建.github/PULL_REQUEST_TEMPLATE.md## 描述 !-- 请清晰描述本次 PR 解决的问题 -- ## 背景 !-- 问题来源用户反馈监控告警技术评审 -- ## 方案 !-- 简述实现思路关键设计决策 -- ## 验证 !-- 如何测试本地步骤预发环境链接 -- ## 影响范围 !-- 修改了哪些模块是否影响其他功能 -- ## 关联 !-- Jira Issue / GitHub Issue --CI 流水线GitHub Actions 创建.github/workflows/ci.ymlname: CI on: pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: 18 - name: Install dependencies run: npm ci - name: Run tests run: npm test - name: Build run: npm run build这个最简配置确保了每次 PR 都会触发测试和构建失败则无法合并。实操心得初始化阶段最容易忽略的是“权限同步”。我们曾因忘记在 GitHub 中给新成员分配Triage权限导致他无法给自己的 PR 添加标签CI 流水线无法识别其所属模块测试用例跑错了集合。所以初始化 checklist 的最后一条永远是“检查所有成员在仓库中的角色是否正确”。4.2 日常开发一个需求从创建到上线的完整闭环以“用户头像上传功能”为例演示标准操作流创建 IssueJira 或 GitHub标题[FEAT] 用户个人中心支持头像上传描述用户进入个人中心点击头像区域弹出文件选择框支持 JPG/PNG最大 2MB上传后实时显示。附件UI 设计稿链接、API 文档链接。创建 Feature 分支git checkout main git pull origin main git checkout -b feature/JIRA-789-avatar-upload开发与提交编写代码每完成一个逻辑单元如“文件选择组件”就提交一次git add src/components/avatar-upload/ git commit -m feat(ui-avatar): add file selection component with size validation所有提交都遵循前述 commit message 规范。推送并创建 PRgit push origin feature/JIRA-789-avatar-upload # GitHub 自动提示 Compare pull request点击进入填写 PR 表单粘贴 Issue 描述补充“验证”部分如localhost:3000/profile - 点击头像 - 选择图片 - 查看控制台是否打印 upload success。CI 与 ReviewGitHub Actions 自动运行显示绿色勾号。Assign 给 1 名 reviewer通常是模块 owner。Reviewer 检查代码、运行本地测试、在预发环境验证给出 approve 或 comment。合并与清理PR approve 后点击Squash and merge保持 main 历史干净。GitHub 自动删除 feature 分支在 Settings 中开启 “Automatically delete head branches”。本地执行git checkout main git pull origin main git branch -d feature/JIRA-789-avatar-upload上线main 分支的 push 触发 CD 流水线.github/workflows/cd.yml自动部署到生产环境。部署完成后Slack 机器人发送通知“maindeployed to prod, version v2.3.1”。这个闭环从 Issue 创建到生产上线平均耗时 4.2 小时不含等待 review 时间。关键在于每个环节都有明确的输入输出和自动化保障人只做决策机器负责执行。4.3 紧急修复Hotfix 的标准化操作手册再完美的流程也挡不住线上 Bug。我们的 Hotfix 流程目标是“快、准、稳”触发条件线上环境出现 P0 级故障如核心功能不可用、数据丢失、安全漏洞且已有明确修复方案。操作步骤# 1. 从当前线上 tag 拉取 hotfix 分支不是从 main git checkout -b hotfix/JIRA-999-fix-payment-fail v2.3.0 # 2. 编写修复代码提交 git commit -m fix(payment): handle Stripe network timeout gracefully # 3. 推送并创建 PR目标分支为 main不是 develop git push origin hotfix/JIRA-999-fix-payment-fail # 4. PR 描述必须包含 # - 故障现象附 Sentry 错误截图 # - 根本原因如Stripe SDK 未捕获 ECONNRESET # - 修复方案增加重试逻辑 # - 验证方式本地模拟网络断开确认不崩溃 # 5. 合并后立即打新 tag git checkout main git pull origin main git tag -a v2.3.1 -m hotfix: payment timeout handling git push origin v2.3.1事后同步在团队群同步[HOTFIX] v2.3.1 已发布修复支付超时问题详情见 PR #456更新 Confluence 的“线上问题追踪表”标记 JIRA-999 为 resolved在下一次 retro 会议上复盘为什么这个 Bug 没在测试环境发现如何加强监控注意Hotfix 分支必须基于线上 tag而非 main。这是血泪教训。我们曾有一次hotfix 基于 main结果把 main 上尚未测试的 feature 代码也带到了生产环境引发连锁故障。现在所有 hotfix 操作都封装成一个 shell 脚本./scripts/hotfix-start.sh JIRA-999自动完成分支创建、tag 检出、PR 创建杜绝人为失误。5. 常见问题与排查技巧实录那些文档里不会写的坑5.1 “Merge Conflict”不是错误而是沟通失效的警报冲突Conflict常被当作 Git 的缺陷但在我眼里它是团队协作健康度的晴雨表。一次冲突背后往往藏着三个问题需求重叠、进度不同步、或职责不清。我们不追求“零冲突”而是追求“冲突可预测、可快速解决”。预防性策略模块 Owner 制每个核心模块如auth、payment指定一名 Owner所有涉及该模块的 PR必须 Owner review。Owner 有责任了解模块内所有活跃分支提前协调。每日 Sync晨会最后 5 分钟每人说一句“我今天主要改xxx模块涉及yyy文件”。这比任何工具都管用。文件锁File Locking对高冲突风险文件如package.json、webpack.config.js在 PR 描述中声明“此 PR 修改 package.json请勿同时修改依赖”。我们甚至用 GitHub 的CODEOWNERS文件自动 assign 相关 reviewer。解决技巧拒绝git merge --no-ff它会产生无意义的 merge commit污染历史。我们强制git config --global pull.rebase true让git pull默认 rebase保持线性历史。用git difftool替代git merge当冲突复杂时git difftool会调用 Beyond Compare 或 VS Code图形化对比三方ours/theirs/base比命令行文本清晰十倍。冲突解决后必须运行npm test很多冲突看似只是语法差异但可能破坏类型推导或模块导入路径。测试是唯一真理。实操心得有一次两个前端同学同时修改src/utils/date-format.ts一个加了formatToISO方法一个改了formatToDisplay的时区逻辑。冲突解决后他们只检查了函数体没运行测试结果formatToISO的单元测试因时区参数变化而失败。从此我们加了一条团队公约“解决冲突后不运行测试等于没解决”。5.2 “Why is my PR not triggering CI?” —— CI 失败的 5 个隐形原因CI 流水线不触发是新人最常遇到的“玄学问题”。排除网络和服务器故障90% 的原因集中在以下五点原因检查方法解决方案分支名不匹配git branch -a看本地分支名Settings → Branches看 GitHub 的 trigger 规则确保.yml中on.pull_request.branches包含你的分支前缀如- feature/**YAML 语法错误GitHub Actions 页面的 “Actions” tab → 点击 “All workflows” → 查看 workflow 文件是否有红色感叹号用 YAML Lint 在线校验注意缩进必须用空格不能用 Tab文件未提交git status确认.github/workflows/ci.yml是否在 staging areagit add .github/workflows/ci.yml git commit -m chore: add ci workflowPR 未关联到正确的 base 分支PR 页面右上角确认 “base: main” 而不是 “base: develop”在 PR 页面点击 “Edit”修改 base 分支GitHub Token 权限不足Actions 日志中出现Resource not accessible by integration进入 Settings → Secrets and variables → Actions → 检查GITHUB_TOKEN的 permissions确保Contents为Read and write最隐蔽的一次是某位同学在.yml文件末尾多加了一个空格导致 YAML 解析失败但 GitHub 只显示“Workflow not found”没有任何错误提示。我们花了 3 小时才定位到。所以现在所有新成员入职第一件事就是跑通这个检查清单。5.3 “The main branch is behind” —— 同步混乱的根治方案main is behind提示意味着你的本地 main 比远程旧。新手常犯的错误是git pull origin main结果拉下来一堆别人刚 merge 的 feature导致本地环境不稳定。我们的标准做法是永远用git fetchgit reset --hardgit checkout main git fetch origin main git reset --hard origin/mainfetch只下载元数据不改变工作区reset --hard强制本地与远程完全一致干净利落。禁用git pull在团队.gitconfig中统一配置[pull] rebase true [advice] pullBeforePush false这样git pull实际执行git fetch git rebase避免 merge commit。定期清理本地分支git branch --merged main | grep -v main\|develop | xargs git branch -d一键删除所有已合并的本地 feature 分支。我们把它做成 aliasgit cleanup。提示