企业官网建设流程全解析

1. 从“同目录并行”到“多分支并行开发”

我把三个编码代理会话丢进同一个项目目录，让它们同时开工，这大概是我最近半年在本地开发里踩过最深的坑之一。

一开始的想法特别简单：项目到了交付密集期，登录模块要改造、支付逻辑要加新功能、报表那块还要修一堆历史问题，我一个人实在排不开。既然身边有编码代理，为什么不开三个终端窗口，让每个代理负责一块任务？听起来很美，实际跑起来半小时内就会让你后悔。

后悔的原因是：这些代理都会读文件、改文件、跑测试、重启服务。当两个代理同时操作同一个工作目录，它们本质上是在同一块白纸上用同一种颜色的笔写字。A 代理刚把公共类型定义里的某个函数重命名，B 代理还在按老名字调用；A 代理往 package.json 里加了依赖并更新了锁文件，B 代理的安装流程就会看到不一致的依赖树。最夸张的一次，两个代理同时跑测试命令，其中一个把临时数据库文件清了，另一个当场失败。

这就是“多分支并行开发”这套流程的原始动机：不是让代理在同一目录里假装并行，而是从文件系统层面把每个代理的工作空间彻底隔离开，再通过 git 的分支和工作树机制把它们像多条独立流水线一样管理起来。

1.1 两个并行代理挤在同一个目录里会发生什么

先说一个具体场景，方便你理解我为什么对“同目录并行”这么敏感。

假设你有src/utils.ts这个文件，A 代理负责性能优化，需要把里面几个工具函数改成异步版本；B 代理负责新功能对接，也要在同一个文件里加一个导出函数。两个代理都在各自的上下文里“看着”这个文件的旧版本，然后差不多时间开始写盘。

A 代理写完异步版本，跑了一遍测试，通过，提交。B 代理在旧版本基础上加了新函数，保存文件，然后发现整个文件被 A 代理改得面目全非，B 代理的修改要么覆盖掉 A 的结果，要么因为依赖 A 的函数签名而产生一堆编译错误。这个阶段你根本分不清是代码逻辑错了，还是两个代理互相踩了脚。

更隐蔽的问题是运行环境。很多项目都有本地调试服务、临时文件、缓存目录。两个代理同时在同一个目录里跑npm run dev或者pytest，它们会在同一个端口上打架，在同一个临时目录里写冲突的文件，甚至因为共享某个全局状态文件而互相干扰。这时候你没法说“哪个代理做错了”，因为每个代理单独跑都是对的，放在一起就不对。

这就是我在项目里明确了一条底线：只要同时存在一个以上的编码代理会话，就不再让它们共享同一个工作目录。要么串行排队，要么用工作树彻底分开。

1.2 为什么“串行切换分支”也兜不住

有人说，既然不能共享目录，那我保守一点，让代理 A 先干活，提交，切分支，再让代理 B 干活，这样总行了吧。

串行方案确实能避免同目录互踩，但你很快就会遇到第二个问题：上下文连续性。编码代理的优势之一就是能在一段上下文里持续跟踪需求、修改多个相关文件、反复验证。如果你在它干了一半的时候切换分支，那个代理对当前状态的感知就断了。你也许可以把没提交的修改 stash 起来再切过去，但 stash 出来的临时状态非常容易丢，而且等你切回来继续干的时候，代理很可能需要重新读一遍所有相关文件才能捡回思路。

另一个问题是任务排队带来的时间浪费。一个代理写代码的时候，另一个代理只能干等着。尤其在需求多而杂的周期里，串行执行的效率会低得让人怀疑人生。你明明买了几张并行计算的大核，却非要跑单线程，那何必呢。

所以我最后选择了 git worktree。它解决的核心问题很简单：同一个仓库，多个工作目录，每个工作目录对应一个独立分支，目录之间物理隔离，但底层对象库共享。这样我就能同时让几个代理各自处理一个分支，互不干扰，每个代理都在自己独立的文件副本上干活。

2. Worktree 的并行原理与方案选型

在讲实操之前，我先花一点时间解释工作树到底是怎么工作的，因为很多人对 git worktree 的理解停留在“不过就是多个目录”的层面，但真正用起来会发现很多细节。

git 仓库平时维护着一棵工作树，也就是你当前 checkout 到某个分支时看到的那一整个目录。传统方式下，你切换分支，这棵工作树里的文件就被替换成另一个分支的内容。而git worktree add可以在这个仓库里额外创建多棵工作树，每棵工作树都被分配一个独立的工作目录，并且 checkout 到不同的分支。

