作为 UniApp 开发者，pages.json 绝对是你每天都会接触的核心文件——它就像 UniApp 项目的“导航地图+全局外观设置面板”，所有页面的路由、窗口样式、底部 TabBar 等关键配置，都需要在这里统一管理。

很多新手入门时，常常会因为 pages.json 配置错误，导致页面不显示、导航栏异常、TabBar 失效等问题。今天这篇教程，就从基础到进阶，手把手教你配置 pages.json，覆盖 90% 开发场景，搭配完整示例和避坑要点，看完直接上手实操！

一、先搞懂：pages.json 到底有什么用？

在 UniApp 中，pages.json 是全局配置文件，无需引入，项目启动时会自动读取。它的核心作用主要有 5 点，新手务必记牢：

• 配置页面路由：指定项目包含哪些页面，以及哪个页面是首页（启动页）；

• 设置窗口表现：控制导航栏的颜色、标题、字体，以及页面背景色、下拉刷新等；

• 定义底部 TabBar：实现原生体验的底部导航（比如首页、我的、分类等）；

• 配置全局样式：统一所有页面的基础样式，避免重复编写；

• 高级功能配置：如分包加载、页面预加载、平台特有样式适配等。

关键提醒：所有页面必须在 pages.json 中注册，否则不会被打包到项目中，跳转时会直接报错，这是新手最容易踩的第一个坑！

二、基础配置：从“默认模板”开始理解

用 HBuilder X 创建 UniApp 项目（默认模板）后，pages.json 会自动生成基础结构，我们先从最简单的默认配置入手，逐行拆解含义：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  }
}

这个默认配置虽然简单，但包含了两个最核心的节点：pages 节点和 globalStyle 节点，我们逐个拆解。

1. pages 节点（页面路由配置，核心中的核心）

pages 是一个数组，数组中的每一个对象，都对应一个页面的配置，数组的第一项就是项目的首页（启动时默认打开的页面）。

每个页面对象包含 2 个关键属性，必填且不能写错：

• path：页面路径

• 格式：pages/页面文件夹/页面文件名（无需写 .vue 或 .nvue 后缀）；

• 示例：”pages/index/index” 对应项目中 pages → index → index.vue 文件；

• 注意：支持子目录，比如 “pages/user/settings/index”（用户设置页），路径要和文件实际位置完全一致。

• style：页面单独样式

• 用于配置当前页面的专属样式，优先级高于 globalStyle（全局样式）；

• 常用配置：navigationBarTitleText（当前页面导航栏标题）、enablePullDownRefresh（是否开启下拉刷新）等；

• 示例：给首页设置红色导航栏标题，只需在 style 中添加 “navigationBarTitleText”: “我的首页”。

实操示例：新增一个“我的”页面

1. 先在 pages 文件夹下新建 my 文件夹，再新建 my.vue 文件；

2. 在 pages.json 的 pages 数组中添加配置，此时 pages 数组有两个对象，首页仍为第一个：

"pages": [
  {
    "path": "pages/index/index",
    "style": {
      "navigationBarTitleText": "首页"
    }
  },
  {
    "path": "pages/my/my",
    "style": {
      "navigationBarTitleText": "我的",
      "enablePullDownRefresh": true, // 开启下拉刷新
      "backgroundColor": "#F5F5F5" // 页面背景色（覆盖全局样式）
    }
  }
]

2. globalStyle 节点（全局样式配置，减少重复代码）

globalStyle 用于配置所有页面的统一样式，无需在每个页面的 style 中重复编写，常用配置如下（全部可直接复制使用）：

"globalStyle": {
  "navigationBarTextStyle": "black", // 导航栏标题颜色（仅支持 black/white）
  "navigationBarBackgroundColor": "#F8F8F8", // 导航栏背景色（十六进制颜色）
  "backgroundColor": "#F8F8F8", // 页面窗口背景色（下拉刷新时显示）
  "enablePullDownRefresh": false, // 全局是否开启下拉刷新（默认 false）
  "onReachBottomDistance": 50, // 页面上拉触底触发距离（默认 50px，用于上拉加载更多）
  "app-plus": { // App 平台特有配置（仅 App 生效，其他平台忽略）
    "background": "#efeff4" // App 页面背景色
  }
}

