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

uni-app H5端使用注意事项【跨端开发系列】

news 2026/2/5 15:22:41

🔗 uniapp 跨端开发系列文章：🎀🎀🎀

uni-app 组成和跨端原理【跨端开发系列】
uni-app 各端差异注意事项【跨端开发系列】
uni-app 离线本地存储方案【跨端开发系列】
uni-app UI库、框架、组件选型指南【跨端开发系列】
uni-app 蓝牙开发【特别专题】
uni-app 导航栏开发指南【跨端开发系列】
uni-app 原生控件层级过高无法覆盖的解决方案【跨端开发系列】
uni-app 设置缓存过期时间【跨端开发系列】

一、介绍 🎯

uni-app 是一个使用 Vue.js 开发所有前端应用的框架，开发者编写一套代码，可发布到iOS、Android、Web（响应式）、以及各种小程序（微信/支付宝/百度/头条/飞书/QQ/快手/钉钉/淘宝）、快应用等多个平台。

uni-app在开发者数量、案例、跨端抹平度、扩展灵活性、性能体验、周边生态、学习成本、开发成本等8大关键指标上拥有更强的优势。

二、功能框架图 📋

从下面 uni-app 功能框架图可看出， uni-app 在跨平台的过程中，不牺牲平台特色，可优雅的调用平台专有能力，真正做到海纳百川、各取所长。

三、使用方式 📖

打开 uni-app 项目下的 vue 文件。
点击菜单运行-> 运行到浏览器 -> Chrome 。
在 Chrome 內打开 调试模式（右键->检查）开启 设备模拟 ，模拟移动设备。
HBuilderX 修改代码后会自动刷新 chrome 的页面。
审查元素，每个页面都在 page 节点下，pageHead 是微信和 app 下的原生导航栏，即 pages.json 里配的导航栏。pageBody 是导航栏下的页面内容。所有标签为了避免和标准H5标签冲突，都加了 U前缀。
断点 debug ，点 chrome 控制台的 source ，可以给 js 打断点调试。
找到同名的文件，如果没有同名 vue 文件，一般会有一个同文件名的 js 文件，此时会提示检测到 sourcemap ，是否引入，点允许。然后就会有同名的 vue 文件。如果找不到，则把焦点放到 source 的代码区，然后敲 ctrl+p 打开文件查找窗口，然后敲入 vue 页面名字，然后打开 vue 页面。这个 vue 里，只有 js，没有 tag 和 css ，但可以打断点调试。

四、发布方式📤

配置发行后的路径（发行在网站 根目录 可不配置），比如发行网站路径是www.xxx.com/html5，在 manifest.json 可视化界面 - H5配置 - 运行的基础路径中设置，也可以在源码视图内编辑 h5 节点， router 下增加 base 属性为 html5 。可视化界面设置：

源码视图设置：

点击菜单发行 -> H5 。
在当下项目下的 unpackage/dist/build/h5 目录找到出的资源，部署服务器（或者使用本地服务器预览，不要直接在浏览器打开html文件）。如果发布使用的 history 模式，需要服务端配合，参考：后端配置方式。

五、跨端注意🪡

uni-app由 uni 的通用 api 和平台专有 api 组成，H5版也不例外。可以使用 uni 的通用 api 完成很多工作，也可以在条件编译里调用 H5版的浏览器专有api。

🚫虽然 dom、window 都可以用了，但如果要跨端，还是少写这样的代码好。
🚫强烈不建议使用浏览器的~~跳转页面的api~~ 。
✅H5仍应该使用 pages.json 管理页面。
✅H5的 条件编译 写法是把之前的 app-plus 换成 H5 。敲 ifdef 会有代码助手提示。

//#ifdef H5  
this.titleHeight = 44  
//#endif

🔸条件编译目前有 7 个平台，APP-PLUS、APP-PLUS-NVUE、MP-WEIXIN、H5、MP、MP-BAIDU、MP-ALIPAY。

🔸其中 APP-PLUS-NVUE 是 APP-PLUS 的子集，用于 weex 下单独写专用代码。
为了方便多平台选择，还引入了 ~#ifndef~ ，也就是 ifdef 的 not ，反向选择。以及或语法，及||。

🔸这些命名都是c语言条件编译的标准命名。

// #ifndef H5  
console.log("这段代码编译到非H5平台");  
// #endif