底层的.git目录是共享的，对象库、引用、配置、钩子这些都是同一套。每棵工作树只维护自己的 index、HEAD、工作区状态和对应的 .git 文件链接。这意味着提交历史是统一的，你在任何一个工作树里提交，其他工作树都能看到这个 commit；但每个工作树当前检出的内容、未提交的修改、暂存区状态是各自独立的。

听起来有点绕，打个比方：社区里有一间公共图书室（对象库），每个人借出去的书其实是副本，你在副本上怎么写都不会弄脏别人那份；但当你写完想放回书架时，图书管理员会检查这本书和其他人有没有重复修改之处。

对编码代理来说，这个机制的价值在于：每个代理看到的是一份完全独立、干净的项目副本。它可以在自己的目录里随便改，随便跑测试，不担心另一个代理把同一行代码改了。而合并冲突被推迟到最终合并阶段，那时候你再用常规的冲突解决手段去处理，而不是在代理运行到一半的时候去救火。

2.1 三种并行开发路线的对比

我平时会跟团队里的朋友这样对比，他们大部分一听就懂了。

串行切换和同目录并行的问题前面已经说过了，这里重点说工作树方案的磁盘开销。因为是同一个仓库，对象库只保留一份，不会像git clone那样复制所有历史。每个工作树额外占用的主要是一份工作区文件。如果你的仓库有 1 万个小文件，那每建一个工作树就多一份 1 万个文件的目录；但大多数文件的体积都很小，只要不是动辄几个 GB 的二进制资源，这点开销完全能接受。

2.2 为什么选择 Worktree，而不是临时克隆仓库

也有人问我：那你为什么不直接git clone几个仓库副本，每个副本给一个代理，不也一样隔离吗？

区别在于：克隆副本之间的“血缘关系”太弱。它们各自有独立的远程配置和引用，平行开发一段时间后，仓库 A 和仓库 B 之间要互相同步代码，你得手动推拉远程仓库，或者反复重置。这个管理负担会随着代理数量增加而急剧膨胀，而且很容易出现某个副本忘记同步、远程分支漂移、引用对不上的问题。

worktree 则不一样。所有工作树共享同一个对象库和引用命名空间，我只要在一棵工作树里执行git pull，其他工作树在git merge main时就能用到最新对象。整个仓库的状态在逻辑上永远是统一的，只是每个工作目录各自 checkout 不同分支而已。这对于多代理场景是决定性的优势，因为代理最怕的就是“代码从哪来、往哪去”这套底层的仓管逻辑不清晰。

注意：worktree 不是虚拟化，不是容器，也不能帮你解决构建工具之间的冲突。它本质上只是把“写代码的目录”拆开了，最终合并和冲突处理仍然要靠你自己的 git 能力兜底。

3. 工程落地：初始化工作树与代理环境隔离

理论讲完，来点能直接照着敲的命令。我建议你把这套流程固定成一篇团队文档，每次开新需求就按这个来，省得临时决定导致满天飞的分支。

3.1 目录规划与初始化命令

我习惯把工作树统一放在一个wt-space文件夹下，方便一眼看到当前并行开了哪些分支。

先在主工作目录里把仓库准备好，然后执行：

git worktree add -b feature/login ../wt-space/wt-login main git worktree add -b feature/pay ../wt-space/wt-pay main git worktree add -b feature/report-fix ../wt-space/wt-report-fix main

这样会基于main创建三个新分支，并在对应目录里生成独立工作树。执行完毕后，用git worktree list确认一下：

git worktree list

输出大概长这样：

/Users/you/project main /Users/you/wt-space/wt-login feature/login /Users/you/wt-space/wt-pay feature/pay /Users/you/wt-space/wt-report-fix feature/report-fix

需要注意的一点：第一次进入每个工作树时，它只是把分支 checkout 出来了，依赖、环境配置这些都不会自动准备好。所以每个代理真正开始工作之前，你需要先完成三件事：装依赖、配环境变量、准备项目说明文件。

我的具体做法是：

cd ../wt-space/wt-login npm install cp ../project/.env.example .env.local

这里的建议是，在你最初的几个工作树目录里先手动执行一次依赖安装，然后把整套初始化脚本固化下来。之后每次新增工作树，直接跑同一个初始化脚本就行。不要指望代理自己在没有任何指引的情况下就能把环境装出来，那会浪费大量上下文。