重点：如果某个页面需要特殊样式，可在该页面的 style 中重新配置，会自动覆盖 globalStyle 中的对应配置（比如上面“我的”页面，单独设置了 backgroundColor）。

三、高频配置：底部 TabBar 配置（最常用场景）

绝大多数 UniApp 项目（如商城、资讯、工具类），都会用到底部 TabBar 导航（比如首页、分类、购物车、我的）。TabBar 配置在 pages.json 的根节点，和 pages、globalStyle 同级。

1. TabBar 核心配置规则

• TabBar 中的页面，必须是 pages 数组中的页面；

• TabBar 最多支持 5 个 tab（最少 2 个），超过 5 个会报错；

• tab 的 pagePath 必须和 pages 数组中的 path 完全一致，否则 TabBar 不显示。

2. 完整示例（4 个 Tab，直接复制可用）

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "pages/category/category",
      "style": {
        "navigationBarTitleText": "分类"
      }
    },
    {
      "path": "pages/cart/cart",
      "style": {
        "navigationBarTitleText": "购物车"
      }
    },
    {
      "path": "pages/my/my",
      "style": {
        "navigationBarTitleText": "我的"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  },
  "tabBar": {
    "color": "#666666", // 未选中 tab 的文字颜色
    "selectedColor": "#FF6700", // 选中 tab 的文字颜色
    "backgroundColor": "#FFFFFF", // TabBar 背景色
    "position": "bottom", // TabBar 位置（仅支持 bottom/top，默认 bottom）
    "borderStyle": "black", // TabBar 边框颜色（仅支持 black/white）
    "list": [ // Tab 列表（数组长度 2-5，顺序和显示顺序一致）
      {
        "pagePath": "pages/index/index", // 对应 pages 中的路径（必须一致）
        "text": "首页", // Tab 文字
        "iconPath": "/static/icon/home.png", // 未选中时的图标路径
        "selectedIconPath": "/static/icon/home-active.png" // 选中时的图标路径
      },
      {
        "pagePath": "pages/category/category",
        "text": "分类",
        "iconPath": "/static/icon/category.png",
        "selectedIconPath": "/static/icon/category-active.png"
      },
      {
        "pagePath": "pages/cart/cart",
        "text": "购物车",
        "iconPath": "/static/icon/cart.png",
        "selectedIconPath": "/static/icon/cart-active.png"
      },
      {
        "pagePath": "pages/my/my",
        "text": "我的",
        "iconPath": "/static/icon/my.png",
        "selectedIconPath": "/static/icon/my-active.png"
      }
    ]
  }
}

TabBar 避坑要点：

• 图标路径必须以 / 开头（绝对路径），建议放在 static 文件夹下，避免路径错误；

• 图标建议使用 40*40px 的图片（png 格式最佳），避免拉伸变形；

• 跳转 TabBar 页面时，必须使用 uni.switchTab() 方法，不能用 uni.navigateTo()（否则跳转无效）。

四、进阶配置：分包加载（解决小程序体积过大）

当项目页面较多时，小程序打包后的体积容易超过 2M（小程序默认限制），此时就需要用到分包加载——将项目拆分为主包和多个分包，启动时只加载主包，进入分包页面时再加载对应分包，减少启动时间。

分包配置在 pages.json 的根节点，新增 subPackages 数组（和 pages 同级），完整示例如下：

