Uniapp 页面路由配置（pages.json）完全指南

在 Uniapp 开发中，pages.json 是一个核心配置文件，用于管理应用的路由、页面样式、导航栏、底部 TabBar 等全局设置。它类似于微信小程序的 app.json，但功能更加强大，支持多端适配（H5、小程序、App 等）。

本文将详细介绍 pages.json 的配置方法，涵盖基本结构、页面路由、全局样式、TabBar 配置、条件编译等内容，并结合实际示例帮助开发者快速掌握 Uniapp 的路由管理机制。

1. pages.json 的基本结构

pages.json 采用 JSON 格式，主要包含以下几个核心配置项：

{"pages": [],          // 必填，页面路由配置"globalStyle": {},    // 全局窗口样式"tabBar": {},         // 底部/顶部 TabBar 配置"condition": {},      // 开发环境启动模式"easycom": {},        // 组件自动引入规则"subPackages": []     // 分包加载配置
}

其中，pages 是必填项，用于定义应用的所有页面路径，数组的第一个页面就是应用的启动页。

2. 页面路由配置（pages）

pages 是一个数组，每一项代表一个页面，格式如下：

"pages": [{"path": "pages/index/index",  // 页面路径"style": {                    // 页面样式"navigationBarTitleText": "首页","enablePullDownRefresh": true}},{"path": "pages/user/user","style": {"navigationBarTitleText": "个人中心"}}
]

关键点

1. path：页面路径，无需写文件后缀（如 .vue）。

2. style：可覆盖 globalStyle 的全局样式，支持自定义导航栏、下拉刷新等。

3. 第一项为启动页：pages 数组的第一个页面就是应用启动时加载的首页。

3. 全局窗口样式（globalStyle）

globalStyle 用于定义所有页面的默认样式，如导航栏、背景色、下拉刷新等：

"globalStyle": {"navigationBarTextStyle": "black",      // 标题颜色：black/white"navigationBarTitleText": "Uniapp Demo", // 默认标题"navigationBarBackgroundColor": "#F8F8F8", // 导航栏背景色"backgroundColor": "#FFFFFF",           // 页面背景色"enablePullDownRefresh": false,         // 是否开启全局下拉刷新"onReachBottomDistance": 50,            // 页面上拉触底距离（单位px）"app-plus": {                           // App 特有配置"titleNView": false                   // 是否禁用原生导航栏},"h5": {                                // H5 特有配置"titleNView": false                  // 是否禁用 H5 导航栏}
}

常见应用场景

• 自定义导航栏：在 app-plus 或 h5 中关闭原生导航栏，使用自定义 UI。

• 下拉刷新：enablePullDownRefresh 设为 true 后，可在页面监听 onPullDownRefresh 事件。

• 触底加载：通过 onReachBottomDistance 设置触底距离，结合 onReachBottom 实现分页加载。

4. 底部 TabBar 配置（tabBar）

如果应用需要底部导航栏（如微信小程序），可以通过 tabBar 配置：

"tabBar": {"color": "#999999",               // 默认文字颜色"selectedColor": "#007AFF",       // 选中时文字颜色"backgroundColor": "#FFFFFF",     // TabBar 背景色"borderStyle": "black",           // 上边框颜色（black/white）"position": "bottom",             // 位置（bottom/top）"list": [{"pagePath": "pages/index/index",  // 页面路径"text": "首页",                   // 文字"iconPath": "static/tab-home.png",       // 默认图标"selectedIconPath": "static/tab-home-active.png" // 选中图标},{"pagePath": "pages/user/user","text": "我的","iconPath": "static/tab-user.png","selectedIconPath": "static/tab-user-active.png"}]
}

注意事项

1. list 最少 2 个，最多 5 个：TabBar 的选项数量有限制。

2. pagePath 必须在 pages 中定义：否则会报错。

3. 图标推荐尺寸：建议使用 81px × 81px 的 PNG 图标，避免模糊。

5. 条件编译与平台差异化配置

Uniapp 支持条件编译，可以为不同平台（H5、小程序、App）配置不同的样式：

"pages": [{"path": "pages/index/index","style": {"navigationBarTitleText": "默认标题","mp-weixin": {                    // 仅微信小程序生效"navigationBarTitleText": "微信首页"},"app-plus": {                     // 仅 App 生效"titleNView": false             // 禁用原生导航栏},"h5": {                           // 仅 H5 生效"titleNView": false}}}
]

适用场景

• 不同平台不同标题：比如在微信小程序显示“微信首页”，在 App 显示“App 首页”。

• 禁用原生导航栏：在 App 和 H5 中使用自定义导航栏。

6. 路由跳转方式

Uniapp 提供了多种路由跳转 API，适用于不同场景：

方法	说明	示例
uni.navigateTo	保留当前页，跳转新页面（可返回）	uni.navigateTo({ url: '/pages/detail/detail?id=1' })
uni.redirectTo	关闭当前页，跳转新页面（不可返回）	uni.redirectTo({ url: '/pages/login/login' })
uni.switchTab	跳转 TabBar 页面（关闭其他页面）	uni.switchTab({ url: '/pages/index/index' })
uni.reLaunch	关闭所有页面，打开新页面	uni.reLaunch({ url: '/pages/home/home' })
uni.navigateBack	返回上一页或多级页面	uni.navigateBack({ delta: 1 })

参数传递

// 跳转时传参
uni.navigateTo({url: '/pages/detail/detail?id=123&name=uniapp'
})// 目标页面接收参数
export default {onLoad(options) {console.log(options.id)    // 123console.log(options.name)  // "uniapp"}
}

7. 分包加载（subPackages）

如果应用体积较大，可以使用分包加载优化性能：

"subPackages": [{"root": "pages/sub",       // 分包根目录"pages": [                // 分包页面{"path": "shop/list","style": { "navigationBarTitleText": "商品列表" }}]}
]

分包优势

• 按需加载：用户访问分包页面时才下载，减少首屏加载时间。

• 突破主包大小限制：微信小程序主包限制 2MB，分包可扩展至 20MB。

8. 开发调试技巧（condition）

在开发阶段，可以通过 condition 配置启动模式，快速调试特定页面：

"condition": {"current": 0,       // 当前激活的模式索引"list": [{"name": "商品详情",  // 模式名称"path": "pages/detail/detail",  // 启动页面"query": "id=1001"  // 启动参数}]
}

在 HBuilderX 中，可以右键 pages.json 选择 “启动模式” 进行调试。

9. 常见问题与解决方案

Q1：页面路径报错 "Page not found"

• 原因：pages.json 未正确配置页面路径。

• 解决：检查 path 是否拼写正确，并确保文件存在。

Q2：TabBar 不显示

• 原因：

  1. tabBar.list 少于 2 个或超过 5 个。

  2. pagePath 未在 pages 中定义。

• 解决：确保 list 数量正确，且 pagePath 已配置。

Q3：如何动态修改导航栏标题？

uni.setNavigationBarTitle({title: "新标题"
})

10. 总结

pages.json 是 Uniapp 的核心配置文件，掌握它的用法可以高效管理应用的路由、样式和导航。本文详细介绍了：

1. pages 页面路由配置

2. globalStyle 全局样式

3. tabBar 底部导航栏

4. 条件编译与平台差异化

5. 路由跳转与参数传递

6. 分包加载优化

7. 开发调试技巧

合理使用 pages.json 可以让你的 Uniapp 应用更加灵活、高效。希望这篇指南能帮助你更好地掌握 Uniapp 路由管理