企业官网建设流程全解析

• 示例工程
• 前端
• 移动开发
• 跨平台

导读：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) 还是 5+App / wap2app 项目，都需要连接真实的手机或手机模拟器来运行测试，这一开发方式统称为“真机运行”。

两个平台采用不同的设备连接协议：

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

真机运行的核心目的，是实现代码修改后的热刷新，避免每次修改都要重新打包才能看到效果。开发者只需在 HBuilderX 中编辑代码，手机上即可实时看到修改效果，并且可以在 HBuilderX 控制台看到日志输出。

运行入口：三种方式激活“运行到手机或模拟器”

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

1. HBuilderX 顶部运行菜单：点击顶部【运行】菜单，选择【运行到手机或模拟器】，可看到完整的运行子菜单，包含“运行到 Android App 基座”“运行到 iOS App 基座”等常见目标。
2. 工具栏运行按钮：相比顶部运行菜单，工具栏按钮下的运行菜单内容较少，只保留最常见的运行项。
3. 快捷键【Ctrl+r】：实际激活的是工具栏运行按钮。可以继续搭配数字键操作，实现无鼠标快捷运行。

操作技巧：运行菜单支持按数字键快速选择菜单项，例如按“4”选择“运行到 Android App 基座”；也可以按上下键后回车选择。这一交互设计可以让“Ctrl+r → 数字键”成为日常高频调试的肌肉记忆。

连接设备：选择界面与多设备管理

点击“运行到 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 配置；如果要自定义这些信息，则需要使用自定义运行基座。

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

1. uni-app 项目编译（5+ App / Wap2App 项目无需编译）；
2. 通过数据线给手机安装真机运行基座（需要手机屏幕高亮，并在手机端点击允许）；
3. 编译后的代码同步到手机设备上；
4. 启动手机端的真机运行基座，加载同步到手机的代码（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/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 等动态代码可以在运行基座上动态加载，实现热重载运行。其中 uni-app x 的 Android 端，uts 代码编译为 kt 后通过dex 动态加载来实现热刷新——这与传统 WebView 渲染架构的 App 有本质区别，是 uni-app x 原生渲染能力在调试阶段的体现（关于 uni-app x 的引擎架构可参考 README.md 中“App 平台使用原生渲染”的说明）。

系统版本要求（HBuilderX 3.7.1 版本调整）：

• Android 平台：要求 Android 5（API 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.uniappx；Capabilities（苹果开发者平台开启的能力）包括 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-client（uniCloud 云函数/云对象）、uni-createRequestPermissionListener、uni-createWebviewContext、uni-facialRecognitionVerify（实人认证）、uni-fileSystemManager、uni-location（system 系统定位 / tencent 腾讯定位）、uni-getNetworkType、uni-getProvider、uni-installApk、uni-media、uni-network（网络请求/文件上传下载）、uni-payment（alipay 支付宝 / 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 顶部【发行】菜单，或快捷键【Ctrl+u】。

打包自定义运行基座后，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+（仅 Android）：Android 通过离线 SDK 打包生成自定义基座后，如果基座已通过 Android Studio 的运行安装到手机中，可以在设备选择窗口选择“自定义基座-已安装基座”，并选择对应调试的包名。配置关联项目（打包离线 SDK 的原生工程项目）后，可以在 HBuilderX 中调试原生代码，即“原生联调”。

HBuilderX 4.81+（iOS）：iOS 通过离线 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 x，appid 为__UNI__HelloUniAppX，vueVersion: "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.modules：App 平台模块配置节点，这里声明的模块（如 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 x

uni-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 动态加载热刷新”这一调试机制能够成立的技术前提。

真机运行常见问题速查

掌握上述运行入口、设备连接、基座机制与日志定位方法后，即可在 Android / iOS 真机与模拟器上建立“改代码 → 热刷新 → 看日志”的高效调试闭环；当涉及包名、证书、权限、原生模块或三方 SDK 变更时，再切换到自定义基座链路，即可在不失调试能力的前提下验证完整的原生配置。

• 示例工程
• 前端
• 移动开发
• 跨平台