在公司里接手一个小程序项目时，最常听到的一句话是“这功能我本地跑得好好的，怎么你一拉下来就报错”。做了几年微信小程序开发，从一个人单干到带三个人的小团队，再到和前端、后端、产品一起协同，我最大的感受是：小程序多人开发这件事，技术上没什么高门槛，真正难的是把“配置”这件事理清楚。AppID不统一、成员权限没配好、每个人本地环境不一样、上传体验版互相覆盖……这些问题几乎每个团队都会踩一遍。这篇文章就把微信小程序多人开发的完整配置流程梳理一遍，从公众平台的角色权限，到开发者工具的本地设置，再到代码托管、自动化上传、真机联调的配合方式，尽量让团队里每个人拿到项目就能跑，少踩坑。

1. 先理顺角色与权限：微信公众平台的多人协作基础

1.1 项目成员的三种角色和边界

很多人第一次接触多人开发，误以为只要把代码仓库共享给同事就够了。实际上微信小程序有一个前置门槛：你的微信账号必须是这个项目的成员，才能在开发者工具里正常操作。这个成员关系是在微信公众平台（mp.weixin.qq.com）里配置的，和代码仓库完全是两套体系。

登录公众平台后，在“管理-成员管理-项目成员”里添加成员，支持按微信号搜索、按手机号搜索、按邮箱邀请。添加时可以指定角色，角色分为三种。

管理员拥有最高权限，可以修改小程序的基本信息、配置服务器域名、管理所有成员、发布代码、查看数据分析，甚至注销账号。项目成员可以上传代码、在开发者工具里预览和调试，也可以查看大部分开发相关的配置，但不能修改小程序的核心信息，比如不能修改AppID对应的主体信息、不能操作“成员管理”这类账号级操作。体验成员只能扫码体验开发版和体验版，不能上传代码，也不能进入开发者工具操作。

这里有一个实际工作流的细节：如果团队里有后端同学需要联调接口，或者有产品经理想看最新效果，他们不一定需要“项目成员”权限。给他们加“体验成员”就够了，直接用微信扫码打开体验版，省去安装开发者工具的步骤。但是体验成员的数量是有限制的，我记得现在一个项目大约可以添加几十个，超过了就需要删除旧的再添加。这个限制在团队规模扩大时要提前规划，别等到要拉人体验时才发现加不进去。

还有一个容易忽略的点：在公众平台添加项目成员时，系统会提示该成员是否已绑定小程序账号。如果对方微信没有注册过小程序相关账号，添加时会要求先注册一个，这里会多一步操作，但通常不影响最终结果。实操中我建议团队里每个人第一次进入开发者工具时，先用自己微信扫码登录一次，确保账号能正常打开工具，再让管理员去后台添加权限。顺序反了的话，就会出现“已经加我了我还是没权限”的错觉，其实是登录的账号和添加的账号不一致。

1.2 AppID是团队的“统一身份标识”

AppID（小程序ID）是每个微信小程序的唯一身份证，格式类似 wx + 一串字符。多人开发里最容易出现的问题之一，就是不同成员本地项目使用的AppID不一致，导致预览、上传、调试时行为完全不一样。

一个正规流程是：小程序还没注册时，开发者可以在工具里选择“测试号”，这种AppID适合个人快速体验功能，但测试号没有真实的后台配置能力，不能上传审核，也不能做完整的域名配置。团队正式协作时，必须有一个注册好的小程序AppID，所有人统一使用这个。项目负责人从公众平台“开发-开发管理-开发设置”里找到AppID，发给团队所有人。

这里要特别提醒：公众平台里还有一个AppSecret（小程序密钥），这个和AppID不一样，AppSecret相当于账号密码级别的敏感信息，主要给后端服务器调用接口时使用，绝对不能直接贴在代码仓库里，也不能发给全员。如果开发中有成员需要用到后端接口签名，应该由后端统一保管和调用，而不是把AppSecret分发到每个前端开发者的电脑上。项目里如果发现有人把AppSecret提交到了Git记录中，建议立刻去公众平台重置，别嫌麻烦。