3.2 代理指引文件的分身与同步策略

现在很多编码代理都支持项目级指引文件，在项目根目录放一个AGENTS.md或CLAUDE.md，代理启动时会自动读取，作为长期依赖的行为说明。这块在多工作树场景下有个坑：每个分支会各自维护一份自己的指引文件。

如果你把公共规范和当前任务说明都写在同一份AGENTS.md里，会出现两个问题。第一，公共规范改动后，你必须每个工作树都同步一份；第二，分支合并时，这份文件很容易产生冲突，因为多个分支可能同时修改它。

我的做法是把指引文件拆成两层。公共规范放在仓库内部的docs/agents/AGENTS.shared.md，这个文件只在主分支维护，改动频率低。每个工作树里放一个轻量的AGENTS.md，内容是符号链接：

cd ../wt-space/wt-login ln -s ../../docs/agents/AGENTS.shared.md AGENTS.md

然后在.gitignore里把AGENTS.md忽略掉，这样每棵工作树都只保存自己的短期任务说明，比如“本轮只改登录模块，不要动支付目录”，而公共规范统一指向同一个链接文件。

如果你不想用符号链接，也可以直接复制一份AGENTS.shared.md到每个工作树里当AGENTS.md，但那样每次改公共规范都要手动批量复制一遍，工作树多了很容易漏。我个人测下来，符号链接是最稳的。

3.3 环境变量与依赖目录的处理

环境变量一定要按工作树独立配置。很多项目会读.env，如果你让所有工作树共用同一个.env，那么 A 代理在登录分支上改了一个测试账号，B 代理在支付分支上也可能被影响到，排查半天才发现是环境变量被带过去了。

依赖目录我的建议是：对常规项目，每个工作树独立安装一份 node_modules 或者虚拟环境。虽然多占一点磁盘，但能避免代理因为共享依赖目录而互相把文件改乱。如果你嫌安装太慢，可以先在第一个工作树里装好依赖之后，用文件系统快照或者直接复制目录的方式给其他工作树复制一遍，再各自执行一次包管理器的完整性校验，避免反复下载。

不过要留意一点：有些包管理器在安装脚本里会写.git相关操作，比如执行 git 钩子，而工作树里的.git其实是一个文件，不是目录，极少数工具会在识别仓库根路径时出问题。遇到这种报错，优先确认工具对worktree布局的兼容性，或者在该工作树内单独配置钩子路径。

4. 多分支并行开发的完整流程实测

下面我把最近实际跑过的一轮并行开发流程完整串一遍。三个分支并行推进，每个分支用独立工作树，三个代理各自负责一个模块，最终合并回主线。

4.1 分支规划与“主工作树”职责

在开始之前先想清楚一件事：谁是主要负责集成的那个目录。我通常会把原始的主工作目录保留为main分支的“驻守区”，它平时只用来做两件事：从远程拉取最新主线、验收并合并功能分支。平时不要在驻守区里跑代理，也就是不要让代理在这里做无谓的改动，否则你很可能在合并时发现主角被换掉了。

真正并行开工时，我在每个工作树里分别启动一个编码代理，并给它们划定明确的边界。例如：

• wt-login：只修改src/modules/login、src/api/auth，目标是登录相关接口改造。
• wt-pay：只修改src/modules/payment、src/api/billing，新增一个支付回调处理。
• wt-report-fix：只修改src/modules/report，修复导出报表时的日期格式问题。

这步特别重要。工作树提供了物理隔离，但代理的“注意力隔离”才是并行开发效率的第二根支柱。你一定要在AGENTS.md里明确告诉代理：不要越界修改其他模块的文件。否则即使工作树是隔离的，等到最终合并时也会因为不同分支对同一批文件的各自修改而产生大量冲突。

4.2 并行开工、提交与状态同步

我在三个终端窗口里同时启动了三个代理，分别进入各自工作树。初期一切顺利，每个代理都在自己的目录里改代码、跑测试、提交。

提交纪律直接沿用手动开发的习惯：功能点完成就提交，提交信息写清楚属于哪个分支。比如在wt-login里：

cd ../wt-space/wt-login git add src/modules/login src/api/auth git commit -m "feat(login): 支持新的会话刷新逻辑"

在wt-pay里也在同时提交它自己的支付回调代码。因为底层共享对象库，这些 commit 在 git 层面是全局可见的，只是各工作树的 HEAD 指针不同。

并行开发进行到一半时，远程主线有了新的更新。这时候要在每个工作树里把主线合并进来，保持功能分支不落后。我只在驻守区拉取远程：

