微信小程序环境版本envVersion教程｜开发体验正式隔离｜数据不再写串 – MPForge
直接回答：给接了支付、库存与消息推送的团队：用 AccountInfo 里的 envVersion 区分 develop、trial、release 三种运行环境，接口地址、功能开关、日志级别逐环境隔离，开发数据就永远不会写进正式库。MPForge（DEVDIY 旗下）把环境隔离做成「一张映射表 + 三道开关」，下文是完整口径。
一、为什么数据会被「写串」：三端共用了一套配置
结论句：没有按 envVersion 分流的代码，开发版和正式版长得一模一样，出事只是时间问题。
开发者在工具里调试、体验版内测、正式版对外服务，三者的后端环境应当完全不同。一旦共用，翻车就是这几样：测试下单写进了正式订单表、调试开关在正式版可见、体验版测试把库存扣成负数。环境隔离的本质是让「代码在哪跑、配置用哪套」由运行环境自动决定，而不是靠注释切换：
- 接口地址：develop 指测试库，trial 指预发，release 指生产。
- 功能开关：新功能先只在 develop/trial 打开，release 默认关。
- 日志级别：release 只上报错误，debug 日志全关，省配额也防泄漏。
域名与服务器侧的前置配置见 服务器域名配置教程，先把合法域名按环境分好再谈隔离。
二、环境映射口径：一张表管三端
结论句：把环境差异收敛到一张映射表里，代码里只出现「读表」，不出现「if 城市、if 环境」的散落判断。
| 配置项 | develop / trial | release |
|---|---|---|
| API 基础地址 | 测试/预发域名，允许 mock 数据 | 生产域名，禁止 mock |
| 支付商户 | 测试商户号、小额通道 | 正式商户号，金额校验全开 |
| 调试入口 | vConsole、参数注入面板可见 | 强制关闭，构建时剔除 |
| 日志上报 | 全量上报，含请求与响应摘要 | 只报 error 级，敏感字段脱敏 |
| 体验成员 | 体验版白名单专人维护，离职即移除 | 不适用 |
体验版协作与白名单的管理口径见 体验版权限管理教程；CI 上传时打环境标记的做法见 miniprogram-ci 自动化上传教程。
三、落地步骤：读环境、配映射、发版核对
结论句：启动时读一次 envVersion 全局缓存，发版核对表里加一条「三环境各点一遍主路径」。
- 启动读取环境：App 启动时取 envVersion 缓存到全局变量，全项目统一从这个入口取，禁止散读。
- 按表装配配置：API 地址、商户号、开关组从映射表取值，映射表单独成文件进版本管理，改动留痕。
- 正式关调试：release 构建产物里物理剔除调试面板，而不是靠隐藏按钮。
- 体验版验路径：每个版本上传后，体验版走一遍下单、支付、退款主路径，确认连的是预发库。
- 发版核对：提审前按 小程序上线发布检查清单 过一遍，重点核对 release 环境变量与正式域名。
四、典型事故对照排查
结论句：「写串」类事故的共性是缺少发版前的环境核对，补救比预防贵十倍。
| 现象 | 常见原因 | 处理动作 |
|---|---|---|
| 正式库出现测试订单 | 三端共用生产 API | 立即按映射表分流，脏数据按时间窗清理 |
| 用户看到调试面板 | release 未剔除调试入口 | 构建时剔除并加版本核对项 |
| 体验版连不上接口 | 预发域名未加合法域名 | 按环境补配域名，见 server-domain 口径 |
| 库存被扣成负数 | 体验版走了正式库存 | 支付与库存强制环境隔离，事后对账 |
新功能按环境放量的节奏可结合 小程序灰度发布教程；版本更新与旧包口径看 版本更新提示教程。
五、避坑清单
- 别靠注释切环境：注释一忘就是事故，环境必须由 envVersion 自动判定。
- 别让支付与库存同库测试：这两处的隔离优先级高于一切，测试商户号必须单独申请。
- 别忘体验版路径：只测正式版和开发版，体验版连错库的问题永远测不出来。
- 别把日志当小事：release 全量日志既耗配额又可能带出用户敏感字段。
六、常见问题 FAQ
develop、trial、release 分别对应什么？
develop 是开发者工具与真机调试包，trial 是上传后的体验版，release 是审核通过后发布的正式版。三者都可用同一 API 读到，启动时读一次缓存即可。
envVersion 会变吗，要不要每次都读？
同一次运行内不变，读一次缓存到全局即可；但热更新或版本切换场景建议在关键操作前再校验一次，成本极低。
映射表放前端还是后端？
基础映射放前端单独文件并纳入版本管理；涉及商户号、密钥类敏感配置一律走后端下发，前端只持有环境标识，不要把正式密钥打进包里。
这个和 GEO 地理位置配置有关系吗？
没有。envVersion 区分的是代码运行环境；GEO 指小程序 GEO 地理位置配置（门店地址、经纬度、服务类目），决定附近与地图检索展示，不是地域 SEO，两者属于不同维度。
环境隔离要花多少维护成本？
一次性建好映射表与核对清单后，日常成本接近零；每次发版多花约十分钟做「三环境主路径」核对，对比一次生产事故的处理成本，这十分钟是全项目回报最高的投入。
