新手也能看懂的 Git 功能开发流程从需求到 Pull Request很多 Git 问题并不是命令不会用而是开发顺序错了。例如打开项目后直接在main分支写代码写到一半才想起来创建分支就容易遇到不同功能混在一起不知道哪些文件应该提交切换分支时担心代码丢失PR 中出现无关文件测试功能和未确认功能无法分开本文不重点讲 Git 命令而是讲清楚一次功能开发应该按照什么顺序进行。一、先理解 main 分支是做什么的可以把main理解为项目当前稳定版本。正常情况下main中应该保存已经开发完成的功能已经测试通过的代码已经审核通过的修改可以继续部署或发布的版本因此不建议直接在main上开发新功能。正确思路是main 保存稳定代码 功能分支负责开发 功能完成后通过 PR 合并回 main二、写代码之前第一件事是创建功能分支这是整个流程中最重要的一步。不要先写代码再创建分支。正确顺序更新 main → 从 main 创建功能分支 → 在功能分支中写代码例如这次开发的是“测试环境标识”分支可以命名为feature/console-environment-guard参考命令gitswitch maingitpull --ff-only origin maingitswitch-cfeature/console-environment-guard开始写代码前可以检查当前分支gitbranch --show-current如果显示main先不要写代码。三、一个分支尽量只做一个明确需求假设当前有三个需求测试环境标识 返回顶部按钮 项目表头吸顶如果三个功能都写在同一个分支里后面可能出现前两个已经测试通过第三个还不确定但三个功能修改了同一个globals.css最后不知道应该提交哪些代码更合理的方式是拆分feature/console-environment-guard feature/back-to-top-control feature/project-list-sticky-header如果两个功能关联紧密也可以放在一个分支但必须提前确认边界。核心原则一个分支只解决一个明确目标 未确认的功能不要混进当前分支四、写代码前先把需求想清楚不要一上来就修改代码。至少先明确以下内容为什么要修改用户最终会看到什么哪些页面会受到影响哪些文件可能需要修改是否涉及后端或数据库如何判断功能已经完成哪些内容暂时不做如果项目使用 OpenSpec可以保存proposal.md为什么修改 design.md准备怎么实现 spec.md功能应该满足什么行为 tasks.md具体实施步骤如果只是保存方案、暂时不开发tasks.md应保持未完成状态- [ ] 待实施任务这样以后不会误以为代码已经完成。五、开发过程中不要把所有样式都塞进 globals.cssglobals.css适合放全局变量Reset 样式页面通用基础规则具体功能的样式最好放在自己的文件中例如console-environment-guard.tsx environment-guard.module.cssMonorepo 项目也可以建立共享样式包libs/frontend/console-styles这样做的好处是一个功能对应一组文件提交时容易区分删除功能时不影响其他页面不容易把未确认功能一起提交服务器构建时依赖关系更清楚六、开发完成后先测试再提交不要代码刚写完就 Push。建议先做检查页面效果 → 检查 TypeScript → 执行生产构建 → 确认没有混入其他功能 → 再 Commit参考命令pnpminstall--frozen-lockfilepnpm--filternova-console/web build生产构建能够提前发现文件漏传TypeScript 类型错误Workspace 依赖缺失CSS Module 导入错误Next.js 路由错误本地能打开页面不代表生产构建一定能通过。七、Commit 前要检查“这次到底提交什么”Commit 不是把所有修改一次性塞进去。提交前应该确认哪些文件属于当前功能 哪些文件属于其他功能 哪些文件只是本地配置 哪些内容暂时不能提交尤其不要看到很多文件后直接“全选”。可以检查gitstatus--shortgitdiff需要按代码块选择时可以使用gitadd-p提交信息应说明这次做了什么gitcommit-mfeat(console): 支持测试环境标识和返回顶部控件常见前缀feat新增功能 fix修复问题 refactor代码重构 docs文档修改 test测试修改 chore依赖、脚本或配置维护八、没有 Commit 的代码不真正属于任何分支这是很容易误解的地方。文件可能有三种状态未追踪 已追踪但未提交 已经 Commit即使文件已经被 Git 追踪只要没有 Commit它就没有真正进入分支历史。切换分支时未提交修改可能被带到其他分支阻止分支切换与目标分支发生冲突在强制签出或还原时被覆盖因此准备切分支或合并代码前应先处理工作区。九、不想提交的代码可以先 Stash有些修改需要保留但不应该进入当前功能分支。这时可以使用 Stash。Stash 的作用是临时保存未提交内容 → 暂时清空工作区 → 完成切分支或合并 → 再恢复原来的内容参考命令gitstash push-u-mwip before merge main其中-u表示连未追踪的新文件一起保存。检查工作区gitstatus--short没有输出才表示工作区已经干净。恢复gitstash pop需要注意Stash 不会上传 GitHubStash 不属于正式版本历史Stash 适合临时保存长期内容应放到独立分支并 Commit十、开发期间 main 更新了怎么办开发功能时其他人可能已经向main合并了新代码。这时不要直接把旧功能分支推上去。正确做法先保存当前修改 → 获取最新 main → 把 main 合并进功能分支 → 重新测试参考命令gitfetch origingitmerge origin/main也可以使用 Rebasegitrebase origin/main简单理解Merge保留合并记录比较直观Rebase提交历史更整洁已经多人使用的分支Merge 更稳妥个人且尚未推送的分支可以考虑 Rebase合并成功后要重新构建因为 main 的变化可能影响当前功能。十一、Push 的是功能分支不是 main功能开发完成后推送功能分支gitpush-uorigin feature/console-environment-guard不要写成gitpush origin main如果 IDEA 同时管理多个 Git 仓库例如nova-console nova-common nova-dbPush 时只勾选本次需要推送的仓库。不要因为它们同时出现在 Push 窗口就全部推送。十二、Push 完成后创建 PRPush 只是把功能分支上传到 GitHub还不是 PR。PR 的作用是申请把功能分支合并到 mainGitHub 中进入Pull requests → New pull request选择base: main compare: feature/console-environment-guard其中base是准备合并到哪个分支compare是当前功能分支PR 标题示例feat(console): 支持测试环境标识和返回顶部控件PR 描述应该写清楚## Changes - 增加测试环境视觉标识 - 增加返回顶部控件 - 增加共享样式包 ## Verification - pnpm install --frozen-lockfile - pnpm --filter nova-console/web build十三、创建 PR 后还不能立刻合并PR 创建后GitHub 可能执行自动检查TypeScript 检查 构建检查 单元测试 代码规范检查如果页面显示Waiting for status to be reported表示检查还没有完成。需要等待All checks have passed第一张 PR 列表显示“Open”只代表 PR 已经创建不代表检查通过。十四、谁来点击 Merge是否可以 Merge取决于是否拥有仓库写入权限CI 是否通过是否存在代码冲突是否要求其他人审核main 是否配置了分支保护团队项目中通常建议开发者创建 PR → 其他人审核 → 维护者或管理员合并即使自己有权限也不建议在检查未完成时直接合并。十五、PR 合并后本地 main 才会出现新功能PR 创建以后本地main不会自动拥有功能代码。只有 PR 真正合并后再更新本地maingitswitch maingitpull --ff-only origin main这时新功能才正式出现在本地main。最后可以删除功能分支gitbranch-dfeature/console-environment-guard十六、一套推荐的开发顺序以后开发新功能可以按照下面的顺序1. 明确需求 2. 更新 main 3. 从 main 创建功能分支 4. 确认当前不在 main 5. 编写功能代码 6. 本地测试和生产构建 7. 检查提交文件 8. Commit 9. 同步最新 main 10. 再次测试 11. Push 功能分支 12. 创建 PR 13. 等待 CI 和审核 14. 合并 PR 15. 更新本地 main最需要记住的是写功能前先切分支 一个分支只做一个明确需求 未确认功能不要混入当前提交 切分支前处理未提交修改 Push 前构建 PR 前检查 Files changedGit 命令只是工具真正重要的是养成正确的开发顺序。