怎么创建app.json

怎么创建app.json——小程序配置文件全解析

在小程序开发中,app.json 是一个至关重要的核心文件，它就像小程序的“配置说明书”，负责定义全局的页面路径、窗口样式、 tabBar 导航、网络请求域名等关键信息，直接影响小程序的结构、外观和功能，无论是微信小程序、支付宝小程序还是百度小程序，app.json 都是必不可少的配置入口，本文将手把手教你如何创建 app.json，并详解其核心配置项，助你快速小程序的全局配置技巧。

创建 app.json：从零开始的配置第一步

理解 app.json 的作用

app.json 是小程序的全局配置文件，位于项目根目录下（与 app.js、app.wxss 同级），它以 JSON 格式编写，用于统一管理小程序的全局设置，包括：

页面路径：声明小程序包含的所有页面，决定页面路由跳转的合法性；
窗口样式：定义小程序的导航栏、背景色、下拉刷新等全局外观；
导航栏配置：设置顶部导航栏的标题、颜色、按钮等；
TabBar：配置底部标签栏的样式、页面跳转逻辑；
网络与调试：声明允许请求的域名、开启调试模式等。

创建 app.json 的步骤

（1）新建文件

在小程序项目根目录下,新建一个名为 app.json 的文件（注意文件名必须小写，且扩展名为 .json）。

（2）编写基本 JSON 结构

app.json 必须符合 JSON 语法（如双引号、逗号分隔、无注释等），创建后，先填入一个最基本的结构，包含最核心的 pages 字段（声明页面路径）：

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

（3）验证 JSON 格式

保存文件后,开发工具（如微信开发者工具）会自动校验 JSON 格式，如果格式错误，控制台会提示错误信息（如缺少逗号、引号不匹配等），需及时修正。

app.json 核心配置项详解

pages：声明所有页面路径

pages 是 app.json 中必须存在的字段，用于声明小程序包含的所有页面路径，它是一个字符串数组，每个元素代表一个页面的相对路径（从项目根目录算起，无需扩展名）。

语法规则：

"pages": [
  "页面路径1",
  "页面路径2",
  "..."
]

示例说明：

假设小程序包含首页、个人中心、设置页三个页面，且页面文件存放在 pages 目录下，pages 字段可配置为：

"pages": [
  "pages/home/index",  // 首页
  "pages/profile/index", // 个人中心
  "pages/settings/index" // 设置页
]

注意事项：

路径顺序：数组的第一个路径是小程序的“首页”（即启动时加载的页面）；
动态添加页面：新增页面时，需手动在 pages 数组末尾添加路径（开发工具可自动提示，但建议手动确认）；
路径规范：路径使用分隔，无需以开头，无需写 .js、.wxml、.wxss 等扩展名。

window：全局窗口样式配置

window 字段用于定义小程序的全局窗口外观，包括导航栏、背景色、下拉刷新等，它是一个对象，包含多个子配置项。

常用配置项：

配置项	类型	默认值	说明
`navigationBarTitleText`	string	无	文字（如“我的小程序”）
`navigationBarBackgroundColor`	string	`#000000`	导航栏背景色（支持十六进制颜色码，如 `#FFFFFF` 为白色）
`navigationBarTextStyle`	string	`white`	颜色（可选 `white` 或 `black`，取决于背景色）
`backgroundColor`	string	`#FFFFFF`	窗口背景色（页面内容区域的背景色）
`backgroundTextStyle`	string	`dark`	下拉 loading 的样式（可选 `dark` 或 `light`）
`enablePullDownRefresh`	boolean	`false`	是否开启全局下拉刷新（开启后，所有页面默认支持下拉刷新）
`onReachBottomDistance`	number	50	页面上拉触底时，距离底部多少距离触发 `onReachBottom` 事件（单位：px）

示例配置：

"window": {
  "navigationBarTitleText": "我的小程序",
  "navigationBarBackgroundColor": "#07C160",  // 微信绿
  "navigationBarTextStyle": "white",          // 白色标题
  "backgroundColor": "#F7F7F7",              // 浅灰背景
  "enablePullDownRefresh": true,              // 开启下拉刷新
  "backgroundTextStyle": "dark"               // 下拉 loading 为深色
}

tabBar：底部标签栏配置

如果小程序需要底部导航栏（如微信、淘宝等常见的“首页”“分类”“购物车”），需通过 tabBar 字段配置，它是一个对象，包含多个子配置项，仅当配置存在时才会显示标签栏。

常用配置项：

配置项	类型	说明
`color`	string	标签栏默认文字颜色（十六进制颜色码）
`selectedColor`	string	标签栏选中文字颜色（如当前页面在“首页”，则“首页”文字为此颜色）
`backgroundColor`	string	标签栏背景色
`borderStyle`	string	标签栏上边框颜色（可选 `black` 或 `white`）
`list`	array	标签栏数组，每个元素是一个对象，定义单个标签的配置（如页面路径、图标、标题）

`list` 数组子项配置：

配置项	类型	说明
`pagePath`	string	标签对应的页面路径（必须在 `pages` 中声明）
`text`	string	文字（如“首页”“我的”）
`iconPath`	string	未选中时的图标路径（建议尺寸 81px×81px，支持 PNG/JPG）
`selectedIconPath`	string	选中时的图标路径（尺寸与 `iconPath` 一致，建议用不同颜色区分选中状态）

示例配置：

假设小程序有“首页”“分类”“我的”三个标签，tabBar 可配置为：

"tabBar": {
  "color": "#999999",           // 默认文字颜色
  "selectedColor": "#07C160",   // 选中文字颜色
  "backgroundColor": "#FFFFFF", // 背景色
  "borderStyle": "black",       // 上边框黑色
  "list": [
    {
      "pagePath": "pages/home/index",
      "text": "首页",
      "iconPath": "images/home.png",
      "selectedIconPath": "images/home-selected.png"
    },
    {
      "pagePath": "pages/category/index",
      "text": "分类",
      "iconPath": "images/category.png",
      "selectedIconPath": "images/category-selected.png"
    },
    {
      "pagePath": "pages/profile/index",
      "text": "我的",
      "iconPath": "images/profile.png",
      "selectedIconPath": "images/profile-selected.png"
    }
  ]
}

style：全局样式配置（可选）

style 字段用于配置小程序的全局样式，如 navigationBarTextStyle、navigationBarTitleText 等（部分平台支持），但多数配置已被 window 字段覆盖，style 在实际开发中较少使用，可根据平台文档选择性配置。

sitemapLocation：配置 sitemap.json 路径（可选）

sitemapLocation 用于声明 sitemap.json 文件的位置（默认为项目根目录下的 sitemap.json）。sitemap.json 用于配置小程序及其页面是否允许被微信索引（影响搜索结果），默认值为：

"sitemapLocation": "sitemap.json"

完整 app.json 示例

结合以上配置项,一个完整的 app.json 文件如下：

正文

怎么创建app.json