微信开发者工具的app.json怎么配置

微信开发者工具中app.json配置全指南：从小程序页面到全局设置的核心配置

在微信小程序开发中,app.json 是整个小程序的“全局配置文件”，它就像小程序的“说明书”，定义了小程序的页面路径、窗口样式、导航栏行为、底部标签栏等核心全局属性，无论是初学者还是有经验的开发者，准确理解并配置 app.json 都是开发小程序的基础，本文将详细讲解 app.json 的结构、常用配置项及实际应用场景，帮你快速小程序的全局配置技巧。

app.json 的基本结构与作用

app.json 是小程序根目录下的必需文件（与 app.js、app.wxss 同级），采用 JSON 格式编写，它的核心作用是统一管理小程序的全局配置，避免在每个页面中重复设置通用属性，微信小程序启动时，会优先读取 app.json 中的配置，从而确定小程序的“骨架”。

一个典型的 app.json 结构如下：

{
  "pages": [
    "pages/index/index",
    "pages/logs/logs"
  ],
  "window": {
    "navigationBarTitleText": "我的小程序",
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#3cc51f",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "images/home.png",
        "selectedIconPath": "images/home-active.png"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "日志",
        "iconPath": "images/logs.png",
        "selectedIconPath": "images/logs-active.png"
      }
    ]
  },
  "style": "v2",
  "sitemapLocation": "sitemap.json"
}

核心配置项详解

pages：配置小程序所有页面路径

pages 是 app.json 中最重要的配置项之一，它是一个字符串数组，定义了小程序中所有页面的路径（相对于小程序根目录）。

• 配置规则：

  • 数组中的每一项代表一个页面,格式为 "页面文件夹名/页面文件名"（"pages/index/index"，对应 pages/index/index.wxml、pages/index/index.js 等文件）。
  • 数组的第一个页面是小程序的首页（启动时加载的页面）。
  • 新增页面时,只需在数组中添加路径即可，微信开发者工具会自动创建对应的页面文件（也可手动创建后添加路径）。

• 示例：

  "pages": [
    "pages/index/index",      // 首页
    "pages/user/user",        // 用户页
    "pages/settings/settings" // 设置页
  ]

• 注意事项：

  • 删除页面时,需同时从 pages 数组中移除对应路径，否则会导致加载失败。
  • 如果页面较多,可通过调整数组顺序管理页面层级。

window：配置小程序窗口样式

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

• 常用配置项：
  | 配置项 | 类型 | 默认值 | 说明 |
  |--------|------|--------|------|
  | navigationBarTitleText | String | - | 导航栏标题文本（必填，除非使用 navigationStyle: "custom"） |
  | navigationBarBackgroundColor | String | "#ffffff" | 导航栏背景色，支持十六进制颜色（如 #ff0000） |
  | navigationBarTextStyle | String | "white" | 导航栏标题颜色，可选 "white" 或 "black" |
  | backgroundColor | String | "#ffffff" | 窗口背景色 |
  | backgroundTextStyle | String | "dark" | 下拉 loading 的样式，可选 "dark" 或 "light" |
  | enablePullDownRefresh | Boolean | false | 是否开启全局下拉刷新（开启后，所有页面支持下拉刷新） |
  | navigationStyle | String | "default" | 导航栏样式，"default" 为默认导航栏，"custom" 为自定义导航栏（隐藏原生导航栏） |

• 示例：

  "window": {
    "navigationBarTitleText": "我的小程序",
    "navigationBarBackgroundColor": "#ff6b6b",
    "navigationBarTextStyle": "white",
    "enablePullDownRefresh": true,
    "backgroundTextStyle": "light"
  }

• 注意事项：

  • navigationStyle: "custom" 时，需自行通过组件实现导航栏功能（如 <view class="custom-nav">...</view>）。
  • 开启下拉刷新后,页面需在 onPullDownRefresh 生命周期中处理刷新逻辑。

tabBar：配置底部标签栏

tabBar 是小程序底部常驻的标签栏，用于快速切换核心页面（最多5个，最少2个），只有配置了 tabBar，小程序才会显示底部导航。

• 常用配置项：
  | 配置项 | 类型 | 说明 |
  |--------|------|------|
  | color | String | 未选中标签的文本和图标颜色 |
  | selectedColor | String | 选中标签的文本和图标颜色 |
  | backgroundColor | String | 标签栏背景色 |
  | borderStyle | String | 标签栏上边框颜色，可选 "black" 或 "white" |
  | list | Array | 标签栏配置数组，每个元素是一个标签对象 |

• list 数组中的标签对象配置：
  | 配置项 | 类型 | 说明 |
  |--------|------|------|
  | pagePath | String | 标签对应的页面路径（必须在 pages 中定义） |
  | text | String | 标签标题（最多4个字符） |
  | iconPath | String | 未选中时的图标路径（建议尺寸 81px×81px，支持 PNG、JPG） |
  | selectedIconPath | String | 选中时的图标路径（建议尺寸 81px×81px） |

• 示例：

  "tabBar": {
    "color": "#999999",
    "selectedColor": "#ff6b6b",
    "backgroundColor": "#f8f8f8",
    "borderStyle": "black",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "images/tab-home.png",
        "selectedIconPath": "images/tab-home-active.png"
      },
      {
        "pagePath": "pages/user/user",
        "text": "我的",
        "iconPath": "images/tab-user.png",
        "selectedIconPath": "images/tab-user-active.png"
      }
    ]
  }

• 注意事项：

  • list 中的 pagePath 必须在 pages 中存在，否则标签栏无法显示。
  • 图标需提前放入项目目录,路径建议使用相对路径（从项目根目录开始）。

style：配置小程序基础样式版本

style 用于指定小程序的基础样式版本，目前支持 "v1" 和 "v2"（默认为 "v2"）。

• "v2" 版本的特点：

  • 启用新组件样式（如 <button> 默认样式更简洁，去掉边框和背景）。
  • 优化布局性能,支持更灵活的 CSS 属性（如 flex 布局增强）。
  • 部分旧版样式（如 border-radius 对 <button> 的兼容性）有变化。

• 示例：

  "style": "v2"

• 注意事项：

  • 如果项目依赖旧版样式（如 <button> 需要默认边框），可设置为 "v1"，但建议逐步迁移到 "v2" 以获得更好的性能。

sitemapLocation：配置小程序索引文件路径

sitemapLocation 指定小程序 sitemap.json 文件的路径（默认为 "sitemap.json"）。sitemap.json 用于配置小程序页面是否允许被微信索引（影响搜索结果）。

• 示例：

  "sitemapLocation": "sitemap.json"

• sitemap.json 示例：

  {
    "desc": "关于本文件的更多信息，请参考文档 https://developers.weixin.qq.com/miniprogram/dev/framework/sitemap