示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载导读uni-app含 uni-app x由于手机设备差异较大HBuilderX 并未内置 App 模拟器任何 App 类项目的调试都必须依赖“真机运行”——连接真实手机或手机模拟器。本文以 docs/tutorial/run-app.md 为骨架系统讲解运行入口、设备连接、标准/自定义运行基座、运行流程与崩溃日志排查并结合当前开源仓库中的示例工程与标准基座文档docs/tutorial/app-playground.md、src/manifest.json做源码级佐证帮助你从零开始跑通 uni-app 在 Android / iOS 平台的热更新式开发调试链路。为什么需要“真机运行”因手机差异较大HBuilder 并没有提供 App 的模拟器。不管 uni-app (x) 还是 5App / wap2app 项目都需要连接真实的手机或手机模拟器来运行测试这一开发方式统称为“真机运行”。两个平台采用不同的设备连接协议Android 平台HBuilder 支持 adb 协议。在运行 HBuilder 的电脑上既可以使用 USB 线连接 Android 设备也可以使用安装在电脑上的 Android 模拟器包括 Google 官方模拟器以及“雷电”“夜神”等三方模拟器。iOS 平台HBuilder 支持 iTunes 协议。在运行 HBuilder 的电脑上使用 USB 线连接 iPhone 或 iPad如果是 Mac 电脑则可以连接 Xcode 自带的 iOS 模拟器如果是 arm 架构 CPU还可以直接启动真机运行基座。真机运行的核心目的是实现代码修改后的热刷新避免每次修改都要重新打包才能看到效果。开发者只需在 HBuilderX 中编辑代码手机上即可实时看到修改效果并且可以在 HBuilderX 控制台看到日志输出。运行入口三种方式激活“运行到手机或模拟器”通过 HBuilderX 顶部运行菜单、工具栏运行按钮、或快捷键均可激活运行入口。HBuilderX 顶部运行菜单点击顶部【运行】菜单选择【运行到手机或模拟器】可看到完整的运行子菜单包含“运行到 Android App 基座”“运行到 iOS App 基座”等常见目标。工具栏运行按钮相比顶部运行菜单工具栏按钮下的运行菜单内容较少只保留最常见的运行项。快捷键【Ctrlr】实际激活的是工具栏运行按钮。可以继续搭配数字键操作实现无鼠标快捷运行。操作技巧运行菜单支持按数字键快速选择菜单项例如按“4”选择“运行到 Android App 基座”也可以按上下键后回车选择。这一交互设计可以让“Ctrlr → 数字键”成为日常高频调试的肌肉记忆。连接设备选择界面与多设备管理点击“运行到 iOS 或 Android 设备”时会弹出设备选择界面需选择要连接的手机设备或模拟器。多设备运行规则可以多设备同时运行每个运行设备会在 HBuilderX 底部控制台新开一个独立窗口互不干扰但一个设备同时只能运行一个项目不同的项目运行到同一台手机时只有最后一个项目生效。无线连接HBuilderX 4.71 版本Android 设备支持无线连接设备USB 之外的新增方式。连接设备过程中如果找不到手机可以尝试点击“刷新”按钮如果仍然无法找到手机则需按真机运行常见问题逐项排查数据线、驱动、USB 调试开关等。Android 设备选择注意事项如果电脑里安装有模拟器Android 模拟器需要先启动HBuilderX 会直接检测到设备并显示在候选列表中确认 Android 手机设置中USB调试模式已开启。通常在手机的【设置】→【开发者选项】里有的手机在插上数据线后也可以在系统通知栏里设置。注意不能设置为 U 盘模式如果是充电模式则必须同时设置充电时允许usb调试。iOS 设备选择iOS 平台有一个特殊背景需要注意HBuilderX 中自带的标准真机运行基座使用 DCloud 向苹果申请的企业开发者证书签名。根据苹果开发者企业计划许可协议要求使用企业开发者证书签名的 App 只允许企业员工内部使用不允许企业外部人员安装使用。因收到苹果公司警告自 2022 年 9 月 14 日起iOS 真机设备不再支持使用标准真机运行基座。因此在 iOS 真机设备上运行请向苹果申请证书制作自定义基座或者在 Mac 电脑上使用 iOS 模拟器。注意事项确保 USB 线的连接通畅有些数据线质量不佳需使用高电压 USB 端口如果无法识别请尝试更换数据线如果 Windows 电脑连接 iOS 设备需安装 iTunes 软件并确保 Apple 的 Mobile Device 服务开启、iTunes 可找到手机手机连接电脑后确保在手机上弹出的“要信任此电脑吗”提示框中点了“信任”按钮。iOS 模拟器设备选择仅 Mac 电脑支持安装 Xcode 后“标准运行基座”支持使用 iOS 模拟器iOS 模拟器非常多设备选择界面会额外显示搜索框可通过搜索框过滤快速选择需要使用的模拟器。运行到设备完整流程与热更新机制初次运行时会提示安装“真机运行插件”。该插件内置“标准运行基座”此基座使用 DCloud 的包名、证书和三方 SDK 配置如果要自定义这些信息则需要使用自定义运行基座。在运行菜单中选择要运行的手机设备或模拟器点击运行按钮后会执行如下流程uni-app 项目编译5 App / Wap2App 项目无需编译通过数据线给手机安装真机运行基座需要手机屏幕高亮并在手机端点击允许编译后的代码同步到手机设备上启动手机端的真机运行基座加载同步到手机的代码iPhone 手机需手动点击桌面图标启动。运行成功后的开发体验运行成功后HBuilderX 底部的控制台显示成功日志。此后修改代码会差量同步到手机上手机程序会动态热刷同时console.log代码会打印到控制台上点击打印日志可以跳转到相关代码。注意uni-app x 的 web-view 组件网页日志和错误从 HBuilderX 4.51 开始支持同步显示到控制台。iOS 真机自动启动HBuilderX 3.7.0 版本运行 App 项目到 iOS 真机运行成功后手机上的 App 会自动打开目前仅支持 MacOSX不支持 Windows。前提是 MacOSX 需要安装跟 iOS 手机系统相匹配的 Xcode 版本——例如 iPhone 手机系统是 iOS 16.2也需要安装支持 iOS 16.2 的 Xcode 版本。如果/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport目录下不存在与手机系统相匹配的 iOS Platforms则无法自启动 App需在手机端点击运行基座图标手动启动。可以使用如下命令查看 Xcode iOS Platforms 数据ls -lh /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupportMacOSX 下无法自动启动 App 时请排查以下原因iOS 手机系统没有匹配 Xcode 版本手机处于息屏状态项目编译运行失败、或安装基座失败。标准运行基座低门槛调试的默认方案标准运行基座是 DCloud 为方便开发者低门槛调试而提供的此基座 App 使用的是 DCloud 的包名、证书和三方 SDK 配置uni-app / 5App 的标准基座包名为io.dcloud.HBuilder图标为绿色 Huni-app x 的标准基座包名为io.dcloud.uniappx图标为绿色 U。热重载原理在原生层不变的情况下js 等动态代码可以在运行基座上动态加载实现热重载运行。其中 uni-app x 的 Android 端uts 代码编译为 kt 后通过dex 动态加载来实现热刷新——这与传统 WebView 渲染架构的 App 有本质区别是 uni-app x 原生渲染能力在调试阶段的体现关于 uni-app x 的引擎架构可参考 README.md 中“App 平台使用原生渲染”的说明。系统版本要求HBuilderX 3.7.1 版本调整Android 平台要求 Android 5API Level 21及以上系统。如需在 Android 4.4 设备真机运行请使用自定义基座更多 App 支持的最低版本设置可参考 docs/tutorial/adapt.md 中关于最低系统版本的内容iOS 平台要求 iOS 10 及以上系统。如需在 iOS 9.* 设备真机运行请使用自定义基座App 支持的最低版本设置参考manifest.json的deploymentTarget配置。标准基座的签名与能力仓库佐证仓库中的 docs/tutorial/app-playground.md 对 app 平台标准基座做了更完整的说明是理解“标准基座”边界的关键文档Android 标准基座信息包名io.dcloud.uniappx签名 SHA256 为5975dd84fbd6648be4afdfe4cc3025b4c9f8eb6131519e44ff15511a0ab9a7d3、SHA1 为71544e0a6f064614e83f6ad2a4f318df349c1295、MD5 为957764ac1b55e0c38bae22ba2a145b98注册的 Url Scheme 为uniappx。iOS 标准基座信息包名io.dcloud.uniappxCapabilities苹果开发者平台开启的能力包括 Access Wi-Fi Information、Associated Domains、Push Notifications、Sign In with Apple、Time Sensitive Notifications注册 Url Scheme 为uniappx注册通用链接为https://uniappx.dcloud.net.cn/ulink。注意iOS 平台标准基座需要重签名才能使用重签名后会改变包名信息从而导致注册的通用链接失效。标准基座包含的功能模块uni-ad广告联盟含腾讯优量汇 gdt、uni-canvas、uni-cloud-clientuniCloud 云函数/云对象、uni-createRequestPermissionListener、uni-createWebviewContext、uni-facialRecognitionVerify实人认证、uni-fileSystemManager、uni-locationsystem 系统定位 / tencent 腾讯定位、uni-getNetworkType、uni-getProvider、uni-installApk、uni-media、uni-network网络请求/文件上传下载、uni-paymentalipay 支付宝 / wxpay 微信、uni-push统一推送、uni-verify一键登录、uni-video、uni-virtualPayment虚拟支付、uni-websocket。由此可见标准基座内置了大多数常用 API 与三方 SDK开发者无需配置原生环境即可调用这些能力对应的 API 细节可进一步阅读 docs/api/request.md、docs/api/get-location.md、docs/api/request-payment.md、docs/api/websocket-global.md 等文档。Android 平台权限Android 平台标准基座尽量包含所有可能用到的权限以便在开发过程中可调用所有系统 API包括网络权限INTERNET、ACCESS_NETWORK_STATE、存储卡权限WRITE_EXTERNAL_STORAGE、定位权限ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION、ACCESS_BACKGROUND_LOCATION、ACCESS_LOCATION_EXTRA_COMMANDS、蓝牙权限BLUETOOTH、BLUETOOTH_SCAN、BLUETOOTH_CONNECT、前台 Service 权限FOREGROUND_SERVICE、安装应用权限REQUEST_INSTALL_PACKAGES以及相机、通讯录、短信、电话、NFC 等大量其它权限完整权限清单见 docs/tutorial/app-playground.md。这也解释了为什么标准基座能让几乎所有 uni API 在调试期“开箱即用”。仓库示例工程 src/AndroidManifest.xml 同样声明了权限集合而示例工程 src/package.json 的dcloudext.declaration.permissions字段中还列出了对外发布时声明的权限如 INTERNET、定位、相机、媒体读取等可与基座权限形成对照。使用自定义基座运行何时需要与如何生成为什么需要自定义基座标准基座仅能更新热刷代码和资源文件其他诸如修改包名、应用名称、证书、权限、原生模块变更、xml 等资源变更、引入三方 SDK等需要完整执行 Android / iOS 的打包流程由 Android Studio 或 Xcode 编译打包生成 apk 或 ipa 安装包才能生效。但真正打包为正式包又无法调试——不能热重载、不能显示控制台日志。所以 HBuilderX 在运行打包时提供了一个特殊选项“自定义运行基座”。自定义运行基座可以让所有配置生效主要是manifest.json的配置包括App 名称、图标、封面 splash、包名、证书App 模块配置、三方 SDK 配置如微信、推送、地图、语音识别等三方 SDK 配置App 权限配置引入原生插件 / SDK其他manifest.json文档提到的需打包生效的配置。可以云打包自定义基座也可以本地打包自定义基座。云打包自定义基座使用云打包开发者不必配置原生打包环境。uni-app 打包自定义基座点击 HBuilderX 顶部【发行】菜单 → 打包 App → 在弹出的对话框中选择“自定义调试基座仅用于真机运行”然后开始云打包uni-app x 打包自定义基座同样在【发行】菜单中进入打包 App 界面选择自定义调试基座后打包打包 App 的入口在 HBuilderX 顶部【发行】菜单或快捷键【Ctrlu】。打包自定义运行基座后HBuilderX 会自动将生成的 apk / ipa / app 包存放在项目目录/unpackage/debug目录下文件名分别为android_debug.apk、iOS_debug.ipa、Pandora_simulator_debug.app。注意一个项目只能生成一个自定义基座多次生成只保留最后一次结果生成自定义基座后在设备选择窗口选择“自定义基座-本地基座”自定义运行基座必须在 HBuilderX 中真机运行使用不可直接安装使用直接安装启动时会弹出 toast 提示信息正式发版时需按正常打包方式重新打包HBuilderX 3.7.13 起MacOSX 系统 App 项目支持运行自定义基座到 iOS 模拟器。离线打包自定义基座离线打包方式适用于需要本地原生环境参与调试的场景按版本演进有三种模式HBuilderX 4.71 之前使用离线 SDK 打包生成自定义运行基座不支持 cli 方式需将 src 拖拽到编辑器中并重新识别项目类型。生成后将 apk / ipa / app 包存放在项目目录/unpackage/debug目录下文件名分别为android_debug.apk、iOS_debug.ipa、Pandora_simulator_debug.app然后在设备选择窗口选择“自定义基座-本地基座”。HBuilderX 4.71仅 AndroidAndroid 通过离线 SDK 打包生成自定义基座后如果基座已通过 Android Studio 的运行安装到手机中可以在设备选择窗口选择“自定义基座-已安装基座”并选择对应调试的包名。配置关联项目打包离线 SDK 的原生工程项目后可以在 HBuilderX 中调试原生代码即“原生联调”。HBuilderX 4.81iOSiOS 通过离线 SDK 打包生成自定义基座后选择“自定义基座-原生工程基座”。配置基座位置打包离线 SDK 的原生工程项目的产物后可以在 HBuilderX 中调试原生代码。上述离线打包与原生联调的详细步骤属于 App 原生工程范畴可参考 docs/native/README.md 与 docs/plugin/uts-plugin.md 了解 uni-app x 原生插件与离线工程的组织方式。从示例工程看 manifest.json 的基座相关配置当前仓库的 src/manifest.json 即是一个典型的 uni-app x 工程配置Hello uni-app xappid 为__UNI__HelloUniAppXvueVersion: 3。其中可以看到与真机运行 / 打包直接相关的关键节点{ name: Hello uni-app x, appid: __UNI__HelloUniAppX, versionName: 2.0.1, versionCode: 20001, uni-app-x: { vapor: true, styleIsolationVersion: 2 }, vueVersion: 3, app: { distribute: { modules: { uni-ad: { gdt: {} } } } } }versionName/versionCode应用版本名称与版本号在自定义基座与正式打包时都会写入原生工程app.distribute.modulesApp 平台模块配置节点这里声明的模块如 uni-ad 及其 gdt 腾讯优量汇配置正是标准基座已内置、自定义基座需要按需勾选的那部分三方 SDK该文件还包含app-android、app-harmony、web、mp-weixin等平台的分平台配置节点与基座的平台差异一一对应。当你在自定义基座中修改上述配置例如调整包名、勾选模块、配置三方 SDK key后需要重新执行云打包或离线打包生成新的自定义基座才能让配置生效——这正是“标准基座 vs 自定义基座”的分界线。基座闪退崩溃日志的获取与定位真机运行调试中遇到基座闪退时可通过以下路径定位崩溃日志uni-app 的 Android 平台默认标准基座闪退查看手机存储根目录/Android/data/io.dcloud.HBuilder/logs/io.dcloud.HBuilder/crash/崩溃日志文件自定义基座闪退查看手机存储根目录/Android/data/packageName/logs/packageName/crash/崩溃日志文件其中packageName为 apk 包名。例如 apk 包名是uni.UNIB89CXX目录则为/Android/data/uni.UNIB89CXX/logs/uni.UNIB89CXX/crash/。注意并不是所有崩溃都能被捕获并保存成文件此路径仅能覆盖框架可捕获的崩溃场景。uni-app xuni-app x 的闪退日志有多种查看方式运行控制台右上角勾选原生日志可以直接查看在应用的沙盒目录下 cache 缓存目录的uni-crash目录查看标准基座和自定义基座均可uni-app x 标准基座包名为io.dcloud.uniappx。文件系统与缓存目录的规范可参考 docs/api/file-system-spec.md。线上崩溃统计不管是 uni-app 还是 uni-app x线上应用还可以通过 uni 统计查看崩溃日志用于收集已发布版本的崩溃情况uni 统计的接入说明见 docs/uni-push/v2.md 所在文档体系。从仓库视角理解真机运行在整个项目中的位置文档体系本文所讲的 Android / iOS 真机运行是 App 平台调试的主线鸿蒙平台的运行与发行DevEco Studio 工具链、模拟器、证书签名等则是另一套独立的流程详见 docs/tutorial/runbuild.md两者在 docs/_sidebar.md 中相邻编排便于对照阅读。示例工程src/ 目录即为 hello-uni-app-x 示例工程uni-app x 主分支的演示项目其中的 src/manifest.json、src/pages.json、src/AndroidManifest.xml 是运行到真机时的实际工程配置样本examples/hello-uts 与 examples/hello-uvue 则分别演示 uts 与 uvue 两种开发范式在真机上的运行效果。项目定位从 README.md 可知uni-app x 是本仓库主分支其 App 引擎采用原生渲染架构这也正是“标准基座 dex 动态加载热刷新”这一调试机制能够成立的技术前提。真机运行常见问题速查现象排查方向设备列表中找不到手机点击“刷新”检查 USB 调试是否开启、是否为 U 盘模式、数据线/端口是否正常Android 模拟器不可见确认模拟器已先启动再打开设备选择窗口Windows 连不上 iPhone/iPad安装 iTunes 并确保 Apple Mobile Device 服务开启手机提示连接但无法安装基座确保屏幕高亮并在手机端点击“允许”安装iOS 真机无法使用标准基座2022-09-14 起 iOS 真机不再支持标准真机运行基座需自定义基座或 iOS 模拟器iOS 自动启动失败MacXcode 版本与手机系统不匹配、息屏、编译或安装基座失败闪退无日志uni-app 查看 crash 目录uni-app x 勾选原生日志或查看沙盒 uni-crash 目录修改了包名/证书/三方 SDK 不生效标准基座仅支持热刷代码与资源此类配置变更需重新打包自定义基座掌握上述运行入口、设备连接、基座机制与日志定位方法后即可在 Android / iOS 真机与模拟器上建立“改代码 → 热刷新 → 看日志”的高效调试闭环当涉及包名、证书、权限、原生模块或三方 SDK 变更时再切换到自定义基座链路即可在不失调试能力的前提下验证完整的原生配置。赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐如何编译 Go 并在 iOS 模拟器与真机上运行标准库测试如何编译 Go 并在 iOS 模拟器与真机上运行标准库测试 如果你的任务是把 Go 源码树编译到 iOS 目标上并验证标准库测试能在 iOS 模拟器或真机上编程语言编译器语言运行时标准库并发编程Playwright 移动端真机测试Android/iOS 设备连接与自动化Playwright 移动端真机测试Android/iOS 设备连接与自动化 引言告别模拟器痛点拥抱真机测试新范式 你是否还在忍受移动端模拟器测试的三大痛测试开发工具浏览器控制Nx React Native run-ios 执行器完全指南从模拟器到真机的 iOS 启动方案Nx React Native run ios 执行器完全指南从模拟器到真机的 iOS 启动方案 导读 本文聚焦 Nx 仓库中 nx/react nativ开发工具构建工具MonorepoCLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考