在实际项目中，我们还遇到过一种情况：团队成员自己私下注册了一个测试号，本地开发时一直用测试号AppID，功能都正常，但上传代码时才发现这个测试号没有认证、没有配置合法域名，导致体验版里所有请求都发不出去。所以建议团队约定一个硬性规则：本地开发统一用正式AppID，不要为了“个人测试”去临时换号。

1.3 常见权限类报错与处理

我整理几个团队日常最容易遇到的权限相关报错，方便排查。

• “当前微信号尚未绑定小程序”，大概率是开发者工具登录的微信和公众平台添加成员的微信不是同一个账号。
• “没有权限上传代码”，说明你的角色不是管理员或项目成员，或者管理员还没把你加到项目成员列表里。
• “请求失败，invalid appid”，这是DevTools里项目配置的AppID不对，检查project.config.json以及导入项目时输入的AppID。
• 开发工具里后台日志显示“invalid credential”，检查是否在小程序代码里硬编码了别人的AppSecret，或者后端调用access_token时有缓存异常。

团队内部建议维护一份“项目成员与权限登记表”，包含成员微信昵称、角色、加入时间、离职/移除时间。虽然听起来很土，但小团队流动起来后，这张表能帮你快速定位“为什么这个人总没权限”的问题，尤其是新成员入职时。

2. 开发者工具侧配置：让每个人在正确环境里开发

2.1 项目导入与project.config.json里容易踩的坑

微信开发者工具导入项目时会读取项目根目录的 project.config.json，这个文件非常重要，它记录了小程序的AppID、项目名称、编译设置、代码上传配置等信息，而且默认是跟随代码仓库一起提交的，这意味着它会影响团队里每一个人。

最常见的坑有这些。

AppID字段是明文存储在 project.config.json 的 appid 字段里。如果某个人不小心在本地把自己的测试号AppID写进了这个字段并且提交了，所有人拉代码后都会变成测试号。所以代码审查时要关注这个文件的变更。建议做法是在项目文档里说明：本地如果因为测试需要修改AppID，不要提交到共享分支。

projectname 字段如果不同成员使用不同版本的工具修改过，会产生大量无意义的diff。这个可以手动固定，或者接受它每次变动，但要在合并时注意别产生冲突。

setting 节点里有多个编译选项，比如 es6 转 es5、增强编译、样式自动补全、minify（代码压缩）等，多人协作时最好由一个人统一维护这套配置，其他人不要乱改。因为如果A在本地开启了“上传时压缩代码”，B没开，两人上传的产物体积和代码形态就不一样，排查线上问题时容易产生错觉，以为是代码问题，其实是压缩配置不同。

还有一个新版工具容易忽视的文件，private.config.json。这个是开发者工具自动生成的本地私有配置文件，存储当前登录用户的一些本地设置，比如最近打开页面、个人自定义编译条件等。微信官方设计这个文件的初衷就是让它不参与团队共享，因为它只对当前开发者在当前电脑上有效。实际使用中，很多人没把它加入.gitignore，导致每个成员打开项目后，这个文件不断被修改，Git里每天都有这个文件的变动记录，非常烦人。规范做法是在.gitignore里加上 private.config.json，项目成员本地各自生成，互不影响。

2.2 多团队成员同时操作时的编译模式与本地设置

开发者工具支持自定义编译模式，可以在“普通编译”右侧的下拉框里添加编译模式，指定启动页面、启动参数、进入场景等。这对多人协作非常有用，比如负责支付页面的同事可以建一个“启动即进入支付页”的编译模式，不用每次手动跳转。

但要注意，编译模式如果保存在 project.config.json 的 condition 字段里，它是会跟着代码仓库走的。这也意味着，如果A加了一堆自己调试用的编译模式，B拉下来后会看到一堆没用的模式，虽然不影响功能，但界面会变得杂乱。我见过有人把七八个临时编译模式提交上去，别人每次编译下拉列表找半天。合理做法：把团队公共的编译模式（比如首页、登录页、核心业务页）保留在配置里，个人临时调试用的模式用完后及时删掉，不要随手提交。

