微信小程序多人开发的配置流程
上周有个朋友跟我吐槽：他们组四个人接了一个小程序项目，光是把环境跑起来就折腾了三天。A 用公司注册的 AppID 登录，B 手机扫码到别人账号上，C 提交代码的时候把 project.config.json 改了，结果大家拉下来全部报错，D 想传体验版发现根本没有权限。听起来很基础，但就是这种“每个人都会遇到、又没人系统整理过”的事，最容易卡住一个团队。
这篇东西就是把我自己带团队做小程序、以及在多个项目里踩过的坑梳理一遍，讲讲微信小程序从“单机开发”切换到“多人协作”时，到底要配哪些东西、按什么顺序配、每个配置背后解决的是什么问题。适合刚组建小程序开发团队、准备接外包、或者正在带几个实习生的朋友参考。
1. 成员与角色配置：先理清“谁能干什么”，再谈代码
很多团队一上来就拉 Git 仓库、装开发者工具，结果第一步就翻车——同事扫码登录之后发现没有上传权限，或者说自己不是项目成员连开发版都打不开。实际上，微信官方的成员管理体系和普通项目的“给个 Git 权限就行”逻辑不太一样，它把人分成了好几类，每一类能干的事都不一样。
1.1 微信公众平台的角色权限体系
先登录微信公众平台（mp.weixin.qq.com），在“管理 - 成员管理”里可以看到角色分配。官方把成员分为几类：
| 角色 | 能做什么 | 需要注意的坑 |
|---|---|---|
| 管理员 | 全权限，包括成员管理、修改 AppID 信息、发布、解绑 | 一个账号只能有一个管理员，更换管理员流程比较麻烦 |
| 项目成员 | 代码上传、开发版预览、真机调试、查看数据 | 需要管理员在后台手动添加 |
| 运营者 | 管理后台、用户管理、客服消息等，不含代码能力 | 通常给产品/运营同学配这个角色 |
| 体验成员 | 扫码体验开发版/体验版 | 人数有限制（一般几十个），测试多人并发前提前加人 |
实操建议：核心开发人员全部配“项目成员”，产品、测试、UI 配“体验成员”或“运营者”。不要图省事把所有同事都加为项目成员，因为项目成员默认能看到代码上传记录、能上传体验版，权限边界越清晰，后期出幺蛾子的概率越低。
我见过最离谱的情况是：团队把外包的几个开发也加成了项目成员，项目结束后对方还能看到小程序的线上数据。所以每次人员变动，第一件事就是去后台清理成员权限，别等出问题再补。
1.2 添加成员的完整步骤与验证方式
在“成员管理”页面点“添加成员”，输入对方的微信号或手机号，然后选择角色。对方会在微信里收到一条邀请通知，点击确认后还需要用本人微信扫码登录开发者工具激活。
这里有个很容易忽略的点：添加项目成员时，管理员可以设置“指定小程序项目”还是“全部小程序项目”。如果一个微信开放平台账号下面挂了好几个小程序（比如有正式版、测试版、客户A、客户B），一定记得按项目维度分配成员，别让所有人都能操作所有小程序。
添加完成之后，让同事在微信开发者工具右上角头像处确认登录账号与后台添加的微信一致。实际操作中经常出现“管理员加了 A，A 扫码登录的却是 B 的微信号”这种低级但拖延进度的事。
提示：在成员管理里给同事配好“项目成员”后，开发者在工具里上传代码才会出现“上传”按钮。如果同事反馈按钮是灰的，90% 是权限没配好。
2. 项目配置文件的 Git 策略：AppID 与 project.config.json 的相爱相杀
多人开发真正让人头秃的往往不是业务代码，而是项目配置文件。微信开发者工具每个项目根目录下都有一个project.config.json，它记录了 AppID、项目名、编译设置、基础库版本等信息。单机开发时没什么感觉，一旦多人协作，这个文件就会变成冲突高发区。
2.1 AppID 的两种选择：测试号与正式号
新建小程序项目时，AppID 可以填“测试号”（ touristappid ）也可以填真实的小程序 AppID。测试号不需要注册小程序就能用，但不支持云开发、部分 API 受限、也不会上传到真实的版本流。
多人开发时最怕的是配置不统一：有人用正式 AppID，有人用测试号，代码里凡是涉及wx.login、云开发、订阅消息的都跑不通，大家还以为是别人代码写错了。
我们团队的内部约定是：统一使用正式小程序的 AppID 作为开发基础。因为小程序开发者和项目成员的权限是基于 AppID 维度的，正式号能模拟更接近线上环境的行为，比如云开发、微信支付（沙箱）、订阅消息等。只有做纯视图层 Demo 或者新手练手时才用测试号。
在项目的project.config.json里，AppID 字段长这样：
{ "appid": "wx1234567890abcdef", "projectname": "my-miniprogram", "compileType": "miniprogram" }2.2 project.config.json 到底该不该提交到 Git
这是多人开发里最核心的争论点，我决定直接给结论：project.config.json可以提交，而且建议提交，因为团队需要统一的编译配置、基础库版本、ES6 转 ES5 等设置。真正要解决的问题是“本地的个性化设置”不要污染公共配置。
微信开发者工具从某个版本开始支持了project.private.config.json，这个文件就是给个人本地配置用的，它默认不会被提交，只存在于你自己的电脑上。所有本地调试偏好——比如“不校验合法域名”“本地调试端口号”“自己临时改的编译模式”——都应该丢到这个私有配置里。
// project.private.config.json 示例 { "setting": { "urlCheck": false, "es6": true, "minified": false }, "libVersion": "3.0.0" }这样，project.config.json保持稳定，公共配置统一由一个人（通常是前端组长）修改并提交，其他人要做个性化调试就改自己的project.private.config.json。这个思路和“全局 git config 与仓库级 git config”的分层逻辑完全一致，可以类比理解。
2.3 .gitignore 的配置清单
既然project.private.config.json是留给本地的，那就必须在.gitignore里加一行：
# .gitignore project.private.config.json node_modules/ miniprogram_npm/ dist/ .unpkg/另外，如果你的项目依赖 npm 构建，miniprogram_npm这个构建产物目录我建议也不要提交，统一在 clone 后执行npm install再在开发者工具里“构建 npm”。提交产物目录的最大问题是：每个人的本地环境不同，构建出来的产物可能有细微差异，而且代码 review 的时候根本不会有人去翻这个目录，还不如不提交。
2.4 用 code 换 token：多人登录的身份逻辑
平时我们很少意识到，小程序开发者的工具登录本质上是一个 OAuth 授权流程：你在微信客户端扫码，工具拿到一个临时 code，再用 code 去换取访问令牌（token），最后拿着 token 调用微信接口获取你的账号信息和项目列表。
多人开发配置时，这一点的重要意义在于：每个人的 token 都跟自己的微信号绑定，跟 AppID 无关。所以哪怕项目代码完全一致，不同人扫码登录后看到的小程序列表也可能不同——因为账号权限不同。真正确定“谁能不能上传/预览”的，是第 1 小节讲的后台成员权限，而不是你的本地 token。
理解了这套逻辑，遇到“别人能上传，我不能上传”的问题时，就不用去翻代码了，直接检查微信公众平台的成员权限。
3. Git 工作流与分支策略：多人改同一份代码的协作约定
配置好人、管理好项目文件之后，接下来是团队开发中最容易暴雷的环节：Git 工作流。小程序项目本质上是前端项目，但它比普通 Web 前端更特殊——app.json是全局唯一的路由表，页面一多，两个人同时新增页面很容易在同一个文件上撞车。
3.1 一套适合小程序的分支模型
我见过不少团队用“所有人都在 master 上提交”的原始模式，它的直接后果是：线上版本和开发版本混在一起，打包发布之前手忙脚乱，回滚也不知道回哪个版本。
更稳的做法是简化版 Git Flow，按这个模型走：
main（或master）：长期稳定分支，代码永远和线上发布版本对应。develop：日常开发集成分支，所有功能分支最后都合到这里。feature/xxx：每个功能从 develop 拉出独立分支，命名用功能名或需求单号，比如feature/pay-order。release/x.y.z：准备提审前从 develop 拉出发布分支，只修 bug，不开发新功能。
这条模型的好处是：哪天需要紧急回滚，直接在 main 上切回上一个 tag 就行了，不用在几十个提交里翻找。对小程序这种“发版频率高、审核周期不确定”的项目来说特别适用。
3.2 页面注册冲突：app.json 是多人开发的兵家必争之地
小程序里每新增一个页面，都要在app.json的pages数组里注册路径。两个人同时开发不同模块，几乎必然同时改动app.json。一旦在 Git 合并时冲突，展开后满屏都是路径列表，看着就头疼。
我们的操作规范是：
- 每次提交尽量只涉及自己负责的页面，避免顺手格式化整个
app.json。 - 改动
app.json的提交必须单独成一条，不要混杂其他文件改动，方便冲突后 revert。 - 规划页面路径时按模块划分，比如
pages/order/...、pages/user/...，这样不同人尽量操作不同前缀。
如果真的冲突了，不建议盲目选择“保留全部”，因为两边可能各自新增了不同的页面路径，正确做法是把两个分支的路径都保留，再手动去重。
3.3 TabBar 与公共样式的冲突处理
除了app.json，app.wxss和自定义组件库里也容易起冲突。公共样式文件的合并策略是“后改者兼容先改者”：不要轻易删别人的类名，优先在文件末尾追加新的样式类，等版本稳定后再统一重构。
这个策略说出来有点“笨”，但在多人协作场景里是最省事的。我见过有人热心“顺便”重构了公共样式，结果另一个分支里的页面瞬间变形，找问题找了两个小时。多数时候，宁可让代码冗余一点，也不要让公共文件变成每两天一次冲突的导火索。
3.4 提交规范和 Code Review 的底线
给团队定一个基础的 commit message 规范，比如：
feat(支付): 新增余额支付 fix(订单详情): 修复金额精度问题 style(公共组件): 调整按钮圆角不需要上那些重型工具，Git 提交时人工遵守就够了。但有一条要强制：任何人往 develop 分支合代码，必须经过至少一名同事 review。小程序项目试错成本不高，但审核排期成本高，一个低级错误可能让整个版本拖一周。
4. 开发者工具与本地环境的统一配置：基础库、域名、真机调试
配置好了人和代码，接下来是工具层面。微信开发者工具更新频繁，基础库版本也在快速迭代，多人开发时如果版本不一致，就会出现“我这边没问题，你那边报错”的经典局面。
4.1 基础库版本怎么统一
微信小程序的基础库是运行在微信客户端里的 JavaScript 框架版本。开发者工具可以选择多个模拟基础库，但在线上，用户手里的微信版本五花八门，基础库版本参差不齐。
多人协作时，建议在项目里明确锁定调试基础库版本，操作路径是：开发者工具右上角“详情 - 本地设置 - 调试基础库”。选择一个团队约定的版本（比如 3.0.0），同时把project.config.json里的libVersion也锁定为相同版本。
{ "appid": "wx1234567890abcdef", "libVersion": "3.0.0", "setting": { "urlCheck": true } }这里有个细节：project.config.json里的libVersion并不是所有团队成员都会被强制覆盖，工具还是会优先读取本地的缓存配置。所以不要只改配置文件，最好拉一通紧急会议，让每个人手动到“详情”里点一下版本。
4.2 合法域名与本地调试的冲突
微信小程序发布版本要求所有请求接口地址都配置在公众平台的“开发管理 - 开发设置 - 服务器域名”里，而且必须是 HTTPS。多人开发时，同事 A 连的是测试环境接口，同事 B 连的是本地后端，会越来越乱。
处理方案分两个层面：
第一，统一开发环境域名。团队里约定一个固定的测试环境域名，比如https://dev-api.example.com，不管本地后端是不是跑在 3000 端口，代码里统一请求这个域名，再通过环境变量或拦截器替换。
第二，调试时的本地不校验域名。在开发者工具的“详情 - 本地设置”里勾选“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”。注意这个设置要写在project.private.config.json里，避免影响公共配置。
{ "setting": { "urlCheck": false } }4.3 真机调试请求无法到达后端：排查链路
“开发者工具里一切正常，真机扫码就请求失败”是多人开发里最常遇到的线上 issue。按我的经验，按下面的顺序排查：
确认手机和电脑在同一局域网。真机调试时，如果后端跑在本地电脑上，手机访问的必须是电脑的局域网 IP（类似
192.168.x.x），不是localhost。在电脑上执行ipconfig（Windows）或ifconfig（Mac）查 IP，前端代码里的 baseURL 换成这个 IP。确认后端服务监听了对应端口。后端如果只监听了
127.0.0.1，局域网内其他设备是访问不到的。启动脚本里要写明0.0.0.0：
# Node.js 示例 node server.js --host 0.0.0.0 --port 3000检查手机是否开了“不校验合法域名”。真机预览时，在开发者工具“预览”弹窗里，可以勾选“真机调试”时忽略域名校验。如果没有这个入口，可以临时在框架里把请求拦截器关掉 https 校验（仅限开发环境）。
最容易被忽略的一步：手机和电脑是不是在同一个 WiFi 的同一个网段。有些公司网络做了 AP 隔离，设备之间互相 ping 不通，这种情况需要找网管开权限。
排到这里基本能找到问题。我见过很多人卡在第 1 步，一直纠结端口和域名，其实是因为“自己电脑上的 localhost 只有自己才能访问”这个基本概念没串起来。
4.4 上传版本、体验版与提审权限的流转
代码开发完成后，上传和提审环节也有配置讲究。在开发者工具点“上传”后，代码会以“开发版本”的形式出现在公众平台的“版本管理”里。在这里可以“选为体验版”，生成一个体验二维码，体验成员扫码即可使用。
多人团队的配置流程建议是：
- 开发版本由各项目成员自行上传，用途是自测和交叉测试。
- 体验版由前端组长或者测试负责人统一从最新的开发版本中选定，避免大家传的版本各自为政。
- 审核版本只从体验版或开发版中发起提审，提交后管理员会收到审核通知。
这里有一个很容易踩的坑：体验版的版本号不会自动更新，如果你不手动操作，体验版可能一直是五天前的旧代码，而同事还以为自己在测试新功能。每次合并完主干代码、准备给测试验的时候，记得重新上传并“选为体验版”。
4.5 多端框架（uni-app / Taro）下的配置差异
如果团队用的是 uni-app 或 Taro 这类多端框架，底层的微信配置仍然存在，只是位置变了。以 uni-app 为例，manifest.json里的“微信小程序配置”相当于project.config.json的一部分，AppID 在这里配置。用 HBuilderX 发行到微信小程序时，它会在dist/dev/mp-weixin目录下生成对应的project.config.json，这个生成物不要手动改，也别提交到 Git（它属于构建产物）。
多端框架的多人协作，原有的 Git 流程不变，但多了“是否需要提交编译产物”这一个变量。我的建议是：统统不提交，统一在各自本地跑构建。如果团队里有人习惯直接用微信开发者工具打开构建目录改代码，迟早有一天会把工具里的手动修改覆盖掉。
5. 从配置到习惯：一个小脚本解决“配置漂移”
制度讲多了容易忘，我分享一个我们团队一直在用的小技巧：用 Git 钩子检查project.config.json是否被本地改乱。
在.git/hooks/pre-commit里放一个脚本，判断project.config.json是否包含某个团队的“标准指纹”，比如 AppID 是否还指向正式环境的 ID：
#!/bin/sh if grep -q '"appid": "wx1234567890abcdef"' project.config.json; then echo "project.config.json appid is correct" else echo "Error: project.config.json appid seems wrong" exit 1 fi当然这只是一个很朴素的示例。更严谨一点，可以写一个脚本把公共配置和project.private.config.json做 diff，把差异打印出来给开发者确认。但说实话，对于绝大多数团队，一条简单的规则就够了：公共配置不许本地乱改，个人配置不许提交远程。
配置流程写到这里，回头看踩过的那些坑，几乎没有一个是“技术含量高”的，全部都是流程和习惯问题。小程序多人开发比起写业务代码，更像是在搭建一套“大家都能顺畅工作的操作系统”。把这套配置理顺了，你会发现团队效率的提升不是一星半点——至少不会再出现“三天光配置环境”这种事了。