uniapp App平台 真机运行

因手机差异较大,Hbuilder 并没有提供App的模拟器,不管Uni-app(x) 或 5+app/wap2app 项目 ,都需要链接真实的手机或手机模拟器来运行测试,称之为"真机运行"

• Android平台 Hbuilder支持adb协议,在Hbuilder运行的电脑上,可以使用usb线连接Android设备,也可以使用模拟器包括(google官方模拟器,三方模拟器如"雷电",夜神)等
• ios平台支持itunes协议,在Hbuilder运行的电脑上,使用usb链接iphone或ipad; 如果是max电脑,则可以连接XCode自带的IOS模拟器,如果是arm架构cpu,还可以直接启动真机运行基座

真机运行的目的,是为了实现代码修改的热刷新,避免打包才能看到效果,在Hbuilder中编辑代码,在手机上实时看到修改效果,并且可以在hbuilder控制台看到日志

一. 运行入口

通过HBuilder顶部运行菜单、或工具栏运行按钮、或快捷键，均可激活运行入口。

1. HBuilder顶部运行菜单

1. 工具栏运行按钮

可以按数字快速选择菜单项。比如按"4"选择"运行到Android App基座"。也可以按上下键然后回车选择。

相比于HBuilder顶部运行菜单，工具栏运行按钮下的运行菜单内容较少，只保留了最常见的运行。

1. 快捷键【Ctrl+r】

实际上激活了工具栏运行按钮。可继续搭配数字键，实现无鼠标快捷运行操作。

二. 连接设备

点击运行到iOS或Android设备时，会弹出选择界面，需选择要连接的手机设备或模拟器。

可以多设备运行，每个运行设备会在HBuilder底部控制台新开一个独立窗口，互不干扰。 但一个设备同时只能运行一个项目，不同的项目运行到相同手机只有最后一个项目生效。

HBuilderX 4.71+版本，Android设备支持无线连接设备。

连接设备过程中如果找不到手机，可以尝试点击"刷新"按钮，如果还是无法找到手机请参考真机运行常见问题

Android设备选择

注意:

• 如果电脑里安装有模拟器(Android模拟器需要先启动) ,hbd会直接检测设备并显示在候选列表中 ,可以参考如何安装模拟器
• 确认Android手机设置中USB调试模式已开启,注意不能设置为u盘模式,如果是充电模式则必须同时充电时允许usb调试

iOS设备选择

HbuildxX中自带的标准真机运行基座使用DCloud向苹果申请的企业开发者证书签名,根据苹果开发者企业计划许可协议要求,使用企业开发者证书签名的App只允许企业员工内部使用,不允许企业外部人员安装使用

因收到苹果公司警告,自2022年9月14日起IOS真机设备不再支持使用标准真机运行基座

在IOS真机设备上运行请向苹果申请证书指定自定义基座或者在Mac电脑上使用IOS模拟器

注意事项

• 确保usb线的连接通常(有些数据线质量不佳,需使用高电压usb端口,如果无法识别的时候请尝试更换数据线)
• 如果windows电脑连接IOS设备需电脑安装ITunes软件,并确保apple的mobile device服务开启,ITunes可找到手机
• 手机连接电脑后,确保在手机上弹出的"要新人此电脑吗?" "提示框中点了"信任""按钮

IOS模拟器设备选择

如果是Mac电脑安装XCode后,"标准运行基座" 支持使用IOS模拟器,此功能仅Mac电脑支持

如果未安模拟器可以参考如何安装模拟器

运行到设备

初次运行时会提示安装"真机运行插件";

改插件内置"标准运行基座",这个基座使用的是DCloud的包名,证书和第三方SDK配置,如果要自定义,则需要使用自定义运行基座

在运行菜单中选择要运行的手机设备或模拟器，点击运行按钮，会执行如下流程：

1. uni-app项目编译（5+ App/Wap2App项目无需编译）
2. 通过数据线给手机安装真机运行基座（需要手机屏幕高亮并在手机端点击允许）
3. 编译后的代码同步到手机设备上
4. 启动手机端的真机运行基座，加载同步到手机的代码（iPhone手机需手动点击桌面图标启动）

运行成功后，HBuilder底部的控制台显示成功日志。此后修改代码会差量同步到手机上，手机程序会动态热刷。同时console.log代码会打印到控制台上，点击打印日志可以跳转到相关代码。

Hbuilder X 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/DeviceSupport

MacOSX,如果无法自动启动App,请排查以下原因:

IOS 手机系统没有匹配Xcode 版本

手机处于息屏状态

项目编译运行失败,或安装基座失败

三. 使用标准基座运行

标准运行基座, 是DCloud为方便开发者低门槛调试而提供的,此基座App使用的是DCloud的包名,证书,和三方SDK配置

uni-app / 5+App的标准基座的包名为: io.dcloud.Hbuilder, 图标为绿色H

uni-app x的标准基座包名为: io.dcloud.uniappx 图标为绿色U

在原生层不变的情况下,js等动态代码可以在运行基座上动态加载,实现热重载运行(uniapp x 的Android端,uts代码编译为kt后通过dex动态加载来实现热刷新)

HBuilderX3.7.1版本调整标准基座支持的系统版本

• Android平台 要求Android5（API Leavel 21）及以上系统，如需在Android4.4设备真机运行，请使用自定义基座。更多App支持的最低版本设置参考文档
• iOS平台 要求iOS10及以上系统，如需在iOS9.*设备真机运行，请使用自定义基座。更多App支持的最低版本设置参考manifest.json的deploymentTarget

四. 使用自定义基座