本地设置里还有两个关键项：“不校验合法域名、web-view（业务域名）、TLS版本以及HTTPS证书”和“调试基础库版本”。这两个都是只影响本地的配置，不会跟随代码仓库同步，团队成员可以按自己的需要单独设置。但正因为是本地设置，很多新人会困惑：为什么A本地请求正常，B一预览就报“url not in domain list”。原因就是A勾选了不校验域名，B没勾。联调时建议明确要求所有成员都统一处理：要么都勾选以便联调，要么都不勾选以保证体验版表现一致。

调试基础库版本建议团队约定一个最低版本。小程序基础库是微信客户端里运行小程序的那套框架，不同版本支持的API略有差异。如果A用最新的基础库开发，用了某个新API，B的本地基础库版本较旧，跑不起来，就会以为代码错了。团队里可以约定统一使用当前稳定版，或者由项目负责人指定一个折中版本。工具里有“详情-本地设置-调试基础库”可以切换，也可以在代码里通过 wx.getAppBaseInfo 检查用户端基础库版本，但那是运行时的兼容逻辑，开发阶段不需要这么复杂，统一工具版本即可。

2.3 多账号轮换与工具登录态管理

开发者工具本身是支持多账号登录的，但同一时间只能使用一个有效登录态。团队里如果有多个小程序项目，成员需要频繁切换账号时，可以通过工具右上角的头像菜单退出登录再切换。

实际操作中，工具偶尔会出现诡异的“状态失效”，具体表现为虽然能看到项目列表，但上传代码时提示“登录态已过期”或“请重新登录”。很大一部分原因是本地缓存了过期的登录凭证。我遇到多次后的经验是：先退出账号重新登录，不行就关掉工具，清掉项目缓存目录，再重新打开项目。开发者工具的缓存目录一般在用户目录下的 Config 文件夹里，比如 Windows 的 %APPDATA%\Tencent\微信开发者工具，macOS 的 ~/Library/Application Support/微信开发者工具。清理缓存时注意备份自己本地未提交的代码，但通常不会影响到项目源文件，只是会重置工具的登录态和一些界面设置。

这里还有一个多人开发特有的现象：如果团队用同一个微信账号登录开发者工具（比如公司统一注册一个“测试号微信”），虽然可以绕过一个个添加成员的步骤，但风险很大。一旦这个账号被微信风控限制，或者有人误操作，全团队都会瘫痪。而且同一个账号多人同时操作时，开发者工具的登录态会互相踢下线，非常影响效率。所以还是老老实实每个人添加为独立成员，该配置的权限一定配到位。

3. 代码托管与多人协同工作流：把“协作”变成“流程”

3.1 用Git管住微信小程序项目：哪些文件该提交、哪些必须忽略

多人开发绕不开代码版本管理，微信小程序项目本质也是一个普通的JavaScript项目，使用Git没有任何特殊性。但小程序项目有一些特有的文件需要处理。

必须提交到仓库的包括：项目源代码（pages、components、utils等）、app.js、app.json、app.wxss、project.config.json、sitemap.json、以及你引用的npm依赖包里的miniprogram_dist目录（如果用了npm构建的小程序包）。注意这里和普通Web项目不太一样：普通项目用npm install安装依赖，然后通过构建工具打包；而小程序的npm支持是通过开发者工具“构建npm”功能实现的，它会把node_modules里标记为miniprogram的包编译到miniprogram_npm目录。这个miniprogram_npm目录在团队协作时需要一起提交到仓库，否则成员拉下代码后如果本地没执行“构建npm”步骤，运行时会找不到对应的包。

需要忽略的文件包括：node_modules、miniprogram_npm（如果你选择不提交，但这不推荐）、private.config.json、.idea、.vscode、.DS_Store、以及各种日志和临时文件。建议在项目根目录统一维护一个.gitignore，这个文件本身被提交到仓库，避免每个人各自建一套。

我团队的.gitignore大概长这样：

node_modules/ miniprogram_npm/ private.config.json .idea/ .vscode/ .DS_Store *.log project.private.config.json

这里再强调一次 private.config.json 和 project.private.config.json，这两个都是本地私有配置文件的变种，不同版本工具命名略有差异。只要记住一点：所有以private命名的配置文件都代表“个人本地配置”，不应进入版本库。如果项目里还没有这个文件，可以在.gitignore里提前写上，比如 project.private.config.json，省得以后手滑提交。

