Development
hbuilderx-cli
HBuilderX CLI 命令行工具技能。当用户需要通过命令行启动 uni-app 开发环境、查看运行日志、运行自动化测试、配置 HBuilderX CLI 环境，或在 npm scripts 中集成 HBuilderX 工作流时使用。覆盖 Web、Android、iOS、HarmonyOS、小程序等多平台开发。
HBuilderX CLI 命令行工具技能。当用户需要通过命令行启动 uni-app 开发环境、查看运行日志、运行自动化测试、配置 HBuilderX CLI 环境，或在 npm scripts 中集成 HBuilderX 工作流时使用。覆盖 Web、Android、iOS、HarmonyOS、小程序等多平台开发。
本技能覆盖 HBuilderX CLI 命令行工具（@dcloudio/hbuilderx-cli）。当用户需要通过命令行启动 uni-app 开发环境、查看平台日志、运行自动化测试或配置 HBuilderX CLI 时使用本技能。
HBuilderX CLI 是 DCloud 官方提供的命令行工具包装器，让开发者可以通过 npm scripts 或终端命令直接使用 HBuilderX 的各种功能，无需手动操作 IDE。
uni-launch 命令需要 HBuilderX 5.0+uni-logcat 和 uni-test 命令需要 HBuilderX 4.87+uni-test 需要先在 HBuilderX 中安装 uni-app 自动化测试插件当用户需要通过命令行启动 uni-app 开发、查看运行日志、运行测试、在 npm scripts 中集成 HBuilderX 工作流，或配置 HBuilderX CLI 环境时使用本技能。
典型触发场景：
示例调用：
用命令行启动 uni-app 的 Web 开发环境
配置 npm scripts 来运行 Android 和 iOS 开发
查看 Android 模拟器的运行日志
运行 uni-app 的 Web 自动化测试
解决 HBuilderX CLI 找不到的问题
Step 1. 确认环境 — 检查 HBuilderX 是否已安装并运行，确认版本满足要求
Step 2. 选择命令 — 根据需求选择 hbuilderx、uni-launch、uni-logcat 或 uni-test
Step 3. 配置平台参数 — 指定目标平台（web/app-android/app-ios/mp-weixin 等）和平台特有参数
Step 4. 执行与调试 — 运行命令，根据输出调整参数或排查问题
hbuilderx — 通用 CLI 包装器直接传递任意参数给 HBuilderX CLI。如果 HBuilderX 未运行，会自动启动。
# 检查版本
hbuilderx --version
# 打开项目
hbuilderx project open --path /path/to/project
# 启动 Web 开发
hbuilderx launch web --project /path/to/project
# 查看日志
hbuilderx logcat web --project /path/to/project
uni-launch — 开发环境启动⚠️ 需要 HBuilderX 5.0+
启动各平台开发环境，自动处理项目打开和 HBuilderX 启动。
uni-launch web # 使用内置浏览器
uni-launch web --browser Chrome # 指定 Chrome
uni-launch web --browser Safari # 指定 Safari
uni-launch web --compile true # 只编译不运行
uni-launch app-android # 默认设备
uni-launch app-android --deviceId emulator-5554 # 指定模拟器
uni-launch app-android --playground custom # 自定义基座
uni-launch app-android --native-log true # 显示原生日志
uni-launch app-android --continue-on-error true # 编译错误后继续
uni-launch app-ios --iosTarget device # 真机
uni-launch app-ios --iosTarget simulator # 模拟器
uni-launch app-ios --deviceId iPhone-15-Pro # 指定设备
uni-launch mp-weixin --runtime-log true # 微信小程序
uni-launch mp-alipay --runtime-log true # 支付宝小程序
uni-launch mp-toutiao --runtime-log true # 抖音小程序
uni-launch app-harmony # 默认设备
uni-launch app-harmony --deviceId emulator-5554 # 指定模拟器
uni-logcat — 日志查看⚠️ 需要 HBuilderX 4.87+
查看各平台运行日志，自动处理项目打开和 HBuilderX 启动。
uni-logcat web # Web 日志
uni-logcat app-android --deviceId emulator-5554 # Android 指定设备
uni-logcat app-ios --iosTarget device # iOS 真机
uni-logcat app-ios --iosTarget simulator # iOS 模拟器
uni-logcat mp-weixin # 微信小程序
uni-test — 自动化测试⚠️ 需要 HBuilderX 4.87+ ⚠️ 前置条件：必须先在 HBuilderX 中安装 uni-app 自动化测试插件
# Web 测试（支持 Chrome/Safari/Firefox，默认 Chrome）
uni-test web --testcaseFile tests/login.test.js
uni-test web --browser Chrome --testcaseFile tests/login.test.js
uni-test web --browser Safari --testcaseFile tests/login.test.js
uni-test web --browser Firefox --testcaseFile tests/login.test.js
# Android 测试（支持真机和模拟器）
uni-test app-android --device_id emulator-5554
# iOS 测试（仅支持模拟器）
uni-test app-ios --device_id iPhone-15-Pro
# HarmonyOS 测试（支持真机和模拟器）
uni-test app-harmony --device_id emulator-5554
| 平台 | uni-launch | uni-logcat | uni-test | |------|:----------:|:----------:|:--------:| | Web | ✅ | ✅ | ✅ Chrome/Safari/Firefox | | Android | ✅ 真机+模拟器 | ✅ | ✅ 真机+模拟器 | | iOS | ✅ 真机+模拟器 | ✅ | ⚠️ 仅模拟器 | | HarmonyOS | ✅ 真机+模拟器 | ✅ | ✅ 真机+模拟器 | | 微信小程序 | ✅ | ✅ | — | | 支付宝小程序 | ✅ | ✅ | — | | 抖音小程序 | ✅ | ✅ | — |
| 命令 | 最低 HBuilderX 版本 | 说明 |
|------|---------------------|------|
| hbuilderx | 任意版本 | 通用包装器，无版本限制 |
| uni-launch | 5.0+ | 开发环境启动命令 |
| uni-logcat | 4.87+ | 日志查看命令 |
| uni-test | 4.87+ | 自动化测试命令 |
检查 HBuilderX 版本：
cli --version
HBuilderX CLI 会自动检测已启动的 HBuilderX 进程，无需额外配置。
如果自动检测失败，设置 HBUILDERX_CLI_PATH 环境变量：
# macOS/Linux
export HBUILDERX_CLI_PATH="/Applications/HBuilderX.app/Contents/MacOS/cli"
# Windows (cmd)
set HBUILDERX_CLI_PATH="C:\Program Files\HBuilderX\cli.exe"
# Windows (PowerShell)
$env:HBUILDERX_CLI_PATH = "C:\Program Files\HBuilderX\cli.exe"
在 package.json 中配置常用命令：
{
"scripts": {
"hbuilderx": "hbuilderx",
"dev:web": "uni-launch web",
"dev:app-android": "uni-launch app-android",
"dev:app-ios": "uni-launch app-ios",
"dev:mp-weixin": "uni-launch mp-weixin",
"dev:mp-alipay": "uni-launch mp-alipay",
"dev:mp-toutiao": "uni-launch mp-toutiao",
"logcat:web": "uni-logcat web",
"logcat:app-android": "uni-logcat app-android",
"logcat:app-ios": "uni-logcat app-ios",
"test:web": "uni-test web",
"test:app-android": "uni-test app-android",
"test:app-ios": "uni-test app-ios"
}
}
使用 npm scripts：
npm run dev:web
npm run dev:app-android -- --deviceId emulator-5554
npm run logcat:web
npm run test:web -- --testcaseFile tests/login.test.js
npm install -g @dcloudio/hbuilderx-cli
全局安装后可直接使用 hbuilderx、uni-launch、uni-logcat、uni-test 命令。
npm install @dcloudio/hbuilderx-cli --save-dev
本地安装后通过 npm scripts 或 npx 使用。
| 问题 | 解决方案 |
|------|----------|
| command not found: hbuilderx | 确认已全局安装 npm install -g @dcloudio/hbuilderx-cli，或检查 PATH |
| 找不到 HBuilderX | 确保 HBuilderX 已启动，或手动设置 HBUILDERX_CLI_PATH 环境变量 |
| uni-launch 命令不可用 | 升级 HBuilderX 到 5.0+ 版本 |
| uni-logcat/uni-test 命令不可用 | 升级 HBuilderX 到 4.87+ 版本 |
| uni-test 找不到测试插件 | 在 HBuilderX 中安装 uni-app 自动化测试插件 |
| iOS 真机测试失败 | iOS 仅支持模拟器测试，不支持真机 |
| Android 设备未找到 | 检查 ADB 连接：adb devices，确认模拟器已启动或真机已连接 |
| HBuilderX 版本过低 | 通过 cli --version 检查版本，更新到最新版 |
| npm scripts 参数传递失败 | npm scripts 中传递参数需要加 --，如 npm run dev:web -- --browser Chrome |
| Windows 路径问题 | Windows 下 HBUILDERX_CLI_PATH 使用反斜杠或双引号包裹路径 |
| 用户类型 | 使用方式 | |----------|----------| | uni-app 开发者 | 通过命令行快速启动开发环境，替代手动操作 IDE | | CI/CD 工程师 | 在自动化流水线中集成 uni-app 构建和测试 | | 团队协作 | 统一团队的开发启动命令，通过 npm scripts 标准化工作流 | | 多平台开发者 | 一个工具链管理 Web/Android/iOS/小程序等多平台开发 |
自定义选项：
HBUILDERX_CLI_PATHuni-launch 需要 5.0+，uni-logcat 和 uni-test 需要 4.87+，使用前确认版本uni-test app-ios 不支持真机，这是平台限制而非工具限制uni-test 需要先在 HBuilderX 中安装自动化测试插件，否则命令会失败npm run 传递 CLI 参数必须加 -- 分隔符HBUILDERX_CLI_PATHQ: hbuilderx 和 uni-launch 有什么区别？
A: hbuilderx 是通用包装器，直接透传参数给 HBuilderX CLI；uni-launch 是专门的开发启动命令，自动处理项目打开和 HBuilderX 启动，且需要 HBuilderX 5.0+。推荐使用 uni-launch 进行日常开发。
Q: 如何在 CI/CD 中使用？
A: 全局安装 @dcloudio/hbuilderx-cli，确保 HBuilderX 已安装并在 PATH 中，设置 HBUILDERX_CLI_PATH 环境变量，然后在流水线脚本中调用 uni-launch 或 uni-test。
Q: 支持哪些小程序平台？ A: 支持微信小程序（mp-weixin）、支付宝小程序（mp-alipay）、抖音小程序（mp-toutiao）等主流小程序平台。
Q: 如何查看特定设备的日志？
A: 使用 --deviceId 参数指定设备，如 uni-logcat app-android --deviceId emulator-5554。iOS 使用 --iosTarget 参数区分真机和模拟器。
Q: 可以同时运行多个平台的开发环境吗？
A: 可以，每个平台命令独立运行。在不同的终端窗口中分别执行对应的 uni-launch 命令即可。
Q: Windows 下如何设置环境变量？
A: cmd 使用 set HBUILDERX_CLI_PATH="C:\Program Files\HBuilderX\cli.exe"，PowerShell 使用 $env:HBUILDERX_CLI_PATH = "C:\Program Files\HBuilderX\cli.exe"。建议将设置添加到系统环境变量中持久化。