uni-app全局文件

一、pages.json 页面路由

pages.json 文件用来对 uni-app 进行全局配置，决定页面文件的路径、窗口样式、原生的导航栏、底部的原生 tabbar 等。

导航栏高度为 44px (不含状态栏)，tabBar 高度为 50px (不含安全区)。

它类似微信小程序中app.json的页面管理部分。注意定位权限申请等原属于app.json的内容，在 uni-app 中是在 manifest 中配置。

1.1 配置项列表

属性	类型	必填	描述	平台兼容
globalStyle	Object	否	设置默认页面的窗口表现
pages	Object Array	是	设置页面路径及窗口表现
easycom	Object	否	组件自动引入规则	2.5.5+
tabBar	Object	否	设置底部 tab 的表现
condition	Object	否	启动模式配置
subPackages	Object Array	否	分包加载配置	H5 不支持
preloadRule	Object	否	分包预下载规则	微信小程序、QQ 小程序、抖音小程序、支付宝小程序、京东小程序
leftWindow	Object	否	大屏左侧窗口	H5
topWindow	Object	否	大屏顶部窗口	H5
rightWindow	Object	否	大屏右侧窗口	H5
uniIdRouter	Object	否	自动跳转相关配置，新增于 HBuilderX 3.5.0
entryPagePath	String	否	默认启动首页，新增于 HBuilderX 3.7.0	微信小程序、支付宝小程序、抖音小程序、鸿蒙元服务

1.2 pages.json 是干什么的

pages.json = uni-app 的"路由 + 全局界面配置中心"

1.3 pages.json 最核心的 3 大块

json 复制代码

{
  "pages": [],
  "tabBar": {},
  "globalStyle": {}
}

1.4 pages（页面注册，最重要）

1️⃣ 页面必须在这里注册，才能访问

json 复制代码

{
  "pages": [
    {
      "path": "pages/login/login",
      "style": {
        "navigationBarTitleText": "登录"
      }
    }
  ]
}

核心规则
- path 必须和文件路径一致
- 第一个 page 是首页
- 不注册 → navigateTo 直接失败

2️⃣ 常用 page style 配置（你会经常改）

json 复制代码

"style": {
  "navigationBarTitleText": "登录",
  "navigationBarBackgroundColor": "#ffffff",
  "navigationBarTextStyle": "black",
  "enablePullDownRefresh": false
}

字段	作用
navigationBarTitleText	标题
navigationBarBackgroundColor	顶部背景
navigationBarTextStyle	white / black
enablePullDownRefresh	下拉刷新

1.5 tabBar

1️⃣ 一旦进 tabBar，就跳转规则完全变

json 复制代码

"tabBar": {
  "color": "#999",
  "selectedColor": "#007AFF",
  "list": [
    {
      "pagePath": "pages/home/index",
      "text": "首页"
    },
    {
      "pagePath": "pages/login/login",
      "text": "我的"
    }
  ]
}

tabBar 的三条铁律
- tabBar 页面不能用 navigateTo
- tabBar 页面不会被销毁
- tabBar 页面不能带参数

1.6 globalStyle（全局样式）

1️⃣ 所有页面默认样式

json 复制代码

"globalStyle": {
  "navigationBarTextStyle": "black",
  "navigationBarTitleText": "uni-app",
  "navigationBarBackgroundColor": "#ffffff",
  "backgroundColor": "#f8f8f8"
}

页面 style 会覆盖 globalStyle

1.7 subPackages（分包，项目稍大必用）

json 复制代码

"subPackages": [
  {
    "root": "pages-sub",
    "pages": [
      {
        "path": "detail/detail",
        "style": {
          "navigationBarTitleText": "详情"
        }
      }
    ]
  }
]

主包：登录、首页
分包：详情、列表、配置
首屏体积 = 主包大小

1.8 preloadRule（预加载，性能优化）

json 复制代码