3.2 分支策略和合并流程：从单干到多人不打架

多人协作时Git分支策略如果太随意，就会出现“我改了A文件，你改了同一个区域，合并时冲突到怀疑人生”的情况。微信小程序项目虽然文件多，但经常发生冲突的是几个全局文件，比如 app.json、app.wxss、某个公共组件的js文件、project.config.json。

我建议团队采用相对简单的分支模型，不用刻意搞复杂。主干分支（main/master）保持稳定，永远是可发布状态。开发分支（develop）用于日常集成，成员各自从develop拉出功能分支（feature/xxx或者fix/xxx），开发完成后合并回develop。发布前从develop拉一个release分支，测试通过后再合并到main，并打上版本tag。

这种方式对小程序项目来说够用且清晰。核心原则是：项目负责人对main分支有合并权限的监督责任，不要让所有成员直接往main上推。如果团队规模小到只有两三个人，可以简化成直接在main上开发，但至少约定好：改动核心配置前先沟通，比如app.json里新增了一个页面路由，可能影响其他同事正在开发的页面，最好先通知一声再提交。

合并冲突时，最常见的处理工具还是IDE里的冲突解决面板。以微信开发者工具自带的Git面板来说，它提供了基本的“拉取-提交-推送”能力，但对复杂冲突的解决体验一般，我更推荐直接在VS Code里操作Git。这里有一个小程序项目特有的提醒：处理完冲突后一定要重新跑一遍“构建npm”，确保miniprogram_npm目录和package.json一致，否则会出现本地跑得好好的，上传后却报模块找不到的情况。

另外，提交信息建议遵循一个简单规范，比如：

• feat: 新增某某功能
• fix: 修复某某Bug
• chore: 调整项目配置或构建脚本
• docs: 更新文档

这套规范不必做成强制工具链，只要团队在代码审查时强调一下即可。一个好的提交信息，在追溯“这个功能为什么这么写”时非常有用，尤其对小程序这种需求变更频繁的项目。

3.3 自动化上传：用miniprogram-ci把上传体验版变成一条命令

多人开发当中的一个痛点，是“上传体验版”这件事太依赖个人操作。A提交代码到develop，B需要测试体验版，B不能自己上传，得让A手动在工具里上传，还要填版本号和备注，完了再把体验版二维码发给B。这个过程一旦团队人数增长，就会成为瓶颈。

微信官方提供了miniprogram-ci这个命令行工具，专门用来在小程序代码仓库里执行编译、预览、上传等操作。配置完毕后，团队成员可以在本地执行一条命令，或者让CI服务器（比如GitHub Actions、GitLab CI）在代码合并后自动构建并上传体验版。

miniprogram-ci的基本使用流程是这样的。

在公众平台后台的“开发-开发管理-开发设置”里找到“小程序代码上传”，生成“上传密钥”。这个密钥是一个私钥文件，下载后需要保存好，它对应一个密钥名称，后面配置时要用。

在项目里安装miniprogram-ci：

npm install miniprogram-ci --save-dev

然后在项目根目录写一个上传脚本：

const ci = require('miniprogram-ci') const path = require('path') const project = new ci.Project({ appid: 'wx你的AppID', type: 'miniProgram', projectPath: path.resolve(__dirname), privateKeyPath: path.resolve(__dirname, 'private.key'), ignores: ['node_modules/**/*'], }) ci.upload({ project, version: '1.2.3', desc: '测试环境自动构建', setting: { es6: true, minify: true, }, }).then(res => { console.log('上传成功', res) }).catch(err => { console.error('上传失败', err) })

执行：

node scripts/upload.js --version=1.2.3 --desc=测试版

配置好后，上传体验版就从“人工点鼠标”变成了“命令行操作”。接着可以和CI结合，比如develop分支有新提交时，CI自动跑测试、自动上传一个体验版，然后把二维码链接发到企业微信群里。团队里负责验收的人直接扫码即可，不再依赖某个成员在线点击上传。