cd /Users/you/project git pull --ff-only origin main

然后在每个工作树里同步：

cd ../wt-space/wt-login git merge main

如果两个分支之间恰好没冲突，合并会顺利通过；如果有冲突，就在这个工作树里直接解掉，再把结果提交到功能分支上。不要等到最后一口气到驻守区合并时再处理所有冲突，那样你会面对一堆跨模块的混合冲突，非常难理清。

4.3 合并炸出冲突之后怎么办

并行最后一天，三个功能分支都完成了各自的修改，开始往main合并。我保留了--no-ff的方式，这样能看到完整的合并提交和相关分支轨迹。

cd /Users/you/project git merge --no-ff feature/login git merge --no-ff feature/pay git merge --no-ff feature/report-fix

前两个分支合并得很顺，第三个报表分支和登录分支在src/utils/date.ts这个文件上发生了冲突。原因是登录分支重命名了一个时间格式化函数，而报表分支刚好新增了一段调用旧函数的代码。

处理这类跨分支冲突时，我的习惯是先在冲突文件里看一下两个分支各自改的是什么，理解双方意图，再决定保留哪一边或者各退一步。这里显然应该保留新函数名，并让报表分支的代码改成调用新函数。

解完冲突后，提交并跑一遍全量测试：

git add src/utils/date.ts git commit -m "fix(report): 适配登录分支新增的日期处理函数" npm test

这轮并行开发里，冲突只出现了两次，都在可接受的范围内。如果所有分支同时拼命改同一个文件，那就算有工作树也救不了你，说明你在任务拆分上已经出了问题。

5. 常见问题与排查技巧

我用了这么久，把常见问题整理成了一个小速查表，每次遇到类似报错直接按表查，省下大量时间去翻文档。

除表格之外，还有两个老手才知道的坑值得单独说。

第一个坑是当你执行git worktree add之后，这个新工作树的.git是一个普通文件，里面存着它对应的 gitdir 路径。如果你直接用压缩工具备份整个项目目录，会发现备份下来的.git文件指向的是原机器的绝对路径，换一台机器就失效了。正确做法是备份整个仓库和所有工作树目录，并把相对路径关系保持住，或者干脆重新跑git worktree add来重建，不要手动复制。

第二个坑是共享钩子和全局配置。很多仓库会在.git/hooks里放提交前检查脚本，而所有工作树共享同一个.git/hooks。如果有一个代理在工作树里往共享 hook 里安装了额外检查脚本，其他工作树的提交行为都会跟着变。只要你确认这个 hook 不是分支特有的，通常没问题；但如果某个分支确实需要不同的 hook 行为，就得在仓库配置里单独处理，别指望工作树能帮你天然隔离。

6. 多分支并行开发之外，我还想留住的几点经验

如果你能看到这里，说明你真的准备把这套流程用起来。那我不妨把最近实践中沉淀下来的一些“反常识”判断也一并讲了。

第一，越是“看起来简单”的任务，越不值得建工作树。一个功能就改一个文件，直接让代理顺序完成比建工作树、初始化环境、合并分支的整套开销要小得多。工作树的收益要在“多个分支同时有规模改动”的时候才明显，单独小改动强行套这个流程是自找麻烦。

第二，工作树数量最好控制在四个以内，极端情况下也不要超过六个。每个工作树都要安装依赖、定期同步主线，数量一多，维护成本就呈线性上涨。有时候最终消耗的时间反而超过串行执行，不值得。

第三，不要把代理的上下文范围和工作树的物理范围混为一谈。工作树隔离的是文件和 git 状态，但代理的“注意力”需要你自己在AGENTS.md和 prompt 里约束。我给每个代理的任务说明里都会写清楚它只能动哪个目录，遇到跨模块问题时即使它发现也别顺手改，而是记录到当天的待处理清单里，由我来统一决定。

第四，这套流程最值钱的部分其实是“合并前的同步纪律”。并行开发最怕的不是并行本身，而是合并时才发现两个分支对同一个接口的理解完全不一致。所以我在每个功能分支合并回main之前，都会要求分支先在本地把最新主线合并一遍、跑完测试，再执行最终合并。这一条可以说是整个工作流里唯一真正必需的步骤，其他都是锦上添花。

如果你只记住一条，那就记住这条：每次合并前同步，同步后测试，测试通过再往主线合。多分支并行开发的所有混乱，九成都能被这一条拦在门外面。