小程序开发配置：从零到上线的关键一步

很多朋友在咨询小程序开发时，关注点往往集中在页面好不好看、功能全不全，却忽略了一个决定项目能否顺利上线、后续好不好维护的环节——开发配置。我是知码客，在邯郸做小程序和 APP 开发这些年，见过不少项目因为配置没理清，上线前反复返工。这篇文章就把小程序开发配置这件事讲清楚。

为什么开发配置值得单独拿出来说

小程序和传统 Web 项目不同，它运行在微信、支付宝等平台容器里，账号体系、域名、权限、环境都是平台强约束的。配置一旦出错，常见表现是：本地跑得好好的，真机预览白屏；接口在开发者工具里正常，体验版却请求失败；上线后才发现支付、订阅消息没开通。这些问题不涉及业务逻辑，却会直接拖慢交付节奏。

对本地客户来说更实际：邯郸不少做零售、餐饮、教培的商家，小程序要赶在活动节点上线，配置环节卡住一天，运营计划就得往后推。所以我们团队在项目启动阶段，会把配置清单先过一遍，再进入编码。

账号与主体配置

• 注册小程序账号并完成主体认证，企业主体才能使用支付、部分行业能力。
• 在「成员管理」中添加开发者、体验者，按角色分配权限，避免共用管理员账号。
• 完善服务类目，类目与实际业务一致，否则提审容易被驳回。
• 涉及食品、教育、医疗等行业的，提前准备对应资质。

这一步看似行政工作，但类目和资质直接决定后面能调用哪些接口，建议在写第一行业务代码前就定下来。

项目配置文件：app.json 与 project.config.json

小程序根目录下的配置文件是开发的骨架。app.json 负责全局页面路径、窗口表现、tabBar 和权限声明；project.config.json 记录开发者工具的项目设置，比如 appid、编译模式、是否启用 ES6 转 ES5。

{
  "pages": [
    "pages/index/index",
    "pages/category/category",
    "pages/cart/cart",
    "pages/mine/mine"
  ],
  "window": {
    "navigationBarTitleText": "知码客示例",
    "navigationBarBackgroundColor": "#ffffff"
  },
  "tabBar": {
    "list": [
      { "pagePath": "pages/index/index", "text": "首页" },
      { "pagePath": "pages/mine/mine", "text": "我的" }
    ]
  },
  "permission": {
    "scope.userLocation": {
      "desc": "用于展示附近门店"
    }
  }
}

注意 permission 里的描述要写清楚用途，审核时会看；tabBar 的图标路径和页面路径必须真实存在，否则编译直接报错。

服务器域名与网络配置

这是最容易出问题的一块。小程序只能请求已在小程序后台配置的合法域名，且必须是 HTTPS。开发阶段可以在开发者工具里勾选「不校验合法域名」，但体验版和正式版不行。

• 在后台「开发管理 - 开发设置」中配置 request、uploadFile、downloadFile、socket 四类域名。
• 域名需完成备案，证书有效，不支持 IP 和本地地址。
• 建议开发、测试、生产环境使用不同子域名，避免测试数据污染线上。

我们在给邯郸本地一家连锁门店做小程序时，就遇到过客户原有服务器域名未备案的情况，最后协调更换域名并重新配置，多花了几天。提前确认域名状态，能省下不少时间。

环境区分与密钥管理

appid、AppSecret、支付密钥这类信息不要写死在代码里，也不要提交到公开仓库。常见做法是按环境拆分配置，通过构建脚本注入：

// config/index.js
const env = process.env.NODE_ENV || 'development';
const configs = {
  development: {
    baseUrl: 'https://dev-api.example.com',
    appid: 'wx_dev_xxxx'
  },
  production: {
    baseUrl: 'https://api.example.com',
    appid: 'wx_prod_xxxx'
  }
};
module.exports = configs[env];

AppSecret 只放在服务端，前端永远不接触。涉及支付的商户号、API 密钥同理。

上线前的配置检查清单

1. appid 与后台项目一致，成员权限齐全。
2. 合法域名四类均已配置，证书未过期。
3. 隐私协议、用户信息授权说明已补充。
4. 版本号与体验版、审核版本对应清晰。
5. 订阅消息模板、支付能力按需开通并测试。

把这些配置当成开发的一部分，而不是上线前的临时任务，项目会顺很多。知码客在邯郸做小程序和 APP 开发，习惯在动手前先把配置理清楚，后面写业务代码才踏实。如果你也在准备自己的小程序，不妨从这份清单开始。