{
  "pages": [
    // 主包页面（首页、TabBar 页面必须放在主包）
    {
      "path": "pages/index/index",
      "style": { "navigationBarTitleText": "首页" }
    },
    {
      "path": "pages/my/my",
      "style": { "navigationBarTitleText": "我的" }
    }
  ],
  "subPackages": [
    // 第一个分包（比如“资讯相关”页面）
    {
      "root": "pages-news", // 分包根目录（自定义命名，建议语义化）
      "name": "newsPackage", // 分包名称（可选，用于预加载）
      "pages": [
        // 分包内的页面路径，相对于 root 目录（无需写全路径）
        {
          "path": "list/list",
          "style": { "navigationBarTitleText": "资讯列表" }
        },
        {
          "path": "detail/detail",
          "style": { "navigationBarTitleText": "资讯详情" }
        }
      ]
    },
    // 第二个分包（比如“设置相关”页面）
    {
      "root": "pages-setting",
      "pages": [
        {
          "path": "user/settings",
          "style": { "navigationBarTitleText": "用户设置" }
        }
      ]
    }
  ],
  // 分包预加载（可选，提升用户体验）
  "preloadRule": {
    "pages/index/index": { // 当进入首页时，预加载资讯分包
      "network": "all", // 所有网络环境下都预加载
      "packages": ["newsPackage"] // 预加载的分包名称
    }
  },
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarBackgroundColor": "#F8F8F8"
  }
}

分包配置关键提醒：

• 主包：存放首页、TabBar 页面，以及所有页面共用的组件、资源；

• 分包：存放非核心页面（如资讯、设置），path 是相对于 root 目录的相对路径；

• 跳转分包页面时，路径需包含分包 root，比如跳转资讯列表页：/pages-news/list/list。

五、平台特有配置：多端适配（App/小程序/H5）

UniApp 的核心优势是“一套代码多端运行”，但不同平台（App、微信小程序、H5）的样式和功能存在差异，此时可以用 条件编译 配置平台特有样式。

最常用的条件编译节点是 app-plus（App 端）、mp-weixin（微信小程序）、h5（H5 端），可嵌套在 style 或 globalStyle 中，示例如下：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        // App 端特有配置
        "app-plus": {
          "titleNView": {
            "titleSize": "16px", // App 端导航栏标题字体大小
            "titleColor": "#FFFFFF",
            "backgroundColor": "#FF6700",
            // App 端导航栏右侧添加自定义按钮（用 IconFont 图标）
            "buttons": [
              {
                "text": "\ue60f", // 图标 Unicode 码（来自 IconFont）
                "fontSize": "30px",
                "fontSrc": "/static/iconfont.ttf" // 自定义字体路径（绝对路径）
              }
            ]
          }
        },
        // 微信小程序特有配置
        "mp-weixin": {
          "navigationBarBackgroundColor": "#FF6700",
          "usingComponents": true // 小程序启用自定义组件
        },
        // H5 端特有配置
        "h5": {
          "navigationBarBackgroundColor": "#FFFFFF"
        }
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarBackgroundColor": "#F8F8F8",
    // 全局平台特有配置
    "mp-weixin": {
      "backgroundColorTop": "#F8F8F8" // 小程序顶部背景色
    }
  }
}

说明：条件编译节点内的配置，仅在对应平台生效，其他平台会自动忽略，无需单独编写多套配置文件。

六、新手必看：常见错误及解决方案

整理了 5 个新手最常遇到的 pages.json 配置错误，对应解决方案直接套用，避免踩坑：

• 错误 1：页面跳转报错“fail:page “xxx” is not found”          解决方案：检查该页面是否在 pages 数组中注册，path 路径是否和文件实际位置一致（大小写、文件夹名称是否写错）。

• 错误 2：TabBar 不显示          解决方案：检查 tabBar.list 中的 pagePath 是否和 pages 数组中的 path 完全一致；检查 list 数组长度是否在 2-5 之间。

• 错误 3：下拉刷新不生效          解决方案：在 globalStyle 或页面 style 中，设置 enablePullDownRefresh: true；如果页面用了 scroll-view 组件，会覆盖页面滚动，导致下拉刷新失效（需用 scroll-view 自身的下拉事件）。

• 错误 4：App 端导航栏按钮不显示          解决方案：检查 app-plus 节点是否嵌套在 style 中；检查 fontSrc 路径是否为绝对路径，字体文件是否放在 static 文件夹下。

