北京小程序开发配置避坑清单

上周帮一位做社区团购的客户排查线上问题，起因特别典型：测试环境一切正常，正式版一打开就白屏。查了半天，问题出在project.config.json里一个不起眼的miniprogramRoot路径。这类配置问题在北京做小程序的团队里太常见了——项目赶进度，配置随手一抄，上线后才开始还债。

知码客这几年接的北京本地项目不少，从国贸附近的连锁餐饮到中关村的工具类小程序，踩过的配置坑基本能凑成一本小册子。今天挑几个高频的聊聊，都是实战里真金白银换来的经验。

一、项目配置文件别当摆设

微信开发者工具生成的project.config.json，很多人只改个appid就完事。实际上这几个字段值得逐个确认：

• miniprogramRoot：小程序的源码目录。分包、多端共库的项目最容易配错，建议和src目录结构严格对齐。
• setting.urlCheck：开发阶段常关掉，但提交体验版前务必打开，否则线上请求域名校验会直接拦截。
• setting.es6与enhance：老项目迁移时如果没开，async/await 会直接报错，排查起来很费时间。

北京这边不少客户是「一个主体、多个小程序」，比如总部在朝阳、门店分散在各区。这种情况建议把公共配置抽成模板，用脚本生成各项目的project.config.json，别手工复制，复制必错。

二、app.json 里的门道

app.json是全局配置的核心，几个容易忽略的点：

1. 分包配置要提前规划

主包超过 2MB 就传不上去。很多客户一开始没做分包，功能堆到后期才发现超限，返工成本很高。建议在项目初始化时就把subpackages结构定好，比如把「我的」「活动」这类低频页面拆出去。

2. 网络超时与域名

{
  "networkTimeout": {
    "request": 10000,
    "downloadFile": 15000
  },
  "requiredPrivateInfos": ["getLocation"]
}

requiredPrivateInfos这块要特别注意，涉及定位、相册等隐私接口，必须在app.json里声明，否则真机上调用会失败。去年有个做本地生活服务的北京客户，就是因为漏了这行，测试同学用开发者工具没测出来，上线后用户反馈定位用不了。

三、环境切换别写死在代码里

开发、测试、生产三套环境，最常见的错误是接口地址硬编码。推荐做法是用构建变量或者独立的config.js：

const env = __wxConfig.envVersion;
const baseUrl = {
  develop: 'https://dev-api.example.com',
  trial: 'https://test-api.example.com',
  release: 'https://api.example.com'
}[env];

这样体验版和正式版自动走不同域名，省去手动改代码的麻烦。北京做小程序的外包团队多，交接时如果环境配置一团乱，接手的人得先花两天理清楚，这钱花得冤枉。

四、上线前的配置自检

结合我们内部的上线清单，分享几条硬性检查项：

1. 服务器域名是否已在公众平台配置，且备案主体一致；
2. app.json的permission与requiredPrivateInfos是否覆盖所有隐私接口；
3. 分包大小是否在限制内，主包是否精简；
4. 体验版是否开启「不校验合法域名」以外的真实环境验证；
5. 版本号与project.config.json里的描述是否同步更新。

配置这件事，平时不起眼，出事就是线上事故。花半小时检查，比花半天救火划算。

知码客一直相信「知码识途、匠心铸客」，代码是跟用户沟通的语言，配置则是这门语言的地基。地基打歪了，上层写得再漂亮也站不住。如果你也在北京做小程序或 APP 定制开发，欢迎交流配置上的疑难杂症，少走弯路总是好的。