app.json如何使用

一文读懂app.json的用法

在小程序开发中，app.json 是整个应用的“配置总管”，它虽然不包含业务逻辑，却控制着小程序的全局行为、页面路由、窗口样式等核心功能，无论是新手入门还是老项目维护，理解 app.json 的使用都是高效开发的关键，本文将从基础结构到核心配置项，结合实例带你彻底 app.json 的用法。

初识app.json：小程序的“全局说明书”

app.json 是小程序的全局配置文件，位于项目根目录下，与 app.js、app.wxss 共同构成小程序的“全局层”，它采用 JSON 格式编写，无需编译，小程序启动时会优先加载其中的配置，从而决定应用的“长相”和“行为规则”。

文件位置与基本结构

app.json 必须位于项目根目录，文件名固定为 app.json（不可修改），其基本结构是一个 JSON 对象，通过不同键值对定义全局配置，

{
  "pages": [
    "pages/index/index",
    "pages/logs/logs"
  ],
  "window": {
    "navigationBarTitleText": "我的小程序"
  },
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页"
      }
    ]
  }
}

为什么需要app.json？

与手动编写页面跳转逻辑、统一窗口样式不同，app.json 通过声明式配置实现了“全局统一管理”：

• 简化开发：无需在每个页面重复配置导航栏、tabBar 等公共样式；
• 行为规范：定义页面路由规则，避免跳转路径错误；
• 体验一致：统一全局视觉风格，保障用户体验连贯性。

核心配置项详解：从页面到交互的全局控制

app.json 的配置项虽不多，但每个都至关重要,下面逐一拆解常用配置的用法与场景。

pages：页面路由配置（必填）

pages 是 app.json 中最核心的配置之一，用于声明小程序所有页面的路径，小程序会根据 pages 数组的顺序，自动将第一个页面设为“首页”，同时生成页面路由规则。

配置格式

pages 是一个字符串数组，每个元素代表一个页面的路径，格式为 "页面文件夹/页面文件名"（.json、.js、.wxml、.wxss 后缀无需填写）。

{
  "pages": [
    "pages/index/index",      // 首页
    "pages/category/index",   // 分类页
    "pages/cart/index",       // 购物车页
    "pages/my/index"          // 个人中心页
  ]
}

注意事项

• 路径必须真实存在：数组中的每个路径对应项目 pages 目录下的文件夹，且文件夹中需包含 .js、.wxml 等必要文件（否则会报错）；
• 顺序决定首页：数组的第一个页面即为小程序启动后的首页，如需更换首页，只需调整数组顺序即可；
• 动态添加页面：若需新增页面（如通过用户操作跳转的临时页），需手动在 pages 数组末尾添加路径，否则无法访问。

window：全局窗口样式配置（可选）

window 用于配置小程序的全局窗口表现，包括导航栏、标题、背景色等，所有页面默认继承此配置（单个页面可通过 page.json 覆盖）。

常用配置项

实例配置

{
  "window": {
    "navigationBarTitleText": "电商商城",
    "navigationBarBackgroundColor": "#ff6b6b",
    "navigationBarTextStyle": "white",
    "backgroundColor": "#f8f9fa",
    "backgroundTextStyle": "dark",
    "enablePullDownRefresh": true
  }
}

效果说明

• 导航栏背景色为红色（#ff6b6b为白色“电商商城”； 区域背景色为浅灰（#f8f9fa）；
• 全局支持下拉刷新，loading 样式为深色。

tabBar：底部标签栏配置（可选）

tabBar 是小程序底部常用的导航组件，用于快速切换核心页面（如首页、分类、购物车等），只有当 tabBar 配置存在时，底部才会显示标签栏。

核心配置规则

• tabBar 最多配置 5 个标签，最少 2 个；
• 每个标签需包含 pagePath（页面路径）、text（标签名）、iconPath（未选中图标）、selectedIconPath（选中图标）四个字段。

配置项详解

实例配置

假设项目有首页、分类、购物车、个人中心四个核心页面，配置 tabBar 如下：

{
  "tabBar": {
    "color": "#999999",
    "selectedColor": "#ff6b6b",
    "backgroundColor": "#ffffff",
    "borderStyle": "black",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "images/home.png",
        "selectedIconPath": "images/home-active.png"
      },
      {
        "pagePath": "pages/category/index",
        "text": "分类",
        "iconPath": "images/category.png",
        "selectedIconPath": "images/category-active.png"
      },
      {
        "pagePath": "pages/cart/index",
        "text": "购物车",
        "iconPath": "images/cart.png",
        "selectedIconPath": "images/cart-active.png"
      },
      {
        "pagePath": "pages/my/index",
        "text": "我的",
        "iconPath": "images/my.png",
        "selectedIconPath": "images/my-active.png"
      }
    ]
  }
}

注意事项

• iconPath 和 selectedIconPath 必须是本地图片路径，建议尺寸 81px×81px，格式支持 PNG、JPG、SVG；
• pagePath 必须已在 pages 中声明，否则标签栏无法显示；
• 修改 tabBar 配置后，需重新编译小程序才能生效。

其他全局配置项

除了上述核心配置，app.json 还包含一些实用全局配置，可根据需求灵活使用：

- debug：调试模式

类型：Boolean，默认值：false
作用：开启后，控制台会打印更详细的日志（如页面注册信息、事件触发日志），适合开发调试，上线前需关闭。

{
  "debug": true
}

- networkTimeout：网络请求超时

类型：Object，默认值：无
作用：配置各类网络请求的超时时间（单位：毫秒），避免请求卡死。

{
  "networkTimeout": {
    "request": 10000,    // wx.request 超时时间
    "downloadFile": 10000 // wx.downloadFile 超时时间
  }
}

- lazyCodeLoading：分包按需加载

类型：Boolean，默认值：false
作用：开启后，首次启动小程序时仅下载主包，进入分包页面时再加载分包内容，提升启动速度（需