"preloadRule": {
  "pages/home/index": {
    "network": "all",
    "packages": ["pages-sub"]
  }
}

1.9 小总结

1️⃣ 页面不在 pages.json → 跳不过去

2️⃣ 第一个 page 是首页

3️⃣ tabBar 页面用 switchTab

4️⃣ tabBar 页面不能传参

5️⃣ 页面 style > globalStyle

6️⃣ 页面不会用 Vue 的 mounted

7️⃣ 分包能救首屏性能

8️⃣ pages.json = 路由注册表

二、manifest.json 应用配置

manifest.json 是干什么的

manifest.json 文件是应用的配置文件，用于指定应用的名称、图标、权限等。HBuilderX 创建的工程此文件在根目录，CLI 创建的工程此文件在 src 目录。

manifest.json = 应用"壳层配置" + "平台差异配置"

它不管页面、不管路由，只管：
- 应用长什么样
- 运行在什么平台
- 权限 / 启动方式 / 编译行为

三、App.vue/App.uvue

App.vue / App.uvue 是什么？

在 uni-app 项目中，这两个文件都是应用的入口 / 全局配置文件。它们不是真正的页面，而是整个应用最顶层的全局组件。所有页面都是在这个顶层下进行切换的。

区别：

如果是常规 uni-app 项目通常是 App.vue（使用 Vue 框架）。
如果是 uni-app x 项目，则是 App.uvue（工作机制类似，只是格式上略有不同）。

为什么不能在 App.vue 写视图模板？

不能写 <template> 标签也就是不能写页面 UI 内容

因为这个文件不是一个真正的"页面组件"。它是 应用的全局入口，不能像普通页面那样写界面标签。

App.vue / App.uvue 能做什么？

1、监听应用生命周期

在这里你可以监听应用整个生命周期的逻辑，比如：

onLaunch：应用启动时触发
onShow：应用从后台返回前台时触发
onHide：应用进入后台时触发

js 复制代码

<script>
	// 只能在App.vue里监听应用的生命周期
	export default {
		onLaunch: function(options) {
			console.log('App Launch')
			console.log('应用启动路径：', options.path)
		},
		onShow: function(options) {
			console.log('App Show')
			console.log('应用启动路径：', options.path)
		},
		onHide: function() {
			console.log('App Hide')
		}
	}
</script>

这些生命周期只能在 App.vue 里监听，其他页面监听无效。

2、定义全局数据 globalData

可以在这里定义一些全局变量，全应用任何地方都能访问。

比如你在 App.vue 中写：

js 复制代码

export default {
  globalData: {
    userInfo: null
  }
}

然后在页面访问：

java 复制代码

const app = getApp()
console.log(app.globalData.userInfo)

这相当于应用级别的简单全局状态。如果是大型复杂状态管理，建议使用 Vuex 或 Pinia 来管理。

3、写全局样式

在 App.vue/uvue 的 <style> 中定义的 CSS 会被整个项目所有页面共享。

比如设定一个全局背景颜色：

html 复制代码

<style>
body {
  background-color: #fff;
}
</style>

注意：如果你的项目同时有 .vue 和 .nvue 文件，某些 CSS 在 nvue 里可能不支持，这时需要做条件编译。

App.vue / App.uvue 什么时候运行？

一打开应用，它的生命周期函数会自动运行
每次应用从后台回来也会触发 onShow
不同平台（H5、App、各种小程序）都适用这些生命周期逻辑（不过有些钩子部分平台可能不支持）

注意事项

App.vue/uvue 不是页面 ，不能写 <template>
只能用于 全局逻辑、生命周期、样式、全局变量
页面之间跳转由 uni.navigateTo, uni.switchTab 等 API 控制
想做全局状态的话，用 Vue 的状态管理（Vuex/Pinia）比 globalData 更可靠

功能	写在 App.vue/uvue	写在页面
应用启动逻辑	✅	❌
全局样式	✅	部分可
页面 UI	❌	✅
页面组件逻辑	❌	✅