• 错误 5：小程序打包体积过大  解决方案：使用分包加载（subPackages）；删除项目中无用的图片、组件；压缩图片体积。

• 错误 6：新建页面时，忘记勾选“在pages.json中注册”         解决方案：无需重新新建页面，手动注册即可，两步搞定（新手友好，直接套用）：          1.  找到项目中的 pages.json 文件，打开后定位到 pages 节点（核心路由数组）；  2.  在 pages 数组中，新增一个页面对象，配置正确的 path（页面路径）和可选的 style，path 必须和新建页面的实际路径完全一致（格式：pages/页面文件夹/页面文件名，无需加 .vue 后缀）。          示例：新建了 pages/test/test.vue 页面未注册，就在 pages 数组中添加：          {   “path”: “pages/test/test”,   “style”: {     “navigationBarTitleText”: “测试页面” // 可选，可自定义页面标题   } }          补充：若新建的是分包页面，需在 subPackages 数组中对应分包的 pages 里添加配置，而非根节点的 pages 数组。

• 错误 7：JSHINT 语法报错（line 16 相关）  报错信息：[JSHINT] Expected ‘]’ and instead saw ‘:’、Expected ‘}’ and instead saw ‘pages/compony/compony’          错误原因：pages.json 是JSON 格式文件，语法极其严格，该错误是「JSON 语法写错」（大概率是 pages 数组/页面对象内，逗号、引号、大括号/中括号不匹配，或路径写法错误），结合报错提示，大概率是 pages 数组中新增页面对象时，语法格式错乱（如漏写逗号、引号，或 path 配置格式错误）。  解决方案（新手一步到位）：          1.  打开 pages.json 文件，定位到报错提示的 line 16（第 16 行），重点查看「pages 数组」内的配置（报错中的 pages/compony/compony 是出错的页面路径）；          2.  核对 3 个核心语法（JSON 必遵守）：             – 所有 key（如 path、style）必须用双引号 ” ” 包裹（不能用单引号）；     – 页面对象之间必须用逗号 , 分隔（pages 数组内，多个 { } 之间不能漏写逗号）；             – 大括号 { }、中括号 [ ] 必须成对出现（pages 是 [ ] 数组，每个页面是 { } 对象，不能漏写开头/结尾的括号）；          3.  报错场景实操修正（结合报错路径 pages/compony/compony）：             错误示例（语法错乱）：             “pages”: [   {“path”: “pages/index/index”,”style”: {“navigationBarTitleText”: “首页”}}   {path: pages/compony/compony,”style”: {“navigationBarTitleText”: “公司页”}} // 漏逗号、path 无引号、漏括号 ]    正确示例（修正后）：             “pages”: [   {     “path”: “pages/index/index”,     “style”: {“navigationBarTitleText”: “首页”}   }, // 补充逗号   {     “path”: “pages/compony/compony”, // path 加双引号，路径写完整     “style”: {“navigationBarTitleText”: “公司页”}   } // 成对大括号，无多余符号 ]          4.  快速校验：保存 pages.json 后，若 HBuilder X 右侧无红色报错提示，且 JSHINT 不再报错，即为语法正确。

七、总结：pages.json 配置核心要点

1. 核心节点优先级：页面 style > globalStyle（全局样式），平台特有配置仅在对应平台生效；

2. 所有页面必须在 pages 数组中注册，path 路径务必和文件实际位置一致；

3. TabBar 配置核心是“pagePath 与 pages 路径一致”，最多 5 个 tab；

4. 小程序体积超限时，用分包加载（subPackages）解决；

5. 多端适配用条件编译节点（app-plus、mp-weixin、h5），无需多套代码。

其实 pages.json 配置并不复杂，核心就是“记住核心节点+掌握常见场景”。新手建议先从默认配置入手，新增页面时逐行添加配置，遇到错误对照上面的解决方案排查，多实操几次就能熟练掌握。

如果觉得这篇教程对你有帮助，记得点赞收藏，后续会更新更多 UniApp 新手入门教程，助力大家快速上手跨端开发！