简介：基于5+ App、Mui与HBuilder的H5移动应用示例工程，面向需要快速上手DCloud跨平台开发的前端学习者，以实际代码解决官方文档零散、示例不足带来的起步困扰。项目通过完整页面与脚本演示了HTML5离线存储与本地存储、CSS3动画与Flexbox布局、ES6异步编程、Mui组件调用、5+ App原生API以及Ajax数据交互等关键知识点，也覆盖移动端屏幕适配、触摸手势、页面路由和表单处理，有助于理解从Web代码到Android/iOS安装包的打包链路。压缩包为zip格式，共13个文件，以js、html、css三类代码文件为主，辅以ttf字体、manifest.json工程配置和README说明，整体仅123KB，结构紧凑、目录清晰，便于通过HBuilder直接导入运行并二次修改。该资源已有831人浏览学习，作为一套轻量入门范例，可帮助开发者快速搭建包含登录页面、页面跳转和原生交互的H5应用雏形，并获得真实的Mui样式调整、API调用与打包发布参照。
1. 一个 H5 项目为什么要专门打包：5+ App 要解决的实际问题
周五下午产品扔过来一句话：三天后要有一版能装进手机的 App。后端接口是现成的，页面也是现成的 mui 模板改好的 H5 应用，就差一层能调用相册、能打包出安装包的外壳。用 HBuilder 配合 5+ Runtime 把这套 H5 应用包起来，是成本最低的一条路——页面不用重写，plus.* 接口补上原生能力就行。这份资源适合两类人：手里有 H5 页面想快速出壳的前端，以及想搞明白 JS 怎么和原生 API 打交道的人。它解决不了复杂的原生性能优化，但能让你用最熟悉的 JavaScript 把应用从浏览器搬进手机终端。
2. 技术选型拆解：mui、5+ Runtime 与 HBuilder 是怎么协作的
2.1 mui 在工程里负责哪一层
打开模板首页，能看到大量>h5app/ ├── manifest.json ├── index.html ├── css/ │ ├── mui.css │ └── app.css ├── js/ │ ├── mui.js │ ├── app.js │ └── bridge.js ├── pages/ │ ├── detail.html │ └── setting.html └── images/
manifest.json 是整个项目的配置中心，App 的标识、权限、图标、启动图都在这里登记，打包工具只认这个文件。css 和 js 目录里，mui.css/mui.js 是框架本体，app.css/app.js 是业务入口，bridge.js 通常是二次开发时用来封装 plus 调用的一层（第六章会给封装样板）。pages 放二级页面，index.html 是首页，对应主 WebView，pages 下的页面由它用 mui.openWindow 拉起来。images 存静态资源。
理解这个结构有个关键点：这是一个多页面应用，不是 SPA。每个 html 是一个独立 WebView，页面之间靠 extras 传参、靠 mui.fire 广播事件，而不是全局状态管理。习惯 Vue/React 的人第一次看会觉得原始，但这是 WebView 方案的常态，也是后面所有坑的根源——两个 WebView 之间没有共享的 window 对象，一切通信都要通过 Runtime 中转。
3.2 入口初始化：mui.init 与 mui.plusReady 的执行顺序
首页的入口代码长这样：
mui.init({ statusBarBackground: '#f7f7f7', gestureConfig: { swipe: true }, preload: { id: 'index', url: 'index.html' } }); mui.plusReady(function() { var info = plus.device.getInfo(); console.log('设备型号: ' + info.model); window.plusReadyFlag = true; document.dispatchEvent(new CustomEvent('app-ready')); });mui.init 负责初始化 UI 组件和手势配置，statusBarBackground 设置状态栏背景色，gestureConfig 开启滑动手势，preload 预加载首页 WebView。mui.plusReady 是 5+ Runtime 就绪的回调，只有在这个回调里调用 plus.* 才是安全的。这里我把就绪状态通过 window.plusReadyFlag 暴露出去，再派发一个 app-ready 自定义事件，业务代码可以等这个事件再初始化数据请求。
这里有一个执行顺序的常见误区：mui.init 和 mui.plusReady 谁先执行取决于页面加载路径。模板里通常先 mui.init，再注册 plusReady；但如果在页面顶部直接同步调用 plus 代码，大概率会拿到 undefined。所以依赖原生能力的初始化放回调里，不依赖的就放普通 DOMContentLoaded 里，两者按职责分开，别混在一起。
3.3 mui.openWindow：页面跳转与参数传递
二级页面的打开方式：
mui.openWindow({ url: 'pages/detail.html', id: 'detail', styles: { top: '0px', bottom: '0px' }, extras: { orderId: 1024 }, createNew: false });参数含义如下表：
| 参数 | 作用 | 说明 |
|---|---|---|
| url | 页面路径 | 相对 index.html 的路径 |
| id | WebView 标识 | 相同 id 不重复创建，会复用已有页面 |
| styles | 新页面 WebView 的尺寸位置 | top/bottom 控制覆盖区域 |
| extras | 传给新页面的自定义参数 | 新页面通过 window.xxx 读取 |
| createNew | 是否强制新开 | false 时复用已存在的页面 |
新页面读取参数的姿势是直接读 window 上的属性。因为 extras 会被 5+ Runtime 注入到新页面的 window 对象上，所以在 detail.html 里 window.orderId 就能读到 1024。但这里有个时序问题：新页面 WebView 创建、页面 JS 执行、extras 注入之间存在异步间隙，赶早了读到 undefined。做这个项目的人几乎都在这踩过坑，我自己的做法是统一在 mui.plusReady 里读，第五章会展开讲。
提示：createNew 传 false 时，相同 id 的页面会被复用，旧页面的状态会保留。做列表页跳详情再返回的场景，这种复用机制能省不少内存，但也容易造成"详情页数据不刷新"的假象，判断时要留意。
3.4 典型原生能力封装：选图后走上传链路
业务里最常见的原生调用是选图片、传服务器。完整链路如下：
function chooseAndUpload() { if (!window.plus) { alert('请在 5+ 环境下运行'); return; } plus.gallery.pick(function(e) { // e.files 是选中的文件路径数组 var localPath = e.files[0], file = plus.io.convertLocalFileSystemURL(localPath); var task = plus.uploader.createUpload( 'https://api.example.com/upload', { method: 'POST' }, function(t, status) { if (status === 200) { console.log('上传成功: ' + t.responseText); } else { console.log('上传失败, 状态码: ' + status); } } ); task.addFile(file, { key: 'file' }); task.start(); }, function(err) { console.log('用户取消或出错: ' + err.message); }, { multiple: false, system: false }); }这段代码串起了三个 plus 模块。plus.gallery.pick 打开系统相册，第一个回调里 e.files 是路径数组，第二个回调是取消或出错时的兜底，第三个参数是配置项，multiple 控制是否多选，system 控制是否调用系统相册界面。拿到路径后要做一次 convertLocalFileSystemURL 转换，因为相册返回的是 local:// 开头的虚拟路径，上传器只认转换后的真实路径。plus.uploader.createUpload 创建上传任务，addFile 把文件挂到表单字段 key 上，start 启动传输。
注意一个细节：plus.gallery.pick 的取消操作也会走错误回调，所以 err.message 偶尔是"用户取消"而不是真错误，业务代码要区分。另外部分定制 ROM 上相册返回路径格式有差异，开发时先 console.log(e.files) 看结构再继续，我就在这上面翻过车。
4. 跑起来：从 HBuilder 到真机的完整调试流程
4.1 把手上的源码变成可运行工程
拿到源码后，第一步不是看代码，而是在 HBuilder 里把工程跑起来。新建一个 5+ App 项目，会生成一份包含 mui 的模板；如果手上有现成源码，用导入功能选择目录即可，关键判别条件是根目录存在 manifest.json 且字段完整。导入后 HBuilder 会按 manifest.json 解析出应用图标、名称和权限清单，这一步解析失败基本是 JSON 语法问题，编辑器右下角会有错误提示。
我一般会先把 manifest.json 里的基础信息检查一遍：应用名称、版本号、应用标识。版本号在后续每次发布都要递增，标识在云打包和更新时会被服务端使用，别拿默认值直接出包。如果导入后页面样式错乱，先看 mui.js 和 mui.css 是否完整，再确认页面引用的路径大小写和目录结构是否一致，这两类问题占了"跑不起来"的大半。
4.2 内置预览与真机调试怎么配合
HBuilder 自带的内置浏览器适合快速看 UI 布局和页面跳转效果，但它不是 5+ Runtime，plus.* 在那儿完全不存在，业务代码一旦走到 plus 调用就会报错。所以开发节奏我建议这样：静态 UI 用内置预览调，涉及原生能力的逻辑直接真机验证。
真机运行的步骤：
- 手机开启开发者选项里的 USB 调试
- 用数据线连接电脑，在 HBuilder 菜单选择"运行到手机或模拟器"
- 首次运行会自动往手机安装一个调试基座，这个基座就是完整的 5+ Runtime
- 之后每次保存，代码会同步到手机，页面自动刷新
真机验证时，console.log 的输出会打到 HBuilder 的控制台，网络请求也能在这里看到。遇到页面白屏，先看控制台有没有 JS 报错，多半是某个 plus 模块调用时机不对。如果提示找不到设备，先检查数据线是否支持数据传输、手机有没有弹授权窗口，这两点是连接失败的常见原因。
注意：调试基座和最终安装包是两个应用。基座默认开放全部权限，所以调试阶段相机、相册都能用；正式包只认 manifest.json 里勾选的权限，这个问题放到 4.3 单独说。
4.3 打包发布前的配置检查清单
打包前要过一遍 manifest.json 的可视化界面，关键配置如下：
| 配置项 | 作用 | 踩坑点 |
|---|---|---|
| 应用标识 | 应用的唯一 ID | 发布后不建议改，改了会被当成新应用 |
| 版本名称 | 展示给用户的版本号 | 每次发版递增 |
| 权限配置 | 声明要用的原生权限 | 漏勾相机权限，plus.camera 会直接失败 |
| 图标与启动图 | 安装包外观 | 不同尺寸屏的图都要配齐 |
权限配置是最容易被忽略的一环。很多开发者在代码里写了 plus.camera.captureImage()，真机调试时能用，打包后就失效——因为调试基座默认所有权限都开，正式包只按 manifest.json 里的勾选打包。所以发布前一定要对着功能清单过一遍权限，把用到的模块对应权限全部勾上，宁可多勾不要少勾。
打包方式分两种：云打包不需要本地装 Android SDK，配置好后在 HBuilder 里提交，远端构建完成后下载安装包，优点是省事，缺点是排队耗时且依赖网络；离线打包适合有原生开发能力、需要深度定制的场景，要本地准备 SDK 工程再把 H5 资源放进去，工程量明显更大。个人项目或团队内部工具用云打包就足够。
安装包出来之后，至少要在三台不同品牌安卓机上各跑一遍完整流程，有条件的话 iOS 端也过一遍。重点回归首次启动、权限弹窗、页面跳转、返回键这四项。这些环节在调试基座里都正常，不代表正式包里一定正常，权限差异就是最大的变量。
5. 避坑指南：5 个最常见的 H5 App 开发问题与排查方法
5.1 新页面里 plus 对象时有时无
现象：页面跳转后立刻调用 plus.device.getInfo()，控制台报 "plus is not defined"，过一会儿重试又正常。
原因：5+ Runtime 在页面加载完成后才把 plus 注入 window 对象，页面 JS 同步执行阶段它还不存在。这是 WebView 初始化时的时序问题，不是业务代码写错了，常见于用 setTimeout 延迟执行的场景。
解决：所有依赖 plus 的代码放进 mui.plusReady 回调。如果业务里大量异步逻辑不便套回调，可以封装一个 Promise 化的等待函数：
function ready() { return new Promise(function(resolve) { if (window.plus) { resolve(); return; } document.addEventListener('plusready', resolve, false); }); }调用侧就变成 ready().then(function(){ /* 使用 plus */ })。这个函数建议放进 js/bridge.js，所有页面共用。排查时先在控制台输入 typeof plus 看当前状态，如果返回 object 说明 Runtime 已就绪，问题在代码执行时机；如果是 undefined 说明还没注入，把调用挪进回调即可。
5.2 Android 返回键直接退出应用
现象：在二级页面按手机返回键，应用没回到上一页，直接退到桌面。
原因：5+ Runtime 对返回键的默认处理是结束应用，不会自动按页面栈回退。mui 模板里如果没有显式接管返回键，用户在任何页面按返回，等价于直接退出，体验上就是"被强制关闭"。
解决：在入口页面监听返回键，按页面栈深度分发：
plus.key.addEventListener('backbutton', function() { var pages = plus.webview.all(); if (pages.length > 1) { plus.webview.close(pages[pages.length - 1]); } else { plus.runtime.quit(); } });这段代码的意思是：页面栈里还有二级页面就关闭栈顶，只剩首页才真正退出。实际项目里如果要做"再按一次退出"的交互，把 else 分支换成时间戳判断即可。注意这个监听要注册在不会被关闭的入口页面，否则页面被关掉后监听也跟着失效。
5.3 extras 参数在新页面读到 undefined
现象：页面跳转时通过 mui.openWindow 传 extras，新页面同步读取 window.orderId 偶尔拿到 undefined，多刷新几次又好了。
原因：extras 注入新页面 window 的时机晚于页面 JS 执行，同步读必然有时序风险。这种随机复现的问题最难排查，因为它只在页面加载慢、WebView 创建延迟时才暴露，表现为"有时候正常，有时候白屏"。
解决：把读取动作统一放进 mui.plusReady，页面内所有逻辑用状态驱动：
mui.plusReady(function() { var orderId = window.orderId || 0; if (!orderId) { mui.toast('缺少订单参数，返回重试'); return; } loadOrderDetail(orderId); });这样即使参数缺失，页面也有明确的兜底行为，而不是静默白屏。顺手养成的习惯是：所有传参不直接依赖同步读取，统一走一个 getPageParam(name) 函数，内部做存在性校验和默认值兜底。
5.4 真机上改的代码不生效
现象：IDE 里改了页面代码，保存后真机还是旧页面，有时清了缓存、重启应用才恢复。
原因：调试基座和部分手机 WebView 有各自的缓存策略，或者上一次运行的进程没有完全退出，旧代码被缓存读了出来。这是工具链层面最常见的问题，跟业务代码无关，别一上来就怀疑自己改错。
解决：HBuilder 的运行菜单里有"清除缓存并重新运行"选项，遇到不生效先点这个。更彻底的做法是杀掉手机上的调试基座进程，再重新运行。排查时先确认当前手机上跑的是调试基座而不是正式打包的安装包——这两个是不同应用，正式包不会收到运行同步，很多人改了半天代码不生效，其实是开着旧安装包在测。
5.5 部分安卓机型相册选择回调不触发
现象：plus.gallery.pick 弹出相册，选完图片后没有任何回调输出，同一套代码在 iOS 上正常。
原因：部分厂商定制 ROM 对相册文件路径的返回格式与标准实现不一致，或者回调触发时页面 WebView 已经被系统回收。这类问题在低内存机型、连续多次选图时更容易出现。
解决：第一步把 e.files 打印出来，对照不同机型的返回结构；第二步不要用匿名函数持有长生命周期上下文，避免页面被回收后回调丢失；第三步如果实在兼容不了，降级方案是隐藏一个 input[type=file] 走普通文件选择，虽然界面不如系统相册美观，但回调链路稳定。机型适配没有一劳永逸的答案，遇到一台处理一台，把已验证的机型记进测试清单就好。
6. 二次开发改造：把模板壳变成业务 App 的三步走
改造思路一句话：不动 mui 模板本身，所有 plus 调用收进 bridge.js，业务页面只和 bridge 打交道。第一步在 js/bridge.js 里加一个 Promise 化的能力样板：
window.bridge = { pickImage: function(multiple) { return new Promise(function(resolve, reject) { plus.gallery.pick(function(e) { resolve(e.files); }, reject, { multiple: !!multiple, system: false }); }); } };第二步，业务页面不再直接写 plus.*，改成 bridge.pickImage().then(...)。好处是页面代码可测试、可复用，真机环境切换时只需要改 bridge 这一层；第三步，每新增一个 bridge 方法，先在 plusReady 之后手动调用一次确认回调触发，再接业务页。这个方法同样适用于摄像头、文件上传等场景。
动手前可以列一张回归清单：首页加载、二级页面跳转、返回键、相册选择、网络请求、退出应用，每改一个模块就对着清单过一遍，成本很低但能拦住大部分回归。从那以后我每次新增业务页面都强制走一遍"先在 bridge.js 暴露方法、再让页面只调 bridge"的流程，真机上的玄学问题少了大半。希望帮到你。
本文还有配套的精品资源，点击获取
