小程序开发配置，我踩过的那些坑

上周帮朋友收拾一个半路接手的小程序项目，打开代码仓库那一刻我差点没坐稳——app.json 里塞了三十多个页面，一半是废弃的；project.config.json 里 appid 还是测试号；云开发环境一个都没配，代码里却到处 wx.cloud 调用。能跑起来纯属运气。这让我想起自己刚做小程序那会儿，配置这块也交了不少学费。今天不聊高深架构，就说说小程序开发配置里那些看着不起眼、但能让你卡半天的地方。

app.json：别把它当垃圾桶

很多新手习惯把所有页面往 pages 数组里一扔，觉得反正能跳转就行。问题是，pages 的第一项就是启动页，顺序错了用户进来看到的就是个空白页。我见过最离谱的，第一项是个已经删掉的页面，开发者工具直接报错，排查了半天才发现是这里。

另外 window 配置也值得花五分钟看一眼。导航栏颜色、下拉刷新、背景色，这些在真机和模拟器上表现可能不一样。我当时设了个 navigationBarBackgroundColor 为纯白，结果 iOS 上状态栏文字也是白的，用户根本看不见时间。后来才加 navigationBarTextStyle: "black"。

{
  "pages": ["pages/index/index", "pages/mine/mine"],
  "window": {
    "navigationBarTitleText": "我的小店",
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f5f5f5"
  }
}

project.config.json 和 appid：别用测试号上线

这个文件是开发者工具的本地配置，容易被忽略。最要命的是 appid。测试号能开发能预览，但没法真机调试某些能力，更不能发布。我有次把测试号的项目直接打包给客户，客户扫码打不开，尴尬得不行。

还有 miniprogramRoot 这个字段。如果你用 uni-app 或者 taro 这类框架，编译产物在 dist 目录，配置没指对，工具打开就是一片空白。建议每次换电脑或者拉新仓库，先确认这个路径。

云开发环境配置：一个项目多个环境要小心

云开发确实省事，但环境配置有个坑：wx.cloud.init 里的 env 参数，如果你写死成某个环境 ID，那测试环境和生产环境就混了。我的做法是抽一个配置文件，按编译条件区分。

// config/env.js
const ENV_MAP = {
  develop: 'dev-xxxxxx',
  trial: 'test-xxxxxx',
  release: 'prod-xxxxxx'
}

export const currentEnv = ENV_MAP[__wxConfig.envVersion] || ENV_MAP.develop

// app.js
wx.cloud.init({
  env: currentEnv,
  traceUser: true
})

__wxConfig.envVersion 能拿到当前是开发版、体验版还是正式版，比手动改靠谱得多。这个细节我在官方文档里翻了挺久才注意到。

几个容易漏的配置项

• 服务器域名：request、uploadFile、downloadFile 的合法域名要在后台配，本地开发工具可以勾选“不校验合法域名”，但上线前一定记得关掉这个选项再测一遍，不然真机直接请求失败。
• 分包配置：主包超过 2M 就得上分包。分包路径写错不会立刻报错，而是等到跳转时才提示找不到页面，调试成本很高。
• 隐私协议：现在涉及用户信息的接口，比如获取头像昵称、位置，都要在后台配置隐私协议，没配的话接口直接返回失败，错误码还不直观。

小结

小程序开发配置这块，说难不难，但它是那种“配对了没人夸、配错了全盘皆输”的活儿。我的建议是，每个新项目建好之后，花二十分钟把 appid、页面顺序、云环境、合法域名这四项过一遍，写个 checklist 存在项目根目录。别嫌麻烦，这二十分钟能省下你后面好几个小时的排查时间。配置这玩意儿，稳一点总没错。