这里要特别强调私钥的安全性。miniprogram-ci的私钥等同于AppSecret级别的权限，可以上传代码，所以绝对不能提交到Git仓库里，也最好不要放在开发者本地五花八门的位置。规范做法是：在CI系统的环境变量里配置私钥内容，本地开发时如果需要跑上传脚本，私钥单独放在项目目录之外的一个隐藏目录，并且加入.gitignore。我见过团队把private.key提交进仓库，没过多久就发现有人用这个密钥上传了非官方代码，最后不得不重新生成密钥并清理Git历史，非常被动。

有了miniprogram-ci之后，团队的分工就更清晰了：开发者在本地写代码、做本地调试，上传体验版交给脚本或CI，发布正式版仍然走公众平台的人工审核流程。自动化和人工审核之间有一个明确的分界，既保证了效率，也没有绕过微信官方的审核机制。

4. 真机调试、体验版与发布配合：多人协作的“验收环节”

4.1 真机调试的多人协调技巧

在开发者工具里调试比较方便，但很多问题必须真机验证，比如摄像头调用、定位、分享到朋友圈、微信支付等。真机调试需要同时打开开发者工具和你手机上的微信小程序调试页面。这里有一个多人开发的细节：真机调试时，手机和电脑需要在同一个局域网内，由开发者工具建立一个临时的调试通道。如果团队多人同时进行真机调试，又有同事在看视频、开在线会议，网络带宽被大量占用，调试通道很容易断开，表现为手机上显示“调试连接已断开”或请求超时。

我经历的多人协作场景里，最稳妥的安排是：给真机调试分配时间段。比如上午10点到12点是A和B联调支付流程，下午2点到4点是C联调分享。如果时间冲突，至少保证同一WiFi下不要同时开启两个以上的真机调试。这个安排看起来有点“土”，但在小团队里非常有效，能避免大家一起卡顿、互相甩锅网络问题。

真机调试另一个常见的坑是请求无法到达后端。开发工具里勾选了“不校验合法域名”，真机调试时也有效。但如果成员在真机调试时使用的微信版本较新，或者调试基础库版本较高，部分地区或某些情况下真机调试依然会拦截非法域名请求。所以多人联调时，最好把后端接口域名先配到公众平台的request合法域名里，走正规通道，而不是长期依赖“不校验域名”。尤其是多人同时调试时，统一配置合法域名能减少大量无意义的神秘问题。

4.2 体验版和测试版本的更新与通知机制

体验版是介于开发版和正式版之间的一个状态，它在公众平台后台选择某个上传过的版本，设置为“体验版”，之后体验成员扫码即可打开。体验版每次更新后，之前的二维码链接是否还有效？这是团队里经常出现的疑问。简单说，体验版二维码对应的是当前被设置为体验版的那个版本，如果你上传了新版本但没有重新设为体验版，体验成员扫码看到的还是旧版，看起来就像“更新没生效”。

多人协作时，这个机制特别容易造成误会。A上传了新版本并设为体验版，B交付时也上传了一个版本，B没有设为体验版。测试同学扫码看到的还是A的版本，于是反馈“B改的功能没生效”。之后团队里就多了一条规矩：谁要把版本给测试或产品体验，谁自己负责上传并去后台设为体验版，然后把新的体验版二维码或小程序路径发到群里。这比在群里反复问“你更新了吗”要高效得多。

还有一个细节是，体验版二维码能通过开发者工具里的“上传”按钮直接生成分享卡片，也可以在公众平台后台的“版本管理”页面下载体验版二维码。团队里如果接了企业微信，可以用企业微信的机器人把体验版二维码和版本号、更新说明一起发出来。这样体验成员不用每次问“去哪扫码”。这一连串操作其实可以和前面说的miniprogram-ci联动，自动上传后由CI脚本生成一个带版本号和日期的二维码图片，推送到工作群。

4.3 与后端同学的域名白名单配合

微信小程序在正式环境里对网络请求有严格限制：request、uploadFile、downloadFile、connectSocket等接口只能请求在公众平台配置的合法域名。这个域名白名单不是实时生效的，修改后通常需要一两分钟才能完全生效，团队成员如果刚好在修改域名后立即测试，可能会遇到“白名单还没生效”的情况。

