uni-app

Expand All

因手机差异较大，HBuilder并没有提供App的模拟器。不管uni-app (x)或5+App/wap2app项目，都需要连接真实的手机或手机模拟器来运行测试，称之为“真机运行”。

Android平台 HBuilder支持adb协议，在HBuilder运行的电脑上，可以使用usb线连接Android设备，也可以使用安装在电脑上的Android模拟器（包括google官方模拟器，三方模拟器如“雷电”、“夜神”等）
iOS平台 HBuilder支持itunes协议，在HBuilder运行的电脑上，使用usb线连接iPhone或iPad；如果是mac电脑，则可以连接XCode自带的iOS模拟器。如果是arm架构cpu，还可以直接启动真机运行基座。

The purpose of running the real machine is to realize the hot refresh of code modification and avoid packaging to see the effect. Edit the code in HBuilder, see the modification effect in real time on the mobile phone, and you can see the log in the HBuilder console.

# Run entry

The run entry can be activated through the run menu at the top of HBuilder, the run button on the toolbar, or a shortcut key.

HBuilder顶部运行菜单

Toolbar run button

Menu items can be quickly selected by number. For example, press "4" to select "Run to Android App Dock". You can also press the up and down keys and then enter to select.

Compared with the run menu at the top of HBuilder, the run menu under the run button on the toolbar has less content, and only the most common runs are reserved.

快捷键【Ctrl+r】

Actually activates the toolbar run button. You can continue to match the number keys to achieve quick operation without a mouse.

# connect device

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

可以多设备运行，每个运行设备会在HBuilder底部控制台新开一个独立窗口，互不干扰。 But a device can only run one project at the same time, and when different projects run to the same mobile phone, only the last project takes effect.

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

If you can't find your phone during the process of connecting the device, you can try to click the "Refresh" button. If you still can't find your phone, please refer to Real Phone Running FAQs

# Android设备选择

注意事项

如果电脑里安装有模拟器（Android模拟器需要先启动），HBuilder会直接检测到设备并显示在候选列表中。可以参考如何安装模拟器
Make sure the USB debugging mode is turned on in the Android phone settings. Usually in the [Settings] [Developer Options] of the mobile phone, some mobile phones can also be set in the system notification bar after plugging in the data cable. Note that it cannot be set to U disk mode. If it is charging mode, you must set the charging time at the same time. Allow usb debugging.

# iOS设备选择

HBuilderX中自带的标准真机运行基座使用DCloud向苹果申请的企业开发者证书签名，根据苹果开发者企业计划许可协议要求，使用企业开发者证书签名的App只允许企业员工内部使用，不允许企业外部人员安装使用。因收到苹果公司警告，自2022年9月14日起iOS真机设备不再支持使用标准真机运行基座，详情见论坛公告：https://ask.dcloud.net.cn/article/40041 在iOS真机设备上运行请向苹果申请证书制作自定义基座或者在Mac电脑使用iOS模拟器

注意事项

确保usb线的连接通畅（有些数据线质量不佳，需使用高电压usb端口，如果无法识别时候请尝试更换数据线）
如果windows电脑连接iOS设备需电脑安装iTunes软件，并确保apple的mobile device服务开启、iTunes可找到手机
手机连接电脑后，确保在手机上弹出的“要信任此电脑吗？”提示框中点了“信任”按钮

# iOS模拟器设备选择

如果是Mac电脑安装XCode后，“标准运行基座”支持使用iOS模拟器

点击后进入iOS模拟器选择界面

上面的界面会额外显示搜索框，因XCode的iOS模拟器非常多，可通过搜索框过滤快速选择需要使用的模拟器。

# run

When you run it for the first time, you will be prompted to install the "real machine running plug-in".

The plugin has a built-in "Standard Run Dock", which uses DCloud's package name, certificate and third-party SDK configuration. If you want to customize, you need to use custom playground

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

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

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

注意：uni-app x 的 web-view 组件网页日志和错误从 HBuilderX 4.51+ 开始支持同步显示到控制台。

# Run the project to the iOS real machine App to start automatically

Currently only supports MacOSX, not Windows

HBuilderX 3.7.0+ version, newly added to run the App project to the real iOS device, after running successfully, the App on the phone will be opened automatically.

As shown below:

Note: MacOSX needs to install the Xcode version that matches the iOS phone system. For example, if the iPhone system is iOS 16.2, you also need to install an Xcode version that supports iOS 16.2. If there is no iOS Platforms that matches the mobile phone system in /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport directory, then the App cannot be launched automatically. Please click the running dock icon on the mobile phone to start it manually.

Use the following command to view Xcode iOS Platforms data.

ls -lh  /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport

On MacOSX, if the App cannot be started automatically, please check the following reasons:

The iOS phone system does not match the Xcode version
The mobile phone is in the off-screen state
Failed to compile and run the project, or failed to install the base

# 使用标准基座运行

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

uni-app/5+App的标准基座的包名为：io.dcloud.HBuilder。图标为绿色H。
uni-app x的标准基座包名为：io.dcloud.uniappx。图标为绿色U。

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

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

Android平台要求Android5（API Leavel 21）及以上系统，如需在Android4.4设备真机运行，请使用自定义基座。更多App支持的最低版本设置参考文档
iOS平台 Requires iOS10 and above. If you need to run on iOS9.* devices, please use a custom dock. For more minimum version settings supported by App, refer to [deploymentTarget] of manifest.json (https://uniapp.dcloud.net.cn/collocation/manifest-app.html#ios)

# 使用自定义基座运行

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

但真的打包为正式包，又无法调试，不能热重载和显示控制台日志。所以HBuilder在运行打包时提供了一个特殊选项，“自定义运行基座”。

自定义运行基座可以所有配置生效（主要是manifest.json的配置），包括：

App名称、图标、封面splash、包名、证书
App module configuration, third-party sdk configuration (such as WeChat, push, map, voice recognition, etc. third-party sdk configuration)
App权限配置
引入原生插件/SDK
Configurations mentioned in other manifest.json documents that need to be packaged to take effect

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

# 云打包自定基座

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

uni-app 打包自定义基座

uni-app x 打包自定义基座

打包App的入口在HBuilder顶部发行菜单，或快捷键【Ctrl+u】

After packaging the custom runtime base, HBuilder will automatically store the generated apk and ipa packages in the project directory/unpackage/debug directory, and the file names are android_debug.apk and iOS_debug.ipa respectively.

Only one custom pedestal can be generated for a project, and multiple generation only keeps the last result.

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