UniApp pages.json 配置完全指南

一、pages.json 是什么？

pages.json 是 UniApp 项目的核心配置文件，相当于整个应用的"大脑和地图"。它负责管理应用的页面路由、窗口样式、导航栏设置、底部 TabBar 等全局信息。简单来说，它告诉应用"有哪些页面、页面在哪里、页面长什么样、如何跳转"。

​​为什么需要 pages.json？​​

• ​​页面路由管理​​：所有页面必须在 pages.json 中注册，否则无法正常访问
• ​​全局样式统一​​：可以设置导航栏、背景色等全局样式，避免在每个页面重复配置
• ​​多端适配​​：支持条件编译，针对不同平台（小程序、H5、App）进行差异化配置
• ​​性能优化​​：支持分包加载，优化大型应用的加载速度

二、基础配置结构

一个完整的 pages.json 文件包含以下核心配置项：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "演示",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#3cc51f",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "iconPath": "static/image/icon_component.png",
        "selectedIconPath": "static/image/icon_component_HL.png",
        "text": "首页"
      }
    ]
  },
  "easycom": {
    "autoscan": true,
    "custom": {
      "^uni-(.*)": "@/components/uni-$1.vue"
    }
  }
}

三、pages 页面路由配置

3.1 pages 数组详解

pages 数组是必填项，用于定义应用的所有页面。数组中的每个对象代表一个页面，包含页面的路径和样式信息。

​​关键属性：​​

• path：页面路径，以 / 开头，省略 .vue 扩展名
• style：页面样式配置，优先级高于 globalStyle
• needLogin：是否需要登录后才能访问（默认 false）

​​配置示例：​​

"pages": [
  {
    "path": "pages/index/index",
    "style": {
      "navigationBarTitleText": "首页",
      "navigationBarBackgroundColor": "#3b82f6",
      "navigationBarTextStyle": "white"
    }
  },
  {
    "path": "pages/about/about",
    "style": {
      "navigationBarTitleText": "关于我们"
    }
  }
]

​​重要规则：​​

• 数组第一项为应用启动页（首页）
• 所有页面必须在 pages 中注册，否则无法访问
• 路径必须与文件实际路径完全一致

3.2 页面跳转方式

UniApp 提供多种页面跳转 API，适用于不同场景：

​​1. uni.navigateTo - 保留当前页跳转​​

uni.navigateTo({
  url: '/pages/detail/detail?id=123&name=张三'
})

特点：新页面入栈，可通过返回按钮返回

​​2. uni.redirectTo - 关闭当前页跳转​​

uni.redirectTo({
  url: '/pages/login/login'
})

特点：关闭当前页，无法返回

​​3. uni.reLaunch - 重启应用跳转​​

uni.reLaunch({
  url: '/pages/index/index'
})

特点：关闭所有页面，清空页面栈

​​4. uni.switchTab - TabBar 页面跳转​​

uni.switchTab({
  url: '/pages/index/index'
})

特点：只能跳转 tabBar 配置的页面

3.3 页面传参与接收

​​传参方式：​​

uni.navigateTo({
  url: '/pages/detail/detail?id=123&name=张三'
})

​​接收参数：​​

export default {
  onLoad(options) {
    console.log(options.id);    // 输出 123
    console.log(options.name);  // 输出 张三
  }
}

四、globalStyle 全局样式配置

globalStyle 用于设置应用的全局窗口样式，这些样式会应用到所有页面上。如果某个页面在 pages 中有单独的样式配置，则会覆盖全局样式。

4.1 常用配置属性

属性	类型	默认值	描述
navigationBarBackgroundColor	HexColor	#F8F8F8	导航栏背景颜色
navigationBarTextStyle	String	black	导航栏标题颜色（black/white）
navigationBarTitleText	String	-	导航栏标题文字
navigationStyle	String	default	导航栏样式（default/custom）
backgroundColor	HexColor	#ffffff	下拉刷新窗口背景色
enablePullDownRefresh	Boolean	false	是否开启下拉刷新
onReachBottomDistance	Number	50	上拉触底距离（px）

​​配置示例：​​

"globalStyle": {
  "navigationBarTextStyle": "black",
  "navigationBarTitleText": "演示",
  "navigationBarBackgroundColor": "#F8F8F8",
  "backgroundColor": "#F8F8F8",
  "enablePullDownRefresh": true,
  "onReachBottomDistance": 50
}

4.2 navigationStyle 特殊配置

当设置 navigationStyle: "custom" 时，表示取消默认的原生导航栏，此时导航栏的背景色、标题文字等属性会失效，需要开发者自定义导航栏。

五、tabBar 底部导航栏配置

tabBar 用于配置底部导航栏，适用于多 Tab 应用场景。

5.1 基础配置

