微信小程序全局配置 app.json 详解

1. 引言

在微信小程序项目中，app.json是整个小程序的全局配置文件，可以理解为小程序的“总入口”和“项目大脑”。

它负责定义：

• 小程序有哪些页面；

• 哪个页面作为首页；

• 小程序窗口如何显示；

• 底部 Tab 栏如何布局；

• 网络请求超时时间；

• 权限声明；

• 分包加载规则等。

简单来说：

app.json决定了小程序的整体骨架，而页面自身的.json文件负责控制单个页面的细节。

例如，一个商城类小程序：

商城小程序 │ ├── 首页 │ ├── 商品列表 │ ├── 购物车 │ ├── 我的 │ └── 设置

这些页面在哪里、如何展示、底部导航如何切换，都需要通过app.json来定义。

app.json 文件特点

app.json本质是一个JSON 格式文件，因此必须严格遵守 JSON 规范。

例如：

✅ 正确：

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

❌ 错误：

{ pages: [ 'pages/index/index' ] }

原因：

• JSON 的 key 必须使用双引号；

• 字符串必须使用双引号；

• 不能写注释；

• 不能存在多余逗号。

例如：

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

最后一个逗号也是错误的。

注意：下面文章中的 JSON 示例为了方便解释，会使用//注释，但实际开发中app.json不能写注释。

2. 核心配置详解

2.1 pages（页面路径）

作用

pages用于声明小程序所有页面路径。

它是app.json中最重要的配置之一。

例如：

{ "pages": [ "pages/index/index", "pages/shop/shop", "pages/cart/cart", "pages/user/user" ] }

表示小程序包含：

pages │ ├── index │ └── index.js │ ├── shop │ └── shop.js │ ├── cart │ └── cart.js │ └── user └── user.js

首页规则

pages数组中的第一项就是小程序启动首页。

例如：

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

启动后首先进入：

pages/login/login

而不是：

pages/index/index

所以开发过程中经常通过调整第一项改变启动页面。

路径注意事项

1. 不需要写文件后缀

正确：

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

不要：

{ "pages": [ "pages/index/index.wxml" ] }

微信小程序会自动寻找：

index.js index.json index.wxml index.wxss

2. 使用相对项目根目录路径

小程序路径都是相对于项目根目录。

例如：

项目：

miniprogram │ ├── app.json │ └── pages └── index └── index.js

配置：

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

而不是：