HBuilderX CLI Reference

本技能覆盖 HBuilderX CLI 命令行工具（@dcloudio/hbuilderx-cli）。当用户需要通过命令行启动 uni-app 开发环境、查看平台日志、运行自动化测试或配置 HBuilderX CLI 时使用本技能。

HBuilderX CLI 是 DCloud 官方提供的命令行工具包装器，让开发者可以通过 npm scripts 或终端命令直接使用 HBuilderX 的各种功能，无需手动操作 IDE。

Capability Boundaries

✅ Strong Suits

1. 通过命令行启动 Web、Android、iOS、HarmonyOS、小程序等多平台开发环境
2. 实时查看各平台运行日志（logcat）
3. 运行 uni-app 自动化测试（Web/Android/iOS/HarmonyOS）
4. 在 npm scripts 和 CI/CD 流程中集成 HBuilderX 工作流
5. HBuilderX CLI 环境检测与配置（自动/手动）

⚠️ Requirements

1. 必须已安装 HBuilderX（CLI 会自动检测运行中的 HBuilderX 进程）
2. uni-launch 命令需要 HBuilderX 5.0+
3. uni-logcat 和 uni-test 命令需要 HBuilderX 4.87+
4. uni-test 需要先在 HBuilderX 中安装 uni-app 自动化测试插件
5. iOS 真机开发需要有效的 Apple 开发者证书

❌ Out of Scope（及替代方案）

1. HBuilderX IDE 本身的使用和配置 → 使用 HBuilderX 官方文档
2. uni-app 应用代码编写 → 使用对应的前端框架技能（vue3、vue2 等）
3. 原生插件开发 → 使用 HBuilderX 原生插件开发文档
4. 云端打包和发布 → 使用 uni-app 云端打包文档
5. 非 uni-app 项目的构建工具 → 使用对应的构建技能（webpack、vite 等）

When to use this skill

当用户需要通过命令行启动 uni-app 开发、查看运行日志、运行测试、在 npm scripts 中集成 HBuilderX 工作流，或配置 HBuilderX CLI 环境时使用本技能。

典型触发场景：

• "怎么用命令行启动 uni-app 的 Web 开发？"
• "如何通过 npm scripts 运行 Android 模拟器？"
• "怎么查看 uni-app 的运行日志？"
• "uni-test 怎么配置？"
• "HBuilderX CLI 找不到怎么办？"

Quick Start

示例调用：

用命令行启动 uni-app 的 Web 开发环境
配置 npm scripts 来运行 Android 和 iOS 开发
查看 Android 模拟器的运行日志
运行 uni-app 的 Web 自动化测试
解决 HBuilderX CLI 找不到的问题

Workflow

Step 1. 确认环境 — 检查 HBuilderX 是否已安装并运行，确认版本满足要求

Step 2. 选择命令 — 根据需求选择 hbuilderx、uni-launch、uni-logcat 或 uni-test

Step 3. 配置平台参数 — 指定目标平台（web/app-android/app-ios/mp-weixin 等）和平台特有参数

Step 4. 执行与调试 — 运行命令，根据输出调整参数或排查问题

Critical: Command Coverage Map

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 启动。

Web 平台

uni-launch web                          # 使用内置浏览器
uni-launch web --browser Chrome         # 指定 Chrome
uni-launch web --browser Safari         # 指定 Safari
uni-launch web --compile true           # 只编译不运行

Android 平台

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  # 编译错误后继续

iOS 平台

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   # 抖音小程序

HarmonyOS 平台

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

Critical: Platform Support Matrix

Critical: Version Requirements

检查 HBuilderX 版本：

cli --version

Critical: Environment Configuration

自动检测（推荐）

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"

Critical: npm scripts Integration

在 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

Installation

全局安装（推荐）

npm install -g @dcloudio/hbuilderx-cli

全局安装后可直接使用 hbuilderx、uni-launch、uni-logcat、uni-test 命令。

本地安装

npm install @dcloudio/hbuilderx-cli --save-dev

本地安装后通过 npm scripts 或 npx 使用。

Quick Fixes

Official References

• HBuilderX CLI 官方文档
• npm 包页面
• GitHub 仓库
• uni-app 自动化测试插件
• DCloud 官方文档

Audience

自定义选项：

• 指定目标平台（web/app-android/app-ios/mp-weixin 等）
• 指定设备（deviceId/iosTarget）
• 指定浏览器（Chrome/Safari/Firefox）
• 配置日志级别和输出

Gotchas

1. 必须先启动 HBuilderX — CLI 依赖 HBuilderX 进程，确保 HBuilderX 已运行或设置 HBUILDERX_CLI_PATH
2. 版本要求不统一 — uni-launch 需要 5.0+，uni-logcat 和 uni-test 需要 4.87+，使用前确认版本
3. iOS 测试仅支持模拟器 — uni-test app-ios 不支持真机，这是平台限制而非工具限制
4. 测试插件必须预装 — uni-test 需要先在 HBuilderX 中安装自动化测试插件，否则命令会失败
5. npm scripts 参数传递 — 通过 npm run 传递 CLI 参数必须加 -- 分隔符
6. 自动检测不可靠时手动配置 — 某些环境下自动检测可能失败（如多实例、非标准安装），此时必须设置 HBUILDERX_CLI_PATH
7. Windows 路径注意转义 — Windows 下环境变量路径包含空格时需要用双引号包裹

FAQ

Q: 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"。建议将设置添加到系统环境变量中持久化。