多人开发的建议是：后端接口域名，包括测试环境域名和正式环境域名，都提前在公众平台配置好。测试环境域名可能是一个类似 https://test-api.example.com 的独立域名，正式环境是 https://api.example.com。如果后端开发同学频繁变更测试环境域名，前端团队会非常难受，因为每次都要去公众平台改配置，还要等生效。理想方案是测试环境域名长期稳定，后端在同一个域名下通过路径或请求头区分环境。

另外，团队里后端往往没有公众平台的账号权限，域名配置通常由前端负责人或管理员操作。实际操作中，我建议把“域名变更”纳入发版流程的一部分，比如每次涉及新接口域名，都要在发布检查单里加一项“检查request合法域名是否已添加”。这个细节看起来不起眼，但我见过不止一次：开发阶段一直开着“不校验域名”，发版当天忘了配域名，结果正式版上线后所有请求全挂，紧急修复时用户已经在评论区开骂了。

4.4 发布审核与版本回退注意事项

小程序的正式发布需要走微信审核，审核通过后可以选择“全量发布”或“分阶段发布”。多人协作时，版本管理和发布这件事最好集中在一个人身上，通常是项目负责人或者有公众平台管理员权限的核心成员，不要每个人都去点“提交审核”。

原因很简单：小程序的审核是有成本的，提交前如果没确认代码分支是否正确、体验版是否已经由产品确认过，提交后被打回，一来一回浪费好几天。团队内部可以约定一个“提审清单”：代码合并到main分支，版本号在app.json或project.config.json里已更新，体验版已验证核心流程，后端接口正式环境已确认可用，域名白名单已配置完成。这个清单在人数多的团队里尤其重要，可以避免“谁都能提审，出了问题没人负责”的混乱局面。

如果不小心发布了有问题的版本，微信公众平台支持把线上版本回退到之前的版本。在“版本管理-线上版本”里可以找到回退按钮。回退操作比较迅速，但要注意：回退只能回到之前审核通过的版本，如果你中间有好几个版本没上线，回退只能回到最近一次审核通过的版本，不能任意选择历史版本。所以团队在上线前最好养成打Tag的习惯，每个发布过的版本在Git里都有对应的记录，便于定位问题。

还有一个建议：发布正式版时，版本号要和应用内的版本展示、更新日志保持一致。微信小程序虽然不需要像App那样展示版本号，但后台审核时填写的版本号和备注，会成为后面排查问题的关键信息。如果线上出了问题，用户反馈说“打开小程序白屏”，你先要知道他现在跑的是哪个版本。如果每次发布时版本号和备注都写得随意，这一步排查就会很费劲。

5. 多人开发高频问题排查实录（含踩坑笔记）

5.1 为什么同事拉下来代码运行报错“appid不合法”

这个问题的直接原因往往是 project.config.json 里的appid被某个人改成了自己的测试号，然后被提交到了共享分支。排查方法：打开项目根目录的 project.config.json，查看appid字段，和公众平台里的正式AppID做对比。如果不对，改回来，并且确认.gitignore里是否忽略了 private.config.json。很多新手会把AppID填到 private.config.json 里的一个覆盖字段，导致 project.config.json 里看着是对的，但运行时实际生效的是 private.config.json 里的值。所以排查时两个文件都要看。

为了避免反复出现，除了代码审查时关注这个字段，也可以约定用简单的git hook脚本，判断提交时 project.config.json 的appid是否匹配某个前缀，不匹配就直接拒绝提交。这个hook不需要很复杂，十几行Node.js脚本就够了。

5.2 上传体验版后从“测试反馈没问题”到“页面白屏”

白屏问题多人协作时很常见。一个典型场景：A在本地开发时页面正常，上传体验版后打开白屏。排查时先要区分“所有人白屏”还是“部分人白屏”。如果所有人白屏，多半是代码在编译阶段就有问题，比如用了某个API在当前基础库版本上不支持，或者app.json里页面路径写错，又或者上传的代码不是最新的（记得前面说的，上传后还要设为体验版）。如果部分人白屏，要先确认白屏的人是什么微信版本、什么机型，有可能是新API在旧基础库上跑不了。

