团队里五个人同时改一个微信小程序，git上每天冲突几十次，合并代码比写代码还累。这种场景我太熟了，前前后后带过七八个小程序项目，踩过的坑能写一本《小程序排雷指南》。今天不聊官方文档里那些正确的废话，专讲那些文档里没有、但真实开发中一定会撞上的墙。

第一个坑，也是最容易被忽略的：微信开发者工具的“项目设置”根本没进git。新同事拉下代码，打开工具直接编译，报错报得莫名其妙。搞了半天，是本地设置里“不校验合法域名”没勾上，或者调试基础库版本跟团队不一致。这东西存在project.config.json里，但很多人不知道要手动把“setting”字段同步。我们后来定了个规矩：新人入职第一天，先把project.config.json里的urlCheck改成false，基础库统一锁到某个版本，然后提交一次“初始化配置”的commit。别嫌麻烦，这能省下一周的“为什么我这边跑不起来”的群聊刷屏。

第二个坑跟云开发有关。如果你们用了云函数，那恭喜，你即将体验什么叫“线上环境地狱”。三个后端同学同时改同一个云函数，部署的时候互相覆盖，线上跑的版本是谁的都不知道。更离谱的是，云开发控制台里的环境ID每个开发者本地都可能不同——有人用tcb-env-prod，有人用tcb-env-test，代码里hardcode环境ID的后果就是，明明本地调试正常，一上生产就报“环境不存在”。我们的解决方案是：所有环境ID统一放在config.js里，用git的分支管理来区分环境，develop分支对应测试环境，master对应生产，云函数部署脚本里自动读取当前分支名来切换环境ID，再配合CI/CD平台，总算把这块理顺了。

第三个坑，页面路由和组件命名。小程序的路由是写在app.json里的，页面文件多了以后，大家随手起名，什么page1、page2、test、demo、final2，app.json里几十个页面路径，鬼知道哪个是对外的。更恐怖的是组件命名冲突——两个同事同时写了一个叫“custom-nav”的组件，一个放在components/nav-bar下，一个放在components/navigation下，用的时候全靠缘分。我们后来强制规定：页面文件必须按模块分目录，比如pages/order/list、pages/user/profile，组件必须带业务前缀，比如order-card、user-avatar，并且每个组件目录下必须有一个README.md，写清楚这个组件是干嘛的、参数是什么。规则很土，但真的能救命。

第四个坑，是样式污染。小程序虽然天生有样式隔离，但全局样式app.wxss是共享的。有人图省事，在全局里写了个button { border-radius: 0 }，结果所有页面里的按钮全变成直角了，设计师看到直接炸毛。还有更隐蔽的：某个页面里定义了page { background: f5f5f5 }，这个page选择器是全局生效的，你改了A页面，B、C、D页面全跟着变。我们的做法是：全局样式只放公共变量和基础reset，所有页面级的样式必须写在页面自己的wxss里，而且页面根元素用唯一的class名包起来，比如.order-page { ... }，这样就算别人复制你的代码，也不会污染到别处。

第五个坑，得聊聊代码合并的“幽灵冲突”。小程序里很多文件是JSON格式，比如app.json、page.json，这种文件冲突时，git的自动合并经常出错。两个同事同时往app.json里加页面，git会认为这是两个不同的修改，自动合并成功，但实际上是数组里出现了重复项，编译直接报错。还有wxml文件，标签嵌套结构复杂，合并时经常出现一个标签被另一个同事的修改截断，生成一堆乱七八糟的代码。我们后来规定：JSON文件必须手动合并，不允许用git的自动合并；wxml文件尽量拆分子组件，一个文件超过200行就一定要拆，减少合并的冲突面积。

第六个坑，是调试和发布的流程混乱。几个人同时开发，谁都想试试自己的代码能不能上线。结果就是，今天你部署测试版，明天他部署体验版，后天有人直接把开发版发到生产了。微信小程序的版本管理又特别不友好——线上版本、审核版本、开发版本、体验版本，四个版本并存，搞混了都不知道用户看到的是哪个。我们后来定了严格的发布流程：develop分支开发完，合并到test分支，由专人（一般是项目经理）在开发者工具里上传体验版，测试通过后，再由同一人上传审核版，审核过了之后，在mp后台点发布。整个过程只有一个人有权限操作mp后台，其他人就算有账号也不允许碰。

一个坑，是沟通成本。听起来很虚，但真的致命。五个人同时开发，你改了登录逻辑，他不知道；他改了支付回调，你没看更新日志。结果联调的时候，登录失效了，支付成功但回调没触发，两个人互相对着屏幕骂了半天，发现是对方改了公共模块的接口。我们后来每周一三五下午开十五分钟站会，每个人只说三件事：昨天做了什么、今天打算做什么、有没有遇到阻塞。另外强制要求：任何公共模块的修改，必须在git提交信息里带上【公共】标签，并且在群里@所有人。一开始觉得麻烦，坚持了一个月之后，真的没人再愿意回到那种“改了代码没人知道”的状态了。

说真的，多人协作开发小程序，技术上的坑其实都有解，最难的永远是人和人之间的协同。工具、规则、流程，这些东西花一周时间就能搭好，但真正让团队跑顺的，是每个人都愿意多写一行注释、多更新一次文档、多问一句“你确定这个改了吗”。如果你现在正被这些坑折磨，别急，按上面的方法一条条试，你会回来感谢我的。