如何制作app.json

如何制作app.json：微信小程序配置文件的完整指南

在微信小程序开发中，app.json 是一个至关重要的核心文件，它作为小程序的“全局配置清单”，定义了整个小程序的页面路径、窗口样式、 tabBar 导航、网络请求超时等全局行为，直接影响小程序的基础框架和用户体验，本文将从文件定位、核心配置项、常见场景实践及注意事项四个方面，详细讲解如何制作 app.json。

app.json 的定位与基本规范

app.json 是小程序的全局配置文件，必须存放在项目根目录下（与 app.js、app.wxss、project.config.json 同级），它是一个 JSON 格式的文件，需严格遵循 JSON 语法规范：

• 使用双引号 包裹字符串（单引号会报错）；
• 属性名和属性值之间用冒号 分隔；
• 多个属性之间用逗号 分隔（最后一个属性后无逗号）；
• 不能有注释（JSON 标准不支持，可通过 或 在开发工具中临时调试，但实际运行需移除）。

app.json 的核心配置项详解

app.json 包含多个全局配置节点，每个节点对应不同的功能模块,以下是常用配置项的具体说明及示例。

pages：页面路由配置

pages 是 app.json 中最基础的配置，用于定义小程序所有页面的路径，它是一个字符串数组，数组的每一项代表一个页面的路径（以 分隔，从项目根目录开始），数组的第一个元素表示小程序的首页（打开小程序时首先加载的页面）。

配置规范：

• 必须配置，且至少包含一个页面路径；
• 路径后缀可省略 .wxml、.wxss、.js、.json，小程序会自动补全；
• 新增页面时，需手动将路径添加到 pages 数组末尾（微信开发者工具可通过“新建页面”功能自动添加）。

示例：

{
  "pages": [
    "pages/index/index",        // 首页
    "pages/user/profile",       // 用户页
    "pages/order/list",         // 订单列表页
    "pages/detail/detail"       // 详情页
  ]
}

window：窗口外观配置

window 用于定义小程序所有页面的默认窗口表现，包括标题栏、背景色、下拉刷新等，它是一个对象，包含多个子属性。

常用子属性：
| 属性名 | 类型 | 默认值 | 说明 | |----------------|---------|--------------|----------------------------------------------------------------------| | navigationBarTitleText | string | 无 | 窗口标题栏文字（首页标题可直接在此设置，其他页面可在页面 .json 中覆盖） | | navigationBarBackgroundColor | string | #ffffff | 标题栏背景色，支持十六进制颜色码（如 #000000） | | navigationBarTextStyle | string | black | 标题栏文字颜色，可选 black（黑）或 white（白） | | backgroundColor | string | #ffffff | 窗口背景色（页面内容区域背景色） | | backgroundTextStyle | string | dark | 下拉 loading 的样式，可选 dark（深色）或 light（浅色） | | enablePullDownRefresh | boolean | false | 是否开启全局下拉刷新（若部分页面需单独控制，可在页面 .json 中配置） | | onReachBottomDistance | number | 50 | 页面上拉触底时，距离底部多远时触发 onReachBottom 事件（单位：px） |

示例：

{
  "window": {
    "navigationBarTitleText": "我的小程序",      // 所有页面默认标题
    "navigationBarBackgroundColor": "#ff6b6b",  // 标题栏背景色（红色）
    "navigationBarTextStyle": "white",         // 标题栏文字白色
    "backgroundColor": "#f8f9fa",              // 页面背景浅灰色
    "enablePullDownRefresh": true,             // 开启全局下拉刷新
    "onReachBottomDistance": 100               // 上拉触底触发距离为100px
  }
}

tabBar：底部导航栏配置

tabBar 用于定义小程序底部或顶部导航栏，实现核心页面的快速切换，它是一个对象，仅在多页面场景下需要配置（单页面小程序无需配置）。

配置规范：

• 最多支持 5 个 tab，最少 2 个；
• 每个 tab 对应一个 list 数组项，包含以下属性：

示例：

{
  "tabBar": {
    "color": "#999999",              // 未选中时文字灰色
    "selectedColor": "#ff6b6b",      // 选中时文字红色
    "backgroundColor": "#ffffff",    // tab 背景白色
    "list": [
      {
        "pagePath": "pages/index/index",  // 首页
        "text": "首页",
        "iconPath": "images/home.png",    // 未选中图标
        "selectedIconPath": "images/home-active.png"  // 选中图标
      },
      {
        "pagePath": "pages/user/profile", // 用户页
        "text": "我的",
        "iconPath": "images/user.png",
        "selectedIconPath": "images/user-active.png"
      }
    ]
  }
}

style：全局样式配置

style 用于配置小程序的全局样式设置，如 navigationStyle（自定义导航栏）等，微信小程序基础库 2.10.1 及以上版本支持。

常用子属性：
| 属性名 | 类型 | 默认值 | 说明 | |--------------------|---------|----------|----------------------------------------------------------------------| | navigationBarTextStyle | string | black | 全局导航栏文字颜色（覆盖 window.navigationBarTextStyle） | | navigationBarTitleText | string | 无 | 全局导航栏标题（覆盖 window.navigationBarTitleText） | | navigationBarBackgroundColor | string | #ffffff | 全局导航栏背景色（覆盖 window.navigationBarBackgroundColor） | | backgroundColor | string | #ffffff | 全局窗口背景色（覆盖 window.backgroundColor） |

示例：

{
  "style": {
    "navigationBarTextStyle": "white",
    "navigationBarBackgroundColor": "#3a3a3a"
  }
}

debug：调试模式配置

debug 用于控制是否开启调试模式，开启后，小程序控制台会打印更详细的日志（如 app.json 解析错误、网络请求详情等），便于开发调试。

配置规范：

• 类型：boolean；
• 默认值：false（生产环境务必关闭）。

示例：

{
  "debug": true  // 开启调试模式（开发时使用）
}

sitemapLocation：站点地图配置

sitemapLocation 用于指定 sitemap.json 文件的路径（默认为项目根目录下的 sitemap.json）。sitemap.json 用于配置小程序及其页面是否允许被微信索引，影响小程序的搜索展示。

配置规范：

• 类型：string；
• 默认值："sitemap.json"。

示例：

{
  "sitemapLocation": "custom-sitemap.json"  // 自定义站点地图路径
}

常见场景实践示例

场景1：基础电商小程序配置

包含首页、分类页、购物车、个人中心四个核心页面，底部导航栏，自定义标题栏。