当前位置： 首页 > news >正文

三、uni-app页面配置（pages.json）

news 2026/8/20 12:54:16

一、核心配置页面

uni-app 的 pages.json，是 uni-app 项目里最核心的配置文件，堪称整个应用的“大脑和地图”。它负责告诉应用：有哪些页面、页面在哪里、页面长什么样、如何跳转。

配置字段作用描述实际开发举例
pages页面路由配置。注册应用的所有页面，数组的第一项就是应用的启动首页。配置首页"path": "pages/index/index"，并设置标题"navigationBarTitleText": "首页"。
globalStyle全局窗口样式。设置所有页面默认的导航栏样式、背景色等。设置全局导航栏背景为白色"navigationBarBackgroundColor": "#ffffff"。
tabBar底部导航栏配置。设置原生体验的底部多 Tab 切换（图标、文字、对应页面）。配置底部的“首页”、“发现”、“我的”三个 Tab 及对应的图标。
subPackages分包加载配置。将大型应用拆分为多个子包，优化首次加载速度（H5 不支持）。将“商城模块”独立为一个分包"root": "pages-mall"，按需加载。
easycom组件自动引入规则。配置后无需手动 import 和注册组件，直接在页面使用。配置后，直接在页面写<uni-badge></uni-badge>就能自动识别。
condition启动模式配置。仅在开发阶段生效，用于模拟直达某个页面，方便调试。开发时直接启动到“商品详情页”，不用每次都从首页点进去。

二、示例