每次排查白屏，我都会建议先打开调试模式。体验版默认能看到调试按钮，在开发者工具里的“真机调试”入口也能看到体验版的报错信息。还有一个小技巧：在app.js的onLaunch里加一个全局错误捕获，把错误上报到自己的日志系统。这个动作在开发初期就做，不要等到上线后再补，多人开发时可以避免大量“我看不到报错”的问题。

5.3 不同人开发者工具版本不一致导致基础功能表现不同

团队里有人用稳定版，有人用RC版，有人一直不升级，这本身就有风险。微信开发者工具的升级会带一些基础库行为变化，有些变化是隐性的，比如某个组件样式调整了、某个API的返回参数变了。多人协作时，建议在项目文档里写明“推荐使用的开发者工具版本号”，新成员入职时直接按这个版本安装，而不是随便下个最新版。

还有一点，项目根目录可以放一个 .editorconfig 文件，统一缩进风格、换行符等。不同操作系统（Windows和macOS）在拉取代码时不改变换行符，但如果你用不同编辑器保存过文件，可能会混入LF和CRLF，导致Git diff里出现大量“假修改”。这种现象在小程序项目里很常见，因为很多人直接用微信开发者工具打开就改文件，而工具在不同平台的换行符处理并不完全一致。配置好.editorconfig后，这个问题基本能消除。

5.4 多人同时改 project.config.json 导致冲突

这个文件是多人协作中的“高频冲突源”。原因在于工具每次打开项目、修改本地设置时都可能顺手更新这个文件。多人都在提交它时，冲突概率很高。我的建议是：

把 project.config.json 里和团队共享的核心配置（appid、miniprogramRoot、compileType、setting里部分关键项）维护好后，提交到仓库。对于那些和本地环境强相关的字段，比如工具版本号（toolkit）、上次打开页面等，如果Git diff里只有这些内容，就不要提交。对于团队成员各自的小工具偏好，可以靠private.config.json隔离。这样虽然不能完全避免冲突，但能把冲突次数从每天变成偶尔。

如果冲突实在频繁，另一个方案是让项目负责人定期维护 project.config.json，其他人遇到配置变更时，把变更交给负责人统一合入，而不是各自往分支上推。这种方式适合“配置敏感型”的项目，牺牲一点灵活性，换来的是稳定。

5.5 真机调试请求无法到达后端的排查顺序

真机调试请求到不了后端，通常按这个顺序排查：先看开发者工具里是否正确打开了“真机调试”并保持了电脑和手机在同一局域网；再看微信开发者工具里的调试器Network面板有没有请求记录；如果没有请求记录，大概率是请求被微信拦截，检查合法域名配置；如果有请求记录但响应超时，检查后端服务是否只监听了localhost或内网IP，没有对局域网开放；最后看HTTPS证书是否有效，真机调试时分两种情况处理。实测下来，团队里联调遇到最多的还是后端服务只监听在127.0.0.1，手机当然访问不了。解决方法是让后端启动时监听 0.0.0.0，或者改用局域网IP访问。

还有一个容易忽略的点：如果后端接口用的是自签名HTTPS证书，开发者工具里勾选了“不校验合法域名、web-view（业务域名）、TLS版本以及HTTPS证书”就能在真机调试里正常访问。但新版本的微信客户端在某些情况下即使打开了这个选项，自签名证书依然被拒绝。这种情况建议直接用线上测试环境域名联调，少在证书上折腾。

最后再分享一点个人体会。微信小程序多人开发的配置流程，本质上和大家熟悉的Web项目多人协作没有太大区别，无非是成员管理、代码托管、环境统一、发布配合这几件事。但小程序特有的“平台-工具-仓库”三层结构，决定了它有一些独特的坑：AppID要和代码仓库同步、域名白名单要提前维护、体验版更新要养成流程、上传密钥要严格保密。把这些东西在项目初期就定好并形成文档，比等到团队扩大到十个人再来补救要轻松得多。我带的项目在经历了前面所有踩坑之后，总结了一套固定的入职流程，新成员拿到文档后半小时内就能把环境跑通，不再需要旁边有人一步步教。这可能才是“配置流程”真正的意义所在。