Skip to content

uni-app 入门:工程结构、运行机制与多端差异 ​

本篇要点:跑通第一个三端工程,能说清同一份代码在小程序、H5、App 上分别由谁渲染、生命周期何时触发、平台差异该写在哪一行。 前置:Vue 3 的组件与响应式要熟,HBuilderX 或 Node 环境备一个即可;这一章从零建工程,不假设你写过小程序。

为什么需要它 ​

一个社区团购项目上线前两天,四个故障堆在同一张群里。有人调了商品页底部按钮的边距,H5 上离底边 16px 很匀称,装到 iPhone 上被 Home 指示条压住一半。有人从列表点进详情、再点进规格、再点进评价,第四层按返回,直接跳回了首页。有人在 App 里写 localStorage.getItem('token'),控制台只回一句 localStorage is not defined,而同一个文件在小程序里编译不报错。第四个人把 document.querySelector 写进了工具函数,只有分享按钮会调它,测试没点到,发版三天后才被发现。

四件事看着不相干,往下追是同一件:没人说得清这行代码跑在哪个环境里。三端的解析器、渲染器、可用 API 各不一样,写代码时把它们当成一台机器,就会在这些地方翻车。

这一章要解决三件事:认得清工程里每个文件管什么;说得出同一份代码在三个端由谁渲染;知道平台差异允许写在哪一行。版本口径截至 2026 年 11 月:uni-app 的 Vue3 编译器以 npm 包发布,版本号是 3.0.0- 后接一段构建号,前几位与 HBuilderX 大版本对齐。升级用 npx @dcloudio/uvm@latest,手改 package.json 里的版本号,容易把编译器和运行时拆成两代。

核心概念 ​

工程结构:四个目录与两个入口 ​

src 下四个目录职责不同。pages 放页面,一个页面一个 .vue,路径就是 pages.json 里登记的路径;components 放自定义组件,按 easycom 约定,目录名与文件名相同就能免注册直接用;static 放原样拷贝、不参与编译的图片和字体;uni_modules 放从插件市场装的包,每个包自带 package.json,可以包含页面、组件和接口。

两个入口文件分工明确。App.vue 管应用级生命周期和全局样式,onLaunch、onShow、onHide 写在这里;main.js 负责创建应用实例,Vue 3 下用的是 createSSRApp 而不是 createApp,写成后者在小程序端会报错。

编译产物在 dist/dev/<平台>(HBuilderX 工程是 unpackage/dist/dev/<平台>)。小程序产物结构接近原生小程序,页面各自一套 wxml/wxss/js;H5 产物是一张 chunk 图;App 产物把逻辑打进 app-service.js。同一份源码三种产物结构,这条差异在《性能优化:setData、长列表与首屏加载》讲性能时还会用上。

运行时:谁解析 JS,谁画界面 ​

运行时(runtime)指代码真正执行时依赖的那套环境,包括谁来解释 JS、谁来画界面、两者能不能直接互相调用。

H5 只有一层,就是浏览器。JS 和 DOM 在同一个线程里,document、window、localStorage 都在手边。

微信小程序是两层。逻辑层(logic layer)跑在独立的 JS 引擎里,渲染层(render layer)是一叠 WebView,两层不共享内存,传数据要序列化。所以小程序里 document 是 undefined,window 也不是浏览器那个 window。

App 的 vue 页面是 WebView 加原生外壳。界面仍然由 WebView 画,相机、蓝牙、支付这类能力由 plus 运行时桥接过来。它有 DOM,但没有浏览器的地址栏,也没有真实的页面 URL。

图 1-1 同一份源码在三个端由谁渲染,差异落在哪一层

如图 1-1 所示,uni.* 是三端唯一重合的那一层。差异不在 Vue 代码里,在你伸手要能力的那一刻。

反例:在 utils/date.js 里写 document.cookie。编译期不报错,因为它是一句合法 JS;H5 上跑得好好的;小程序里只要调到这个函数就崩。它可能只被分享按钮调一次,于是崩在上线之后。

pages.json:页面是注册项,不是文件 ​

pages.json 是路由与窗口表现的唯一登记处。pages 数组的第一项就是启动页,跟文件叫不叫 index 没有关系。没进数组的页面,编译器直接忽略,不报错也不提示。

json
{
  "pages": [
    { "path": "pages/index/index", "style": { "navigationBarTitleText": "首页" } },
    { "path": "pages/mine/mine", "style": { "navigationBarTitleText": "我的" } }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarBackgroundColor": "#F8F8F8"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#3cc51f",
    "list": [
      { "pagePath": "pages/index/index", "text": "首页" },
      { "pagePath": "pages/mine/mine", "text": "我的" }
    ]
  }
}