"tabBar": {
  "color": "#7A7E83",
  "selectedColor": "#3cc51f",
  "borderStyle": "black",
  "backgroundColor": "#ffffff",
  "height": "50px",
  "fontSize": "10px",
  "iconWidth": "24px",
  "spacing": "3px",
  "list": [
    {
      "pagePath": "pages/index/index",
      "iconPath": "static/image/icon_component.png",
      "selectedIconPath": "static/image/icon_component_HL.png",
      "text": "首页"
    }
  ]
}

5.2 list 数组配置

list 数组用于定义每个 Tab 项，最少 2 个，最多 5 个。

​​list 项属性：​​

• pagePath：页面路径（必填，必须在 pages 中注册）
• text：Tab 文字（App/H5 平台必填）
• iconPath：未选中图标路径（建议尺寸 81px×81px）
• selectedIconPath：选中图标路径
• iconfont：字体图标配置（优先级高于 iconPath）

​​注意事项：​​

• 图标大小限制为 40KB
• 不支持网络图片和字体图标
• 当 position 为 top 时，iconPath 和 selectedIconPath 失效

5.3 position 位置配置

position 属性用于设置 TabBar 的位置，可选值：

• bottom：底部（默认）
• top：顶部（仅微信小程序支持）

"tabBar": {
  "position": "top",
  "list": [
    // 当 position 为 top 时，iconPath 失效
  ]
}

六、条件编译处理多端差异

UniApp 通过条件编译实现"一套代码多端运行"，在编译阶段根据平台差异自动包含或排除代码块。

6.1 条件编译语法

​​基础语法：​​

// #ifdef 平台标识
平台特有代码
// #endif

​​常用平台标识：​​

• H5：H5 平台
• MP-WEIXIN：微信小程序
• MP-ALIPAY：支付宝小程序
• APP-PLUS：App 平台
• MP：所有小程序平台

6.2 pages.json 中的条件编译

在 pages.json 中，可以对不同平台配置不同的页面或样式：

"pages": [
  // #ifdef H5
  {
    "path": "pages/h5/index",
    "style": {
      "navigationBarTitleText": "H5首页"
    }
  },
  // #endif
  // #ifdef MP-WEIXIN
  {
    "path": "pages/weixin/index",
    "style": {
      "navigationBarTitleText": "微信首页"
    }
  },
  // #endif
]

6.3 static 目录条件编译

在 static 目录下创建平台专属目录，只有对应平台的资源才会被编译：

static/
├── mp-weixin/    # 仅微信小程序打包
│   └── logo.png
├── common/       # 所有平台打包
│   └── bg.jpg
└── app/          # 仅 App 平台打包
    └── icon.png

七、其他重要配置

7.1 easycom 组件自动引入

easycom 用于配置组件自动引入规则，无需手动 import：

"easycom": {
  "autoscan": true,
  "custom": {
    "^uni-(.*)": "@/components/uni-$1.vue",
    "^u-(.*)": "@/uview-ui/components/u-$1/u-$1.vue"
  }
}

7.2 subPackages 分包加载

当项目较大时，可以使用分包优化加载速度：

"subPackages": [
  {
    "root": "pagesA",
    "pages": [
      {
        "path": "list/list",
        "style": {
          "navigationBarTitleText": "列表页"
        }
      }
    ]
  }
]

7.3 condition 启动模式配置

condition 用于配置开发期间的启动模式，仅开发期间生效：

"condition": {
  "current": 0,
  "list": [
    {
      "name": "test",
      "path": "pages/test/index"
    }
  ]
}

八、常见问题与解决方案

8.1 页面栈限制

​​问题​​：页面栈最多 10 层（小程序端），超出限制会导致跳转失败

​​解决方案​​：

• 合理使用 redirectTo 或 reLaunch 清理页面栈
• 避免页面跳转过深

8.2 TabBar 页面限制

​​问题​​：只有配置在 tabBar 中的页面才能使用 uni.switchTab 跳转

​​解决方案​​：

• 非 TabBar 页面使用 navigateTo 或 redirectTo
• 确保 pagePath 在 pages 中已注册

8.3 路径格式错误

​​问题​​：路径必须以 / 开头，且与 pages.json 中配置完全一致

​​解决方案​​：

• 使用绝对路径（如 /pages/detail/detail）
• 确保路径中的文件名和目录名正确无误

8.4 条件编译语法错误

​​问题​​：JSON 条件编译时逗号分隔符错误

​​解决方案​​：

• 注意 JSON 语法，避免多余逗号
• 使用 HBuilderX 的语法校验功能

九、最佳实践建议

1. ​​合理使用分包​​：大型项目建议使用分包加载，优化首屏加载速度
2. ​​统一全局样式​​：在 globalStyle 中设置统一的导航栏、背景色等样式
3. ​​条件编译优化​​：针对不同平台使用条件编译，减少代码体积
4. ​​页面栈管理​​：合理使用跳转方式，避免页面栈过深
5. ​​静态资源管理​​：使用 static 目录的条件编译，按平台加载资源