小程序开发配置：从项目初始化到上线

小程序的「配置」这件事，看起来只是改几个 JSON 字段，实际却决定了项目能不能顺利跑起来、能不能过审、能不能在真机上稳定运行。很多团队在业务代码上投入很多，配置却随手一填，结果在提审或联调阶段反复返工。这篇文章按项目推进顺序，把小程序开发中真正需要关注的配置项梳理一遍。

一、项目初始化阶段的配置

用开发者工具新建项目时，需要填的几项信息会直接影响后续开发方式：

• AppID：正式开发必须使用已注册的小程序 AppID，测试号只能本地调试，无法使用云开发和部分开放能力。
• 项目名称与目录：目录一旦确定，后续迁移成本不低，建议按「业务名 + 端」命名，避免多人协作时混淆。
• 后端服务选择：选择「不使用云服务」还是「微信云开发」，会决定项目里是否生成 cloudfunctions 目录和云开发配置。中途切换虽然可行，但需要手动补齐配置。
• 模板选择：JS 基础模板、TS 模板、云开发模板的目录结构不同，选错后清理成本较高。

初始化完成后，先确认 project.config.json 中的 appid、compileType、miniprogramRoot 与实际目录一致，这是多人协作时最常见的不一致来源。

二、全局配置 app.json

app.json 是小程序的全局配置入口，核心字段包括：

{
  "pages": [
    "pages/index/index",
    "pages/detail/detail"
  ],
  "window": {
    "navigationBarTitleText": "示例小程序",
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#f5f5f5"
  },
  "tabBar": {
    "list": [
      { "pagePath": "pages/index/index", "text": "首页" },
      { "pagePath": "pages/mine/mine", "text": "我的" }
    ]
  },
  "style": "v2",
  "sitemapLocation": "sitemap.json"
}

• pages：第一项即启动页，页面路径必须与实际文件对应，否则编译直接报错。
• window：全局导航栏与背景色，页面级配置可覆盖。
• tabBar：最多 5 个、最少 2 个，图标路径必须是本地文件，且大小控制在 40KB 以内。
• style：v2 表示启用新版组件样式，新项目建议开启。
• permission / requiredPrivateInfos：涉及位置、相册等能力时需在此声明，未声明会在真机调用失败。

三、分包与体积配置

主包体积限制是硬约束，业务一多就必须分包。配置方式是在 app.json 中增加 subPackages：

{
  "subPackages": [
    {
      "root": "packageA",
      "pages": ["pages/list/list"]
    }
  ],
  "preloadRule": {
    "pages/index/index": {
      "network": "all",
      "packages": ["packageA"]
    }
  }
}

分包目录下的页面路径要写成相对 root 的形式，这一点容易写错。preloadRule 用于在进入指定页面时预下载分包，能明显改善跳转体验，但要注意单个分包预下载有体积上限，不要一次性预载全部分包。

四、云开发相关配置

如果使用云开发，需要关注三处配置：

• project.config.json 中的 cloudfunctionRoot 指向云函数目录。
• 小程序端初始化时指定环境 ID，建议通过常量统一管理，避免测试环境与生产环境混用。
• 云函数目录下的 package.json 依赖版本要锁定，云端安装依赖时不会读取本地 node_modules。

// app.js
App({
  onLaunch() {
    if (!wx.cloud) {
      console.error('请使用 2.2.3 及以上基础库')
      return
    }
    wx.cloud.init({
      env: 'prod-xxxxxx',
      traceUser: true
    })
  }
})

五、发布前的配置检查

提审前建议逐项过一遍：

1. 基础库最低版本是否与使用的 API 匹配，在后台「设置-基本设置」中确认。
2. 服务器域名是否已在后台配置，包括 request、uploadFile、downloadFile、socket 四类，且必须是 HTTPS。
3. 隐私协议与用户信息相关接口是否已按平台要求声明。
4. 体验版是否已在真机完整走通主流程，尤其是分包页面和授权流程。
5. 版本号与项目备注是否填写，便于后续回滚定位。

配置本身不产生业务价值，但它决定了业务代码能否被正确加载、被平台放行。把配置当成项目骨架的一部分来维护，比事后补救省力得多。

对于独立开发者来说，建议把上述配置整理成一份项目模板，新项目直接复用，能省下不少重复劳动。