石家庄小程序开发：配置避坑指南

上周帮一位石家庄桥西区的客户排查线上问题，小程序在开发者工具里跑得好好的，一进真机就白屏。折腾了两个小时，最后发现是 app.json 里多写了一行注释——JSON 不支持注释，工具容错，真机不容错。这类问题在「小程序开发配置」这个环节里特别常见，今天就把我们知码客在石家庄做小程序时踩过的配置坑，系统地聊一聊。

一、项目配置文件：三个文件决定生死

微信小程序项目的根目录里，有三个配置文件是绕不开的：

• app.json：全局配置，页面路径、窗口表现、tabBar、网络超时都在这里
• project.config.json：开发者工具的项目配置，appid、编译设置、代码上传规则
• sitemap.json：搜索索引配置，很多开发者直接忽略，结果小程序在微信搜一搜里搜不到

先说 app.json。最常见的错误是 pages 数组里路径写错，或者新增页面忘了注册。注意 pages 的第一项就是启动页，顺序不能乱。另外 tabBar 的 list 最少 2 项最多 5 项，图标路径不支持网络图片，必须是本地相对路径，尺寸建议 81×81 像素。

再说 project.config.json。这个文件里最容易出问题的是 appid。我们给石家庄本地客户做项目时，经常遇到客户自己用测试号开发，交付时换成正式 appid，结果 project.config.json 里的 appid 没同步，上传代码时报「appid 不匹配」。建议团队协作时把 project.config.json 纳入版本管理，但把 project.private.config.json 加进 .gitignore，个人调试配置不要污染团队配置。

二、域名与服务器配置：真机调试的第一道坎

小程序请求接口必须走 HTTPS，且域名要在微信公众平台「开发管理 → 开发设置 → 服务器域名」里配置。这里有几个细节：

• 域名不能带端口号，不能是 IP 地址
• 每月只能修改 5 次，改之前想清楚
• request 合法域名、uploadFile 合法域名、downloadFile 合法域名是分开配置的，别只配了 request 就以为万事大吉
• 开发阶段可以在开发者工具里勾选「不校验合法域名」，但真机预览时这个选项无效，必须配好域名

去年给石家庄一家做本地生活服务的客户上线小程序，测试环境用的是一台没备案的云服务器，真机调试一直报「url not in domain list」。后来我们把测试环境迁到已备案域名下，问题立刻消失。所以石家庄做小程序的朋友，服务器域名备案这件事要提前规划，别等到上线前一周才想起来。

三、云开发配置：省掉服务器，但别省掉规划

如果项目不大，云开发是个不错的选择。开通云开发后，在 app.js 里初始化：

App({
  onLaunch() {
    if (!wx.cloud) {
      console.error('请使用 2.2.3 或以上的基础库以使用云能力')
    } else {
      wx.cloud.init({
        env: 'your-env-id',
        traceUser: true
      })
    }
  }
})

注意 env 参数，建议显式指定环境 ID，不要依赖默认环境。我们见过不少项目在开发环境和生产环境之间来回切换时，因为没写 env 导致数据写错库。另外云开发的数据库权限配置也要提前设计，默认的「仅创建者可读写」在很多业务场景下并不适用。

四、基础库版本与兼容性

在 app.json 里可以设置 "requiredBackgroundModes"，但更关键的是基础库版本。微信公众平台后台可以设置「最低基础库版本」，设置太高会流失低版本用户，设置太低又用不了新 API。我们的经验是：先看后台的用户基础库分布，取覆盖 95% 用户的版本作为最低版本，新 API 用 wx.canIUse 做降级判断。

五、上线前的配置检查清单

最后给一份我们知码客内部用的检查清单，石家庄的客户交付前都会过一遍：

1. app.json 里所有页面路径都存在且已注册
2. 服务器域名已配置且备案完成
3. project.config.json 的 appid 与正式账号一致
4. sitemap.json 已配置，允许微信索引
5. 基础库最低版本已设置
6. 隐私协议与用户信息授权接口已适配最新规范
7. 体验版已用真机完整走一遍主流程

小程序开发配置这件事，说难不难，但细节多、坑密。知码客在石家庄做小程序和 APP 定制开发这些年，最大的体会是：配置阶段多花半小时检查，能省下上线后好几个小时的救火。毕竟「知码识途、匠心铸客」，每一行配置代码，都是我们和用户沟通的语言。