四、main.js/main.uts

main.js / main.uts 是干嘛的？

它负责：创建应用实例，把 App.vue / App.uvue 挂载起来，然后启动整个应用。

👉 如果 App.vue 是"灵魂"

👉 那 main.js 就是"点火开关"

没有 main.js，App.vue 根本跑不起来。

为什么需要 main.js？

你写了 App.vue，但浏览器 / App / 小程序并不知道：

❓ "我该从哪个文件开始执行？"

main.js 就是明确告诉框架：

用哪个框架（Vue）
用哪个根组件（App.vue）
怎么初始化应用
什么时候挂载到页面

main.js（传统 uni-app，Vue）结构详解

最最常见的 main.js

js 复制代码

import App from './App.vue'

import { createSSRApp } from 'vue'

export function createApp() {
  const app = createSSRApp(App)
  return {
    app
  }
}

import App from './App.vue'
- 把全局根组件 App.vue 引进来
- 相当于："等会我要用这个 App.vue 当整个应用的最外层"
import { createSSRApp } from 'vue'
- 从 Vue 框架里，拿到一个「创建应用实例」的方法
- 为什么不是 createApp？因为 uni-app 需要多端 + SSR 兼容，官方统一用 createSSRApp。
export function createApp() { ... }
- 这是 uni-app 约定的入口函数
- 框架启动时，会自动调用这个函数
- 你不用手动调用，uni-app 帮你调
const app = createSSRApp(App)
- 用 App.vue 创建一个 Vue 应用实例
- 等价于 Vue 项目里的：createApp(App)
return { app }
- 把这个应用实例交给 uni-app 框架
- 后续由 uni-app 负责挂载、渲染、生命周期管理

整体执行流程

text 复制代码

main.js
  ↓
createSSRApp(App.vue)
  ↓
App.vue 执行 onLaunch
  ↓
pages.json 决定首页
  ↓
页面 onLoad / onShow

main.js 能干什么？

注册全局组件

js 复制代码

app.component('MyButton', MyButton)

这样你在任何页面都能直接用<MyButton />

挂载全局属性（常用）

js 复制代码

app.config.globalProperties.$api = api

页面中就可以：

js 复制代码

this.$api.login()

main.js 和 App.vue 的分工

main.js 负责"搭框架"

App.vue 负责"定规则"

文件	职责
main.js	创建应用、注册插件、全局能力
App.vue	onLaunch / onShow / 全局样式
页面	UI + 业务逻辑

uni-app全局文件

一、pages.json 页面路由

1.1 配置项列表

1.2 pages.json 是干什么的

1.3 pages.json 最核心的 3 大块

1.4 pages（页面注册，最重要）

1️⃣ 页面必须在这里注册，才能访问

2️⃣ 常用 page style 配置（你会经常改）

1.5 tabBar

1️⃣ 一旦进 tabBar，就 跳转规则完全变

1.6 globalStyle（全局样式）

1️⃣ 所有页面默认样式

1.7 subPackages（分包，项目稍大必用）

1.8 preloadRule（预加载，性能优化）

1.9 小总结

二、manifest.json 应用配置

manifest.json 是干什么的

三、App.vue/App.uvue

App.vue / App.uvue 是什么？

为什么不能在 App.vue 写视图模板？

App.vue / App.uvue 能做什么？

1、监听应用生命周期

2、定义全局数据 globalData

3、写 全局样式

App.vue / App.uvue 什么时候运行？

注意事项

四、main.js/main.uts

main.js / main.uts 是干嘛的？

为什么需要 main.js？

main.js（传统 uni-app，Vue）结构详解

最最常见的 main.js

整体执行流程

main.js 能干什么？

注册全局组件

挂载全局属性（常用）

main.js 和 App.vue 的分工

1️⃣ 一旦进 tabBar，就跳转规则完全变

3、写全局样式