一文读懂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 覆盖)。
常用配置项
| 配置项 | 类型 | 默认值 | 作用 |
|---|---|---|---|
navigationBarTitleText |
String | 无 | 文本 |
navigationBarBackgroundColor |
HexColor | #000000 |
导航栏背景色(需支持的颜色值,如 #ffffff) |
navigationBarTextStyle |
String | white |
颜色(white/black) |
backgroundColor |
HexColor | #ffffff |
窗口背景色(页面内容区域背景色) |
backgroundTextStyle |
String | dark |
下拉 loading 样式(dark/light) |
enablePullDownRefresh |
Boolean | false |
是否全局开启下拉刷新 |
实例配置
{
"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(选中图标)四个字段。
配置项详解
| 配置项 | 类型 | 必填 | 说明 |
|---|---|---|---|
list |
Array | 是 | 标签栏配置数组,每个元素为一个标签对象 |
color |
HexColor | 否 | 标签文字默认颜色 |
selectedColor |
HexColor | 否 | 标签文字选中颜色 |
backgroundColor |
HexColor | 否 | 标签栏背景色 |
borderStyle |
String | 否 | 标签栏上边框颜色(black/white) |
实例配置
假设项目有首页、分类、购物车、个人中心四个核心页面,配置 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
作用:开启后,首次启动小程序时仅下载主包,进入分包页面时再加载分包内容,提升启动速度(需



还没有评论,来说两句吧...