开发者之前为微信或 app 写的代码，H5的平台不支持时，需要注意把这些代码放到条件编译里。
经过这样的处理，之前做好的App或小程序才能正常运行到H5版里。

小程序版在UI上，尤其是导航栏上限制较多，H5在这里是参考了app，默认解析了pages.json下的app-plus的节点，实现了titleNView、buttons、下拉刷新（下拉刷新只有circle方式，因为只有这样的下拉刷新在H5版上可以保障流畅体验）

六、组件和API支持情况✅

目前的H5版，还没有100%实现uni的所有api，但大部分已经完成，具体参考uniapp文档。

七、第三方组件支持 ✅

支持 mpvue 组件
支持普通 vue 组件（仅H5平台）
支持微信小程序组件（HBuilderX2.5.0+开始支持编译到H5）
支持 nvue

八、vue语法支持 ✅

H5版支持完整的vue语法，同时校验器也校验了更严格的vue语法，有些写法不规范会报警。比如data后面写对象会报警，必须写 function 。

九、注意事项（必看）🔎

编译为H5版后生成的是单页应用，SPA。如果想要 seo 优化，首页可以在 template模板中配置 keyword 。二级页不支持配置。但一个更酷的方式是用 uni-app 直接发布一版百度小程序，搜索权重更高。
编译后看日志和错误，要看浏览器的控制台，~~而不是HBuilderX的控制台~~。浏览器的控制台会有错误提示。
网络请求（request、uploadFile、downloadFile等）在浏览器存在跨域限制（CORS、Cross-Origin），解决方案详见：uni-app H5跨域问题解决方案（CORS、Cross-Origin） - DCloud问答
APP 和微信的原生导航栏和 tabbar 下，元素区域坐标是不包含 原生导航栏和 tabbar 的。而 H5 里原生导航栏和 tabbar 是 div 模拟实现的，所以元素坐标会包含 导航栏和 tabbar 的高度。为了优雅的解决多端 高度定位 问题，uni-app 新增了2个 css 变量： --window-top 和 --window-bottom ，这代表了页面的内容区域距离顶部和底部的距离。举个实例，如果你想在原生 tabbar 上方悬浮一个菜单，之前写 bottom:0 。这样的写法编译到 h5 后，这个菜单会和tabbar 重叠，位于屏幕底部。而改为使用 bottom:var(--window-bottom)，则不管在app下还是在h5下，这个菜单都是悬浮在 tabbar 上浮的。这就避免了写条件编译代码。当然你也仍然可以使用 H5 的条件编译处理界面的不同。
CSS內使用 vh 单位的时候注意 100vh 包含导航栏，使用时需要减去导航栏和 tabBar 高度，部分浏览器还包含浏览器操作栏高度，使用时请注意。
event 对象上使用的 mpvue 独有的属性需调整（比如 event.pageY，可能需要加上44px的导航栏高度）。
fixed 定位的组件有可能遮挡框架内置UI组件，如果不希望遮挡可以分平台判断，在H5平台避开内置UI。
正常支持 rpx 。px是真实物理像素。🚫暂不支持通过设 manifest 的 "transformPx" : true ，把px当动态单位使用。
使用 罗盘、地理位置、加速计 等相关接口需要使用 https 协议，本地预览（localhost）可以使用 http 协议。
PC 端 Chrome 浏览器模拟器设备测试的时候，获取定位 API 需要连接谷歌服务器，需要翻墙。
组件内（页面除外）🚫不支持 onLoad 生命周期。
为避免和内置 组件冲突，自定义组件请 加上前缀（但不能是 u 和 uni ）。比如可使用的自定义组件名称：my-view、m-input、we-icon，🚫例如不可使用的自定义组件名称：u-view、uni-input。如果已有项目使用了可能造成冲突的名称，请修改名称。另外 微信小程序 下自定义组件名称不能以wx 开头。
在 tabBar 页面，如果 page 高度设置为100%时，页面超出滚动会导致底部被 tabbar 遮挡，可在 tabbar 页面去掉 height:100% 或者改用 min-height:100% 。
编写组件时需要遵守vue的规范，之前在app端和小程序端能使用的一些不规范写法需要纠正，比如：🚫不要修改 props 的值、🚫组件最外层 template 节点下不允许包含多个节点。
开发App时，🚫不可在H5预览后直接云打包。需在HBuilderX里点运行-选择运行到手机，真机调试无误后再打包。
H5端 “网络不给力” 原因及解决办法：https://ask.dcloud.net.cn/article/37065。