微信小程序全局配置与页面配置：app.json、页面 JSON 覆盖规则
微信小程序全局配置与页面配置看起来都只是 JSON，真正容易出错的地方却是“配置写在哪里、最终由谁生效”。本次用一个原生小程序项目核对 app.json、pages/home/index.json 和 pages/profile/index.json：全局 window 提供默认值，页面 JSON 只覆盖当前页面的同名项；pages、tabBar 等应用结构仍由 app.json 管理。
先建立一个判断顺序：结构、默认值、页面覆盖
排查配置问题时，不要先在整个项目里搜索某个颜色或标题。先判断它属于哪一层，再看是否存在页面级覆盖。这个顺序能避开大多数“改了 app.json 但某个页面没有变化”的误判。
| 配置位置 | 主要职责 | 作用范围 |
|---|---|---|
app.json 顶层 | pages、tabBar、subPackages、preloadRule | 整个小程序的结构与能力声明 |
app.json 的 window | 导航栏、背景、下拉刷新等默认表现 | 未被页面覆盖的页面 |
页面对应的 .json | 标题、导航栏颜色、滚动及当前页组件声明 | 只影响当前页面 |
如果还不熟悉这些文件分别放在哪里，可以先看微信小程序项目目录结构。这里重点讨论配置如何合并，而不是重复解释目录职责。
app.json 的 pages 决定页面清单和默认首页
官方文档把 pages 列为全局配置的必填项。路径不写文件扩展名，框架会按同一路径寻找页面的 JSON、JavaScript、WXML 和 WXSS 文件。没有单独设置 entryPagePath 时，pages 第一项就是默认启动页。
{
"pages": [
"pages/home/index",
"pages/profile/index"
]
}新增主包页面只创建四个页面文件还不够，还要把路径写进 pages。分包页面则声明在对应的 subPackages[].pages 中，不要同时塞进主包 pages。分包结构和预下载规则可结合微信小程序分包与包体积优化继续核对。
window 是全局默认值，不是不可修改的最终值
app.json 的 window 适合放所有页面都希望继承的默认表现。例如统一导航栏背景、标题颜色和页面背景，不必在每个页面重复一遍。
{
"window": {
"navigationBarTitleText": "分包示例",
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black",
"backgroundColor": "#f5f7fa"
}
}这段配置的含义是提供默认值。只要某个页面没有写同名配置，就会沿用这里的值。适合全局启用的能力才放进 window；例如不是每个页面都需要下拉刷新时，就不应为了省一行配置而全局开启。
页面 JSON 如何覆盖 app.json
页面配置写在页面同名的 .json 文件中。官方规则很明确：当前页面的同名配置会覆盖 app.json；原本属于全局 window 的样式项，在页面 JSON 里直接写属性名，不需要再套一层 window。
{
"navigationBarTitleText": "分包演示"
}在本次项目中，首页只覆盖 navigationBarTitleText。合并后的有效结果是：标题变为“分包演示”，导航栏背景仍继承全局的 #ffffff，文字颜色仍为 black。另一个页面可以写自己的标题，同时继续继承相同的背景和文字颜色。
| 配置项 | 全局值 | 首页页面值 | 首页最终值 |
|---|---|---|---|
navigationBarTitleText | 分包示例 | 分包演示 | 分包演示 |
navigationBarBackgroundColor | #ffffff | 未设置 | #ffffff |
navigationBarTextStyle | black | 未设置 | black |
页面覆盖不是深度复制整份 app.json，也不是把全局字段全部清空。更实用的理解是：只对页面配置文档允许的字段，用当前页的同名值替换全局默认值。
哪些配置不能随意搬到页面 JSON
pages、entryPagePath、tabBar和分包结构属于应用级配置，仍放在app.json。disableScroll只在页面配置中有效，写进app.json不会得到预期结果。usingComponents可以全局声明，也可以只在页面声明；低使用率组件放到页面更利于控制依赖和主包体积。- 并非
app.json的所有字段都支持页面覆盖，判断依据应是官方“页面配置”列表。
这里还有一个常见性能误区：把只在一两个页面使用的组件放进全局 usingComponents。官方文档提醒，全局组件会被视为所有页面的依赖，可能影响启动和按需注入效果。配置能工作，不等于放置位置合理。
tabBar 配置最常见的三个检查点
{
"tabBar": {
"color": "#687076",
"selectedColor": "#07c160",
"backgroundColor": "#ffffff",
"list": [
{ "pagePath": "pages/home/index", "text": "首页" },
{ "pagePath": "pages/profile/index", "text": "说明" }
]
}
}list至少 2 项、最多 5 项。- 每个
pagePath必须已经在主包pages中声明。 - 路径不以斜杠开头，也不写文件后缀；大小写要与实际目录一致。
如果开发者工具在导入阶段就出现项目身份或编译问题，先回到账号、AppID 与开发者工具配置排除项目本身的门槛，再继续判断 JSON。
本次原生项目验证结果
本次使用已经在微信开发者工具 Stable 2.02.2608060 中运行过的原生项目做静态复核，并用脚本重新解析项目内 9 个 JSON 文件。检查结果全部通过：
pages/home/index是未设置entryPagePath时的默认首页。- 两个
tabBar.pagePath都存在于主包pages。 - 首页和说明页分别覆盖导航栏标题。
- 两个页面都继续继承全局导航栏背景色和文字颜色。
- 项目内 JSON 均能被严格解析，没有注释、尾逗号或语法错误。
因此，遇到“只有某个页面标题不对”时，应先打开该页面的 JSON；遇到“底部导航不显示”时，应先回到 app.json 核对 pages 和 tabBar。先按作用域定位，再改值，比反复清缓存和重新编译更容易得到可解释的结果。
官方资料：微信开放文档《全局配置》、微信开放文档《页面配置》（访问日期：2026-08-28；实测工具：Stable 2.02.2608060；项目配置使用基础库 latest，相关最低版本以官方字段表为准）。