运行结果:三端都只能访问这两个页面,底栏出现两个 tab。反过来试一次:在 pages 和 tabBar.list 里同时删掉「我的」,首页再写 uni.navigateTo({ url: '/pages/mine/mine' }),这次跳转会进 fail 回调,errMsg 是 navigateTo:fail page "/pages/mine/mine" is not found;H5 与小程序的文案略有出入,但都是 page not found。注意只删 pages 里的那条、留着 tabBar 的引用,构建会直接报错——两处配置必须一起改。

进了 tabBar 的页面只能用 switchTab 打开,用 navigateTo 会直接失败。这条约束来自小程序原生,H5 端框架照样执行,别指望在 H5 上绕过去。

生命周期与页面栈 ​

页面生命周期(page lifecycle)里最该先分清的是「一次」和「多次」。onLoad 在页面创建时触发一次,适合接参数、发首屏请求;onReady 在首次渲染完成后触发一次,此时才能取节点;onShow 每次页面出现在屏幕上都会触发,包括从下一层返回;onHide 在页面被盖住时触发;onUnload 在页面销毁时触发。

tab 页之间切换只触发 onShow 与 onHide,不会重新 onLoad。把「登录后刷新数据」写在 onLoad 里的项目,用户从登录页 switchTab 回来时看到的还是旧数据。

页面栈(page stack)是打开过的页面按顺序摞起来的结构。navigateTo 压栈,navigateBack 出栈,redirectTo 替换栈顶,reLaunch 清空重来。微信小程序的页面栈上限是 10 层,第 11 次 navigateTo 会失败。

路由 API对页面栈的动作典型场景容易踩的地方
uni.navigateTo压栈,保留当前页列表进详情超过 10 层失败,tab 页不能进
uni.navigateBack出栈,可指定层数返回上一页传 delta 时算错层数
uni.redirectTo替换栈顶详情换详情、登录跳首页替换后无法返回原页
uni.switchTab切到 tab 页并清掉非 tab 页底部导航不能传 query 参数
uni.reLaunch清空栈后打开退出登录、切账号目标页 onLoad 一定重跑
js
export default {
  onLoad(query) {
    console.log('[onLoad] 参数', JSON.stringify(query))
  },
  onShow() {
    console.log('[onShow] 页面可见')
  },
  onReady() {
    console.log('[onReady] 首次渲染完成')
  },
  onHide() {
    console.log('[onHide] 页面被盖住')
  },
  onUnload() {
    console.log('[onUnload] 页面销毁')
  }
}

运行结果(从首页 navigateTo 进这个页面,再点返回):

text
[onLoad] 参数 {"id":"1024"}
[onShow] 页面可见
[onReady] 首次渲染完成
[onHide] 页面被盖住        ← 再进下一层时
[onUnload] 页面销毁        ← 点返回时

开头那个「第四层返回跳回首页」的故障,根因是某次改版把页面跳转统一换成了 reLaunch,栈被清空了。另一个常见事故是把登录页当普通页面 navigateTo 进去,登录成功后再 navigateBack,用户点返回又能回到登录页。登录该用 reLaunch,让它待在栈底。

条件编译:构建期就删掉 ​

条件编译(conditional compilation)是在编译阶段按目标平台删掉源码片段,被删掉的代码不进产物,也不参与该平台的语法检查。

平台标识要背下来:H5、APP-PLUS(全部 App)、APP-ANDROID、APP-IOS、APP-HARMONY、MP(全部小程序)、MP-WEIXIN、MP-ALIPAY。支持 || 与 !,例如 // #ifdef H5 || APP-PLUS。

反例:把条件编译当运行时开关用。写成 if (uni.getSystemInfoSync().uniPlatform === 'web') 的分支会完整进入三端产物,体积照付,维护照担,而且它没法删掉一段 template。

动手实践 ​

第一步,建工程。命令行执行 npx degit dcloudio/uni-preset-vue#vite uniapp-ch1,或者用 HBuilderX「文件 → 新建 → 项目 → uni-app」选默认模板。预期输出:src/ 下同时有 App.vue、main.js、pages.json、manifest.json。manifest.json 在 src 里而不是项目根目录,这是 CLI 工程的标志;如果你在根目录看到它,说明用错了模板,后面所有配置都不会生效。

第二步,把所有平台差异收进一个文件。新建 src/adapter/share.js:

js
// 三端唯一的分享入口,业务侧只调 share()
export function share({ title, path }) {
  // #ifdef MP-WEIXIN
  uni.showShareMenu({ withShareTicket: true })
  return Promise.resolve({ mode: 'mp-menu', title, path })
  // #endif

  // #ifdef H5
  // H5 没有系统分享面板,交给调用方渲染自己的弹层
  return Promise.resolve({ mode: 'h5-panel', title, path })
  // #endif

  // #ifdef APP-PLUS
  const weixin = plus.share.getServices().find((s) => s.id === 'weixin')
  if (!weixin) return Promise.reject(new Error('未安装微信'))
  return new Promise((resolve, reject) => {
    weixin.send({ type: 'web', content: title, href: path }, resolve, reject)
  })
  // #endif
}

运行结果:三端都不会报函数未定义。小程序端返回 { mode: 'mp-menu' } 并弹出右上角菜单;H5 端返回 { mode: 'h5-panel' };App 端未装微信时在 catch 里拿到 Error: 未安装微信。plus 只在 APP-PLUS 分支里存在,把那段 #ifdef 去掉,H5 构建会在 plus.share 这行崩掉——这就是「构建期删除」和「运行期判断」的区别。

第三步,确认它在哪个端跑。新建页面后加一行:

js
const info = uni.getSystemInfoSync()
console.log('平台:', info.uniPlatform, '| 系统:', info.osName, '| 屏宽:', info.windowWidth)

运行结果:H5 打印 平台: web | 系统: mac | 屏宽: 1280(宽度随窗口变);微信开发者工具打印 平台: mp-weixin | 系统: ios | 屏宽: 375;App 真机打印 平台: app | 系统: android | 屏宽: 412。注意 uniPlatform 的值是 web 而不是 h5,写判断时别猜。

第四步,三端各跑一遍,对着同一个页面看差异。H5 用 HBuilderX「运行 → 运行到浏览器」,小程序用「运行 → 运行到小程序模拟器 → 微信开发者工具」,App 用「运行 → 运行到手机或模拟器」。三端跑完再改代码,比在 H5 上改十遍再去适配便宜得多。

调试工具按平台配。H5 直接用 Chrome DevTools,Network 与 Elements 面板和普通网页没区别;小程序用微信开发者工具的 Wxml、Storage、AppData 面板,console 落在调试器里;App 真机连 IDE 时日志常常只回一半,得靠打点或接 vConsole。日志里带上平台标识,三端对照同一段代码时能少猜一半的因果。

常见误解 ​

以为条件编译和 if 一样,写在哪都行。 它在构建期生效,所以 #ifdef APP-PLUS 里的语法错误,H5 构建根本发现不了;反过来,被删掉的 plus 在 H5 产物里不存在,也不会报 plus is not defined。CI 里只编一个端,等于另外两个端从来没被验证过。

以为 H5 能跑就是三端能跑。 H5 有 DOM、有真实 URL、换页靠 history,小程序三者都没有;同一个 navigateTo,在 H5 上像换页,在小程序里是压栈。习惯用 window.location 跳转的项目迁到小程序,第一件事通常是全仓搜索替换。

以为页面栈越深越好,能用 navigateTo 就不用 redirectTo。 栈深只买到「返回上一页」这一个能力,代价是内存、启动恢复的复杂度,和小程序 10 层的硬上限。列表进详情、详情再进详情,第二层详情通常该用 redirectTo 替换栈顶。

小结 ​

  • 三端只有 uni.* 这一层重合:H5 是浏览器,小程序是逻辑层加渲染层的双线程,App 是 WebView 加原生外壳。document、window、localStorage 都不是通用 API。
  • pages.json 决定哪些页面存在,数组第一项是启动页;进 tabBar 的页面只能 switchTab;四个路由 API 分别对应压栈、出栈、替换、清空。
  • 生命周期分一次与多次:onLoad、onReady 一次,onShow、onHide 每次;tab 页切换不重新 onLoad。
  • 条件编译在构建期删代码,不是运行时开关;平台标识写错不会报错,只会让整段分支静默消失。
  • 平台差异只写一个地方。业务代码里一行 #ifdef 都没有,这条纪律到《工程化:Vue3 + Vite、条件编译与分包》才讲得完整。

相关主题 ​

两个页面的工程怎么放都行,二十个页面、主包顶到 2MB 上限时就不行了。《工程化:Vue3 + Vite、条件编译与分包》 工程化:Vue3 + Vite、条件编译与分包 讲 CLI 与 HBuilderX 双轨结构、条件编译的四类载体怎么收敛,以及分包和体积预算怎么在流水线上被拦住。