{// 1. pages：页面路由配置（应用骨架）// 数组的第一项就是应用的启动首页。这里配置的是主包页面。"pages":[{"path":"pages/index/index","style":{"navigationBarTitleText":"好物商城","navigationBarBackgroundColor":"#FF5722","navigationBarTextStyle":"white"}},{"path":"pages/category/category","style":{"navigationBarTitleText":"商品分类"}},{"path":"pages/cart/cart","style":{"navigationBarTitleText":"购物车"}},{"path":"pages/my/my","style":{"navigationBarTitleText":"个人中心","enablePullDownRefresh":true}}],// 2. globalStyle：全局样式配置（默认皮肤）// 定义所有页面默认的窗口表现。如果某个页面需要特殊样式，可以在 pages 里的 style 中覆盖。"globalStyle":{"navigationBarTextStyle":"black","navigationBarTitleText":"我的小店","navigationBarBackgroundColor":"#FFFFFF","backgroundColor":"#F8F8F8","enablePullDownRefresh":false,"onReachBottomDistance":50},// 3. tabBar：底部导航栏配置// 依赖前面的 pages 路径，配置底部多 Tab 切换。"tabBar":{"color":"#909399","selectedColor":"#FF5722","backgroundColor":"#FFFFFF","borderStyle":"black","list":[{"pagePath":"pages/index/index","text":"首页","iconPath":"static/tabbar/home.png","selectedIconPath":"static/tabbar/home-active.png"},{"pagePath":"pages/category/category","text":"分类","iconPath":"static/tabbar/category.png","selectedIconPath":"static/tabbar/category-active.png"},{"pagePath":"pages/cart/cart","text":"购物车","iconPath":"static/tabbar/cart.png","selectedIconPath":"static/tabbar/cart-active.png"},{"pagePath":"pages/my/my","text":"我的","iconPath":"static/tabbar/my.png","selectedIconPath":"static/tabbar/my-active.png"}]},// 4. subPackages：分包加载配置// 将大型应用拆分，减少主包体积，加快首次加载速度。// 这里把“订单模块”独立为一个分包，只有用户进入订单相关页面时才会下载。"subPackages":[{"root":"sub_packages/order","pages":[{"path":"orderList/orderList","style":{"navigationBarTitleText":"我的订单"}},{"path":"orderDetail/orderDetail","style":{"navigationBarTitleText":"订单详情"}}]}],// 5. easycom：组件自动引入规则// 优化开发体验。配置后，只要组件放在 components 目录下，// 就可以直接在页面里使用，无需手动 import 和注册。"easycom":{"autoscan":true,"custom":{"^uni-(.*)":"@/components/uni-$1.vue"}},// 6. condition：启动模式配置// 仅在开发期间生效！用于模拟直达某个页面的场景，方便调试。// 上线前通常会被忽略，放在最后面不会干扰核心业务代码的阅读。"condition":{"current":0,"list":[{"name":"直接打开订单列表","path":"sub_packages/order/orderList/orderList","query":"status=1"}]}}

三、pages

pages 是整个应用最核心的配置项（相当于应用的“骨架”），它是一个数组，里面包含了你应用的所有页面信息。

1. 属性

  • path（必填）：页面的路径。相当于告诉应用这个页面放在哪个文件夹里。
    • 实战注意：路径不需要写.vue后缀，比如写成"pages/index/index"即可。
  • style（可选）：页面的窗口样式配置。用来设置当前页面的导航栏标题、背景色、是否支持下拉刷新等。
    • 实战注意：这里的配置优先级高于全局的globalStyle。如果全局是白色背景，你在style里配置了蓝色，这个页面就会显示蓝色。
  • needLogin（可选）：标识该页面是否需要登录后才能访问。默认是false，如果设为true，未登录用户访问时会被拦截。

2. style属性

属性名类型作用描述实际开发举例
navigationBarBackgroundColorHexColor导航栏背景颜色设置为红色主题"#FF5722"
navigationBarTextStyleString导航栏标题及状态栏前景颜色，仅支持black/white浅色背景配黑色文字"black"
navigationBarTitleTextString导航栏标题文字内容"navigationBarTitleText": "商品详情"
navigationStyleString导航栏样式，支持default（默认）或custom（自定义）设为"custom"可隐藏原生导航栏，自己写一个炫酷的头部
backgroundColorHexColor窗口的背景色（下拉时露出的底色）下拉时露出灰色背景"#F8F8F8"
enablePullDownRefreshBoolean是否开启当前页面的下拉刷新功能列表页设为true，详情页设为false
backgroundTextStyleString下拉 loading 的样式，仅支持dark/light深色背景下拉刷新用"light"
onReachBottomDistanceNumber页面上拉触底事件触发时，距页面底部的距离（单位px）设为50，用于实现列表无限滚动加载

3. 实战避坑小贴士

  • 首页的诞生：pages数组里的第一项，就是整个应用的启动页（首页）。无论你给它起什么名字，只要它排在第一位，它就是老大。
  • 必须注册：所有业务页面都必须在这里注册。如果你在文件夹里新建了一个页面，但没有在pages数组里添加它，这个页面在编译时会被直接忽略，无法访问。

四、globalStyle

globalStyle用于配置整个应用所有页面的默认窗口表现（可以理解为应用的“默认皮肤”）。

1. 属性

属性名类型作用描述实际开发举例
navigationBarBackgroundColorHexColor全局导航栏的背景颜色设置全局统一的主题色"#007AFF"
navigationBarTextStyleString全局导航栏标题及状态栏前景颜色，仅支持black/white默认使用黑色文字"black"
navigationBarTitleTextString全局默认的导航栏标题文字比如统一叫"我的应用"
navigationStyleString全局导航栏样式，支持default（默认）或custom（自定义）设为"custom"时，所有页面默认隐藏原生导航栏
backgroundColorHexColor全局窗口的背景色（下拉刷新时露出的底色）统一设置为"#F8F8F8"
enablePullDownRefreshBoolean是否全局开启下拉刷新功能默认设为false，需要时再在单页style中开启
backgroundTextStyleString下拉 loading 的样式，仅支持dark/light配合深色背景使用"light"
onReachBottomDistanceNumber全局上拉触底事件触发时，距页面底部的距离（单位px）统一设为50，方便处理列表触底加载

五、tabBar

tabBar用于配置应用底部的多 Tab 导航栏。它包含全局样式属性和页面列表（list）两大部分。

1. 全局样式属性

这些属性控制整个底部导航栏的外观表现：

属性名类型作用描述实际开发举例
colorHexColorTab 上文字/图标的默认（未选中）颜色设置为灰色"#999999"
selectedColorHexColorTab 上文字/图标的选中颜色设置为主题色"#FF5722"
backgroundColorHexColor底部导航栏的背景颜色设置为白色"#FFFFFF"
borderStyleString导航栏上边框的颜色，仅支持black/white默认使用"black"
positionStringTabBar 的位置，默认bottom，可选top放在底部"bottom"

2. 页面列表（list 数组）

这是 tabBar 的核心，是一个数组，包含了每一个底部导航项的具体配置。

属性名类型作用描述实际开发举例
pagePathString页面路径。必须在pages数组中先定义过"pages/index/index"
textStringTab 上显示的文字标签"首页"
iconPathString未选中时的图标路径（必须放在static目录下）"static/tabbar/home.png"
selectedIconPathString选中时的图标路径（必须放在static目录下）"static/tabbar/home-active.png"

3. 实战避坑小贴士

  • 数量限制：list数组最少配置 2 个，最多配置 5 个 Tab。
  • 图标路径铁律：iconPath和selectedIconPath必须使用本地相对路径，并且图片必须存放在项目的static目录下。千万不要使用网络图片或@/static别名，否则小程序端会无法解析。
  • 暗黑模式适配：如果你需要支持暗黑模式（DarkMode），tabBar里的颜色属性（如color、backgroundColor）和图标路径（iconPath）都支持通过@符号引用theme.json中定义的变量，从而实现一键切换深浅主题。
  • 跳转方式：一旦使用了tabBar，在代码中跳转这些页面时，不能使用普通的uni.navigateTo，必须使用uni.switchTab方法。

六、subPackages

subPackages（分包加载配置）是优化小程序体积、提升首次启动速度的核心利器。它主要包含分包基础配置、分包预加载策略以及分包优化开关三个核心部分。

1. 分包基础配置 (subPackages)

这是分包的核心节点，它是一个数组，数组中的每一项代表一个独立的子包。

属性名类型作用描述实际开发举例
rootString子包的根目录（必填）。主包和分包不能在同一目录下。将订单模块独立分包："root": "pagesA"
pagesArray子包由哪些页面组成（必填）。这里的path是相对于root的相对路径。包含订单列表页："path": "list/list"
nameString分包别名（选填）。可用于预加载配置。"name": "packageA"
pluginsObject在分包内引入的插件代码包（选填）。仅微信小程序支持，且同一插件不能被多个分包同时引用。配置特定分包使用的微信插件。

2. 分包预加载策略 (preloadRule)

为了提升用户体验，避免用户点击分包页面时长时间等待，可以配置预加载策略。当用户进入某个页面时，框架会自动预下载可能需要的分包。

属性名类型作用描述实际开发举例
keyString触发预下载的页面路径。"pages/index/index"（进入首页时触发）
packagesStringArray进入该页面后，需要预下载的分包root或name（必填）。["pagesA", "pagesB"]
networkString指定在何种网络下预下载（选填）。可选all（不限网络）或wifi（仅WiFi）。"network": "wifi"

3. 分包优化开关 (manifest.json)

除了pages.json中的配置，还需要在manifest.json中开启分包优化，才能让静态资源和 JS 文件真正放入分包内，从而减小主包体积。

配置位置作用描述实际开发举例
mp-weixin->optimization->subPackages开启微信小程序的分包优化。"optimization": {"subPackages": true}

4. 实战避坑小贴士

  • 体积限制（微信小程序）：主包最大不超过 2MB，单个分包最大不超过 2MB，整个项目（主包+所有分包）总大小不超过 20MB。
  • 资源隔离原则：
    • 静态文件：分包目录下放置的static静态资源不会被打包到主包中，且不可在主包中使用。
    • JS 文件：当某个 JS 文件仅被这一个分包引用时，它会被打包进分包；如果被主包或多个分包同时引用，它依然会被打包到主包中。
  • 最佳实践：将启动页、TabBar 页面等高频访问的页面放在主包；将设置、帮助、订单详情等次要功能放入分包。

七、easycom

easycom是一种组件自动引入机制，它能让你告别繁琐的 import 和 components 注册步骤，直接在页面中使用组件。

1. 核心配置项总结

属性名类型默认值作用描述实际开发举例
autoscanBooleantrue是否开启自动扫描功能。开启后，框架会自动扫描符合默认目录规范的组件并注册。保持默认的true，组件放在components/组件名/组件名.vue即可自动识别。
customObject{}自定义匹配规则。当你的组件路径或命名不符合默认规范时，可以使用正则表达式进行自定义映射。将^my-(.*)映射到@/components/my/$1.vue，这样使用<my-button>时就会自动找到对应文件。

2. 实战避坑小贴士

  • 默认规范（autoscan 的底层逻辑）：只要你的组件安装在项目的components目录或uni_modules目录下，并且严格符合components/组件名称/组件名称.vue的目录结构，就可以免注册直接使用。
  • 自定义规则（custom 的语法）：custom的键（Key）是组件标签名的正则表达式，值（Value）是组件文件的路径模板。例如：你有一个组件放在src/components/common/button.vue，想通过<app-button>使用，可以配置为：
"^app-(.*)":"src/components/common/$1.vue"
  • 命名规范：组件命名必须是小写字母，并使用短横线（kebab-case）连接单词，例如my-component。
  • 性能优势：不管components目录下安装了多少组件，easycom在打包后会自动剔除没有使用的组件，实现真正的“按需打包”，对包体积优化非常友好。
  • 修改配置不热更新：考虑到编译速度，直接在pages.json内修改easycom配置通常不会触发重新编译，你需要稍微改动一下页面内容才能触发更新。

八、condition

condition被称为启动模式配置。它仅在开发期间生效，打包上线后没有任何作用。

它的核心作用是：模拟直达某个深层页面的场景（例如小程序转发后用户点击打开的页面）。在开发时，你可以省去从首页一层层点击跳转的麻烦，直接启动到目标页面进行调试。

1. 核心配置项总结

属性名类型是否必填作用描述实际开发举例
currentNumber是当前激活的模式。值为list数组中节点的索引值（从 0 开始）。设为0，表示启动时激活list中的第一个配置模式。
listArray是启动模式列表。包含一个或多个启动模式的对象。配置一个直达“商品详情页”的启动模式。

2. list 数组内部配置项

list数组里的每一项都是一个对象，包含以下属性：

属性名类型是否必填作用描述实际开发举例
nameString是启动模式的名称。"name": "商品详情页"
pathString是启动页面的路径（必须是已注册的页面）。"path": "pages/detail/detail"
queryString否启动参数。在目标页面的onLoad生命周期函数中获取。"query": "id=10&status=1"

3. 实战避坑小贴士

  • 不同平台的生效方式：
    • 在 App 真机运行时：配置后，运行项目会自动直接打开配置的页面。
    • 在微信小程序开发者工具中：配置后，你需要在开发者工具顶部的“编译模式”下拉框中，手动选择对应的模式（如“商品详情页”）才会生效。
  • 参数接收：如果你在query中配置了id=10&status=1，记得在目标页面的<script>中通过onLoad((option) => { console.log(option.id) })来接收这些参数。
  • 上线前清理：因为condition纯粹是为了开发调试，建议在项目上线打包前，将这段配置注释掉或删除，保持pages.json的整洁。
http://www.cnnetsun.cn/news/4117356.html

相关文章：

  • Windows 上部署 NFSv4.1 客户端全攻略：从源码编译到挂载排障的 7 个实战步骤
  • 免费离线语音转文字工具实测：1小时会议录音10分钟出稿，还能分清谁在说话
  • STM32 多通道 ADC + DMA 采集实战：数据错位、读数跳动的根因与滤波选型
  • 免费跨平台视频下载器实战指南：视频号、抖音、快手、QQ音乐资源一次拿下
  • 手绘×AI渲染：概念设计师的高效科幻物件创作全流程
  • 高性能永磁电机驱动系统：从IGBT到FOC算法的核心原理与工程实践
  • 从零到精通：5步搭建PKHeX-Plugins宝可梦数据自动化工作台
  • SubtitleEdit 开源字幕工具怎么用：从零到专业字幕的完整攻略
  • 拯救者工具箱 Lenovo Legion Toolkit 实战指南：告别 Vantage 全家桶，性能与续航一把抓
  • 2026年7月伊春市新房价格深度分析报告
  • 网盘直链提取怎么用？一个免费脚本打通八大网盘下载的完整攻略
  • 大模型聊天格式（Chat Template）详解：从原理到工程实践
  • 老游戏的高清第二春：D2DX补丁让暗黑破坏神2跑满60帧并铺满宽屏的完整教程
  • XMC1202 UART通讯调试全攻略：从时钟配置到抗干扰设计
  • 一张原图衍生整套系列，精简工序高效出稿
  • 可能交叉编译ffmpeg后还需要jni函数
  • ComfyUI AI视频生成：从零搭建本地可视化工作流完整指南
  • VC++ 运行库一键安装保姆级教程：从 DLL 缺失报错到彻底修复
  • 免费开源的模组冲突克星，10分钟快速上手
  • 26.8.4 ntfs文件权限
  • 氢燃料电池与纯电动车技术路线深度解析：从原理到应用场景
  • 需求只给几张截图，兼职的程序员该怎么报价
  • 基于Unity+3D+++C#实现的西安大雁塔文化主题虚拟展馆交互漫游系统
  • TrollInstallerX 免费一键安装 TrollStore：iOS 14.0-16.6.1 旧 iPhone 不再吃灰，几秒就能搞定
  • 教你如何提取图片中的纯净文字
  • 网盘直链解析脚本实测：一个油猴脚本管九大网盘，为什么我反而劝你别迷信“破解限速“？
  • 打不开同事的VSDX文件？drawio-desktop免费跨平台画图工具实测手记
  • PEAM：基于LoRA与对比学习的具身智能体参数化记忆系统
  • 抖音批量下载的实用型方案：douyin-downloader 从环境配置到批量产出的完整记录
  • AI智能体忠诚度验证：构建可解释与可信的决策系统