标准基座仅能更新热刷代码和资源文件,其他诸如修改包名,应用名称,证书,权限,原生模块变更,xml等资源变更,引入三方sdk等,需要完整的执行Android/IOS的打包流程,由Android studio或XCode编译打包生成apk或ipa安装包,才能生效

但真的打包为正式包,又无法调试,不能热重载和现实控制日志,所以Hbuilder在运行打包时提供了一个特殊选项 "自定义运行基座"

自定义运行基座可以所有配置生效(主要是Manifest.json的配置),包括:

app名称,图标,封面splash,包名,证书

App模块配置,三方sdk配置(如微信,推送,地图,语音识别等三方sdk配置)

App权限配置

引入原生插件/sdk

其他manifest.json文档提到的需打包生效的配置

可以云打包自定义基座,也可以本地打包自定义基座

1. 标准基座（官方默认）

DCloud 提前编译好的 Android/iOS 原生壳子，所有人都用同一套。

• 没有自定义原生代码
• 只有 uni 基础插件（定位、网络、文件、基础权限）
• 权限、配置、启动页、图标都是默认

能用场景

1. 只用 uni 自带 API，不加任何原生插件
2. 不改 AndroidManifest、Info.plist、权限、系统配置
3. 简单 H5 套壳、普通业务、不需要硬件深度调用

缺点

不能加第三方原生插件（蓝牙、串口、NFC、离线复杂权限、内网特殊权限）

• 不能修改原生代码、权限、启动页逻辑
• 不适合你水利内网、GIS、特殊硬件、自定义权限项目

---

2. 自定义基座（你项目必用）

是什么

基于官方基座，自己编译 / 打包一个专属原生壳，可以：

• 加第三方原生插件（uniapp 原生插件市场）
• 修改 AndroidManifest.xml 权限、网络安全配置（内网 http 白名单）
• 改启动页、开屏广告、应用图标、包名、签名
• 加串口、蓝牙、USB、文件读写、离线权限、后台保活

什么时候必须用

1. 你用了 原生插件（GIS、串口、蓝牙、PDF 预览、文件管理）
2. 内网项目需要 允许 http 请求、网络安全配置
3. 需要自定义权限、后台保活、特殊硬件能力
4. 真机调试、运行必须和打包 APK 环境一致

核心优势：调试环境 = 打包环境

自定义基座调试出来什么样，打包出来就什么样，不会出现：

调试正常，打包后闪退 / 权限失效 / 插件不生效

---

3. 最核心区别（直接背）

表格

对比项	标准基座	自定义基座
原生插件	❌ 不支持	✅ 支持
权限 / 配置修改	❌ 不能改	✅ 可改
内网 http 兼容	❌ 默认禁止	✅ 可放开
调试 & 打包一致性	不一致，容易出问题	完全一致
适用项目	简单通用项目	你的水利 GIS / 内网项目必用

---

4. 结合你项目的选型结论（最重要）

你做的：

• 水利 GIS、2D 地图、雨情水情大屏
• 内网部署、离线使用
• 可能要文件上传下载、PDF 预览、特殊权限

必须用 自定义基座标准基座根本满足不了，会出现：插件不生效、内网请求失败、权限不足、闪退。

五. 云打包自定基座

使用云打包，开发者不必配置原生打包环境。

• uni-app 打包自定义基座

uni-app x 打包自定义基座

打包自定义运行基座后，HBuilder会自动将生成后的apk或ipa或app包存放在 项目目录/unpackage/debug目录下，文件名分别为android_debug.apk或iOS_debug.ipa或Pandora_simulator_debug.app。

一个项目只能生成一个自定义基座，多次生成只保留最后一次结果。

生成自定义基座后，在设备选择窗口，选择自定义基座-本地基座，如下图所示：

注意: 自定义运行基座必须在HbuilderX中真机运行使用,不可直接安装使用,启动时会弹出toast提示信息,正式发版时需要按正常打包方式重新打包

离线打包自定基座

• Android平台离线生成自定义调试基座(uni-app)
• Android平台离线生成自定义调试基座(uni-app x)
• iOS平台离线生成自定义调试基座(uni-app)
• iOS平台离线生成自定义调试基座(uni-app x)

使用离线SDK打包生成自定义运行基座(不支持cli方式,讲src拖拽到编辑器中,并重新识别项目类型),生成后将apk或ipa或app包存放在项目目录 / unpackage / debug目录下,文件名分别为android_debug.apk,IOS_debug.ipa

可以在设备选择窗口，选择自定义基座-本地基座，如下图所示：

Android通过离线SDK打包生成的自定义基座后,如果基座已通过Android Studio的运行安装到手机中,可以在设备选择窗口,选择自定义基座-已安装基座,并选择对应调试的包名,如下图所示

配置关联项目后，可以在HBuilderX中调试原生代码。关联项目为打包离线SDK的原生工程项目，详细使用请参考原生联调（仅uni-app x）

iOS通过离线SDK打包生成的自定义基座后，选择自定义基座-原生工程基座。如下图所示：

配置基座位置后，可以在HBuilderX中调试原生代码。基座位置为打包离线SDK的原生工程项目的产物，详细使用请参考原生联调（仅uni-app x）

基座闪退获取日志

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 x

uni-app x的闪退日志有多种查看方式。

• 运行控制台右上角勾选原生日志，可以查看
• 在应用的沙盒目录下cache缓存目录的uni-crash目录查看。 详见。标准基座和自定义基座均可，uni-app x的标准基座的包名为io.dcloud.uniappx。

不管是uni-app还是uni-app x，线上应用还可以通过uni统计查看崩溃日志。