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

一、核心配置页面

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`	启动模式配置。仅在开发阶段生效，用于模拟直达某个页面，方便调试。	开发时直接启动到"商品详情页"，不用每次都从首页点进去。

二、示例

json 复制代码

{
  // 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属性

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

3. 实战避坑小贴士

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

四、globalStyle

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

1. 属性

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

五、tabBar

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

1. 全局样式属性

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

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

2. 页面列表（list 数组）

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

属性名	类型	作用描述	实际开发举例
`pagePath`	String	页面路径。必须在 `pages` 数组中先定义过	`"pages/index/index"`
`text`	String	Tab 上显示的文字标签	`"首页"`
`iconPath`	String	未选中时的图标路径（必须放在 `static` 目录下）	`"static/tabbar/home.png"`
`selectedIconPath`	String	选中时的图标路径（必须放在 `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)

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

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

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

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

属性名	类型	作用描述	实际开发举例
`key`	String	触发预下载的页面路径。	`"pages/index/index"`（进入首页时触发）
`packages`	StringArray	进入该页面后，需要预下载的分包 `root` 或 `name`（必填）。	`["pagesA", "pagesB"]`
`network`	String	指定在何种网络下预下载（选填）。可选 `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. 核心配置项总结

属性名	类型	默认值	作用描述	实际开发举例
`autoscan`	Boolean	`true`	是否开启自动扫描功能。开启后，框架会自动扫描符合默认目录规范的组件并注册。	保持默认的 `true`，组件放在 `components/组件名/组件名.vue` 即可自动识别。
`custom`	Object	`{}`	自定义匹配规则。当你的组件路径或命名不符合默认规范时，可以使用正则表达式进行自定义映射。	将 `^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> 使用，可以配置为：

json 复制代码

"^app-(.*)": "src/components/common/$1.vue"

命名规范 ：组件命名必须是小写字母，并使用短横线（kebab-case）连接单词，例如 my-component。
性能优势 ：不管 components 目录下安装了多少组件，easycom 在打包后会自动剔除没有使用的组件，实现真正的"按需打包"，对包体积优化非常友好。
修改配置不热更新 ：考虑到编译速度，直接在 pages.json 内修改 easycom 配置通常不会触发重新编译，你需要稍微改动一下页面内容才能触发更新。

八、condition

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

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

1. 核心配置项总结

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

2. list 数组内部配置项

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

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

3. 实战避坑小贴士

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