怎么创建app.json

如何创建 app.json：微信小程序的全局配置指南

在微信小程序开发中，app.json 是一个至关重要的文件，它作为小程序的“全局配置说明书”，定义了整个小程序的页面路径、窗口样式、tab 栏、网络请求域名等核心行为和表现，无论是新手入门还是项目迭代，正确创建和配置 app.json 都是开发的第一步，也是确保小程序稳定运行的基础，本文将手把手教你如何创建 app.json,并详解其核心配置项。

什么是 app.json？为什么它必不可少？

app.json 是小程序的全局配置文件，位于项目根目录下（与 app.js、app.wxss 同级），它采用 JSON 格式，负责管理小程序的全局页面路由、窗口表现、tab 栏导航、网络请求权限等关键配置。app.json 决定了小程序的“骨架”和“基本规则”——比如有哪些页面、长什么样、底部是否有导航栏等。

微信小程序要求每个项目必须有 app.json，否则项目将无法正常运行（编译时会报错），创建 app.json 是小程序开发的第一步,也是贯穿整个开发周期的基础配置文件。

创建 app.json 的详细步骤

确认项目结构

在微信开发者工具中创建新项目后，默认会在项目根目录生成以下文件：

miniprogram/
├── app.js        // 小程序逻辑入口
├── app.json      // 全局配置文件（核心）
├── app.wxss      // 全局样式文件
└── pages/        // 页面文件夹
    └── index/    // 示例页面
        ├── index.js
        ├── index.json
        ├── index.wxml
        └── index.wxss

如果项目是手动创建（非向导生成），需确保在根目录下创建 app.json 文件（注意文件名小写，无扩展名前缀）。

编写基础 JSON 结构

app.json 必须是合法的 JSON 格式（键值对结构，双引号包裹，无注释），最基础的 app.json 至少包含 pages 字段（定义页面路径），

{
  "pages": [
    "pages/index/index",
    "pages/logs/logs"
  ]
}

说明：

pages 是一个数组，每个元素是一个字符串，表示页面的路径（从项目根目录到页面文件的相对路径，不含扩展名）。
数组的第一项 pages/index/index 是小程序的首页（即打开小程序时首先加载的页面）。

添加其他核心配置字段

除了 pages，app.json 还包含多个全局配置字段，用于控制小程序的行为和表现,以下是常用字段及示例：

（1）`window`：窗口表现配置

window 用于定义小程序主窗口的样式，包括标题、背景色、导航栏等。

{
  "pages": [...],
  "window": {
    "navigationBarBackgroundColor": "#ffffff", // 导航栏背景色，默认#000000
    "navigationBarTextStyle": "black",        // 导航栏标题颜色，仅支持 'black'/'white'
    "navigationBarTitleText": "我的小程序",    // 导航栏标题文本
    "navigationStyle": "default",             // 导航栏样式，'default'（默认）/ 'custom'（自定义）
    "backgroundColor": "#eeeeee",             // 窗口背景色，默认#ffffff
    "backgroundTextStyle": "dark",            // 下拉 loading 样式，仅支持 'dark'/'light'
    "enablePullDownRefresh": true             // 是否开启下拉刷新，默认false
  }
}

常见场景：

修改导航栏标题：navigationBarTitleText
隐藏导航栏：navigationStyle: "custom"（需自行编写导航栏组件）
开启下拉刷新：enablePullDownRefresh: true

（2）`tabBar`：底部导航栏配置

如果小程序有多个核心页面（如首页、我的、订单等），可通过 tabBar 配置底部导航栏，方便用户快速切换。

{
  "pages": [
    "pages/index/index",
    "pages/category/index",
    "pages/user/index"
  ],
  "tabBar": {
    "color": "#7A7E83",           // tab 文字默认颜色
    "selectedColor": "#3cc51f",   // tab 文字选中颜色
    "backgroundColor": "#ffffff", // tab 背景色
    "borderStyle": "black",       // tab 上边框颜色，'black'/'white'
    "list": [                     // tab 列表，至少2个，最多5个
      {
        "pagePath": "pages/index/index",  // 页面路径（必须在 pages 中定义）
        "text": "首页",                   // tab 文本
        "iconPath": "images/home.png",    // 未选中图标（路径建议放根目录或images/）
        "selectedIconPath": "images/home-active.png" // 选中图标
      },
      {
        "pagePath": "pages/user/index",
        "text": "我的",
        "iconPath": "images/user.png",
        "selectedIconPath": "images/user-active.png"
      }
    ]
  }
}

注意：

tabBar.list 中的 pagePath 必须在 pages 数组中定义过，否则无效。
图标建议尺寸：81px×81px，格式为 PNG，且透明背景效果更佳。

（3）`networkTimeout`：网络请求超时配置

networkTimeout 用于设置网络请求（如 wx.request）的超时时间，避免请求卡死导致页面无响应。

{
  "pages": [...],
  "networkTimeout": {
    "request": 10000,  // wx.request 超时时间，单位毫秒（默认60000）
    "downloadFile": 10000, // wx.downloadFile 超时时间（默认60000）
    "uploadFile": 10000,   // wx.uploadFile 超时时间（默认60000）
    "connectSocket": 10000 // wx.connectSocket 超时时间（默认60000）
  }
}

场景：对请求时效性要求高的页面（如实时数据查询），可适当缩短超时时间。

（4）`debug`：调试模式开关

debug 用于控制是否开启调试模式，开启后控制台会打印更详细的日志（如 app.json 解析错误、页面生命周期日志等）。

{
  "pages": [...],
  "debug": true  // 默认false，开发时可开启，上线后需关闭
}

（5）`sitemapLocation`：站点地图配置

sitemapLocation 指定 sitemap.json 文件的路径（用于配置小程序页面是否允许被微信索引）。

{
  "pages": [...],
  "sitemapLocation": "sitemap.json"  // 默认值，通常无需修改
}

验证配置正确性

编写完 app.json 后，需确保 JSON 格式合法（可通过微信开发者工具的“代码校验”功能检查），如果配置错误，工具会在控制台提示具体问题（如缺少逗号、引号不匹配等）。

错误示例："navigationBarTitleText": "我的小程序"（少逗号）
正确示例："navigationBarTitleText": "我的小程序",

常见问题与注意事项

`pages` 数组顺序会影响什么？

pages 数组的第一项是首页，后续项是其他页面的路由路径，新增页面时，需将路径添加到 pages 数组中（可添加到末尾，或通过拖动调整顺序）。

示例：新增一个“订单”页面（pages/order/index），需修改 app.json：

{
  "pages": [
    "pages/index/index",  // 首页不变
    "pages/order/index",  // 新增订单页面
    "pages/user/index"    // 原有“我的”页面后移
  ]
}

修改 `app.json` 后需要重启吗？

微信开发者工具支持实时热更新，修改 app.json 后无需手动重启，工具会自动检测配置变更并重新编译（部分复杂配置可能需点击“编译”按钮生效）。

`tabBar` 和 `wx.navigateTo` 冲突吗？

不会。tabBar 是全局底部导航栏，用于切换核心页面（路径必须在 pages 中定义）；wx.navigateTo 是页面跳转 API，用于非核心页面的跳转（跳转后的页面不会出现在 tabBar 中）。

示例：从“首页

正文