一、核心配置页面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:status1}]}}三、pagespages 是整个应用最核心的配置项相当于应用的“骨架”它是一个数组里面包含了你应用的所有页面信息。1. 属性path必填页面的路径。相当于告诉应用这个页面放在哪个文件夹里。实战注意路径不需要写.vue后缀比如写成pages/index/index即可。style可选页面的窗口样式配置。用来设置当前页面的导航栏标题、背景色、是否支持下拉刷新等。实战注意这里的配置优先级高于全局的globalStyle。如果全局是白色背景你在style里配置了蓝色这个页面就会显示蓝色。needLogin可选标识该页面是否需要登录后才能访问。默认是false如果设为true未登录用户访问时会被拦截。2. style属性属性名类型作用描述实际开发举例navigationBarBackgroundColorHexColor导航栏背景颜色设置为红色主题#FF5722navigationBarTextStyleString导航栏标题及状态栏前景颜色仅支持black/white浅色背景配黑色文字blacknavigationBarTitleTextString导航栏标题文字内容navigationBarTitleText: 商品详情navigationStyleString导航栏样式支持default默认或custom自定义设为custom可隐藏原生导航栏自己写一个炫酷的头部backgroundColorHexColor窗口的背景色下拉时露出的底色下拉时露出灰色背景#F8F8F8enablePullDownRefreshBoolean是否开启当前页面的下拉刷新功能列表页设为true详情页设为falsebackgroundTextStyleString下拉 loading 的样式仅支持dark/light深色背景下拉刷新用lightonReachBottomDistanceNumber页面上拉触底事件触发时距页面底部的距离单位px设为50用于实现列表无限滚动加载3. 实战避坑小贴士首页的诞生pages数组里的第一项就是整个应用的启动页首页。无论你给它起什么名字只要它排在第一位它就是老大。必须注册所有业务页面都必须在这里注册。如果你在文件夹里新建了一个页面但没有在pages数组里添加它这个页面在编译时会被直接忽略无法访问。四、globalStyleglobalStyle用于配置整个应用所有页面的默认窗口表现可以理解为应用的“默认皮肤”。1. 属性属性名类型作用描述实际开发举例navigationBarBackgroundColorHexColor全局导航栏的背景颜色设置全局统一的主题色#007AFFnavigationBarTextStyleString全局导航栏标题及状态栏前景颜色仅支持black/white默认使用黑色文字blacknavigationBarTitleTextString全局默认的导航栏标题文字比如统一叫我的应用navigationStyleString全局导航栏样式支持default默认或custom自定义设为custom时所有页面默认隐藏原生导航栏backgroundColorHexColor全局窗口的背景色下拉刷新时露出的底色统一设置为#F8F8F8enablePullDownRefreshBoolean是否全局开启下拉刷新功能默认设为false需要时再在单页style中开启backgroundTextStyleString下拉 loading 的样式仅支持dark/light配合深色背景使用lightonReachBottomDistanceNumber全局上拉触底事件触发时距页面底部的距离单位px统一设为50方便处理列表触底加载五、tabBartabBar用于配置应用底部的多 Tab 导航栏。它包含全局样式属性和页面列表list两大部分。1. 全局样式属性这些属性控制整个底部导航栏的外观表现属性名类型作用描述实际开发举例colorHexColorTab 上文字/图标的默认未选中颜色设置为灰色#999999selectedColorHexColorTab 上文字/图标的选中颜色设置为主题色#FF5722backgroundColorHexColor底部导航栏的背景颜色设置为白色#FFFFFFborderStyleString导航栏上边框的颜色仅支持black/white默认使用blackpositionStringTabBar 的位置默认bottom可选top放在底部bottom2. 页面列表list 数组这是 tabBar 的核心是一个数组包含了每一个底部导航项的具体配置。属性名类型作用描述实际开发举例pagePathString页面路径。必须在pages数组中先定义过pages/index/indextextStringTab 上显示的文字标签首页iconPathString未选中时的图标路径必须放在static目录下static/tabbar/home.pngselectedIconPathString选中时的图标路径必须放在static目录下static/tabbar/home-active.png3. 实战避坑小贴士数量限制list数组最少配置 2 个最多配置 5 个 Tab。图标路径铁律iconPath和selectedIconPath必须使用本地相对路径并且图片必须存放在项目的static目录下。千万不要使用网络图片或/static别名否则小程序端会无法解析。暗黑模式适配如果你需要支持暗黑模式DarkModetabBar里的颜色属性如color、backgroundColor和图标路径iconPath都支持通过符号引用theme.json中定义的变量从而实现一键切换深浅主题。跳转方式一旦使用了tabBar在代码中跳转这些页面时不能使用普通的uni.navigateTo必须使用uni.switchTab方法。六、subPackagessubPackages分包加载配置是优化小程序体积、提升首次启动速度的核心利器。它主要包含分包基础配置、分包预加载策略以及分包优化开关三个核心部分。1. 分包基础配置 (subPackages)这是分包的核心节点它是一个数组数组中的每一项代表一个独立的子包。属性名类型作用描述实际开发举例rootString子包的根目录必填。主包和分包不能在同一目录下。将订单模块独立分包root: pagesApagesArray子包由哪些页面组成必填。这里的path是相对于root的相对路径。包含订单列表页path: list/listnameString分包别名选填。可用于预加载配置。name: packageApluginsObject在分包内引入的插件代码包选填。仅微信小程序支持且同一插件不能被多个分包同时引用。配置特定分包使用的微信插件。2. 分包预加载策略 (preloadRule)为了提升用户体验避免用户点击分包页面时长时间等待可以配置预加载策略。当用户进入某个页面时框架会自动预下载可能需要的分包。属性名类型作用描述实际开发举例keyString触发预下载的页面路径。pages/index/index进入首页时触发packagesStringArray进入该页面后需要预下载的分包root或name必填。[pagesA, pagesB]networkString指定在何种网络下预下载选填。可选all不限网络或wifi仅WiFi。network: wifi3. 分包优化开关 (manifest.json)除了pages.json中的配置还需要在manifest.json中开启分包优化才能让静态资源和 JS 文件真正放入分包内从而减小主包体积。配置位置作用描述实际开发举例mp-weixin-optimization-subPackages开启微信小程序的分包优化。optimization: {subPackages: true}4. 实战避坑小贴士体积限制微信小程序主包最大不超过 2MB单个分包最大不超过 2MB整个项目主包所有分包总大小不超过 20MB。资源隔离原则静态文件分包目录下放置的static静态资源不会被打包到主包中且不可在主包中使用。JS 文件当某个 JS 文件仅被这一个分包引用时它会被打包进分包如果被主包或多个分包同时引用它依然会被打包到主包中。最佳实践将启动页、TabBar 页面等高频访问的页面放在主包将设置、帮助、订单详情等次要功能放入分包。七、easycomeasycom是一种组件自动引入机制它能让你告别繁琐的 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配置通常不会触发重新编译你需要稍微改动一下页面内容才能触发更新。八、conditioncondition被称为启动模式配置。它仅在开发期间生效打包上线后没有任何作用。它的核心作用是模拟直达某个深层页面的场景例如小程序转发后用户点击打开的页面。在开发时你可以省去从首页一层层点击跳转的麻烦直接启动到目标页面进行调试。1. 核心配置项总结属性名类型是否必填作用描述实际开发举例currentNumber是当前激活的模式。值为list数组中节点的索引值从 0 开始。设为0表示启动时激活list中的第一个配置模式。listArray是启动模式列表。包含一个或多个启动模式的对象。配置一个直达“商品详情页”的启动模式。2. list 数组内部配置项list数组里的每一项都是一个对象包含以下属性属性名类型是否必填作用描述实际开发举例nameString是启动模式的名称。name: 商品详情页pathString是启动页面的路径必须是已注册的页面。path: pages/detail/detailqueryString否启动参数。在目标页面的onLoad生命周期函数中获取。query: id10status13. 实战避坑小贴士不同平台的生效方式在 App 真机运行时配置后运行项目会自动直接打开配置的页面。在微信小程序开发者工具中配置后你需要在开发者工具顶部的“编译模式”下拉框中手动选择对应的模式如“商品详情页”才会生效。参数接收如果你在query中配置了id10status1记得在目标页面的script中通过onLoad((option) { console.log(option.id) })来接收这些参数。上线前清理因为condition纯粹是为了开发调试建议在项目上线打包前将这段配置注释掉或删除保持pages.json的整洁。