hbuilderx-cli
HBuilderX CLI 命令行工具技能。当用户需要通过命令行启动 uni-app 开发环境、查看运行日志、运行自动化测试、配置 HBuilderX CLI 环境,或在 npm scripts 中集成 HBuilderX 工作流时使用。覆盖 Web、Android、iOS、HarmonyOS、小程序等多平台开发。
How do I install this agent skill?
npx skills add https://github.com/full-stack-skills/build-skills --skill hbuilderx-cliIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a legitimate technical reference for the HBuilderX CLI tool. It provides standard instructions for uni-app development workflows, including environment setup, log viewing, and automated testing. No malicious code, obfuscation, or safety bypasses were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
HBuilderX CLI Reference
本技能覆盖 HBuilderX CLI 命令行工具(@dcloudio/hbuilderx-cli)。当用户需要通过命令行启动 uni-app 开发环境、查看平台日志、运行自动化测试或配置 HBuilderX CLI 时使用本技能。
HBuilderX CLI 是 DCloud 官方提供的命令行工具包装器,让开发者可以通过 npm scripts 或终端命令直接使用 HBuilderX 的各种功能,无需手动操作 IDE。
Capability Boundaries
✅ Strong Suits
- 通过命令行启动 Web、Android、iOS、HarmonyOS、小程序等多平台开发环境
- 实时查看各平台运行日志(logcat)
- 运行 uni-app 自动化测试(Web/Android/iOS/HarmonyOS)
- 在 npm scripts 和 CI/CD 流程中集成 HBuilderX 工作流
- HBuilderX CLI 环境检测与配置(自动/手动)
⚠️ Requirements
- 必须已安装 HBuilderX(CLI 会自动检测运行中的 HBuilderX 进程)
uni-launch命令需要 HBuilderX 5.0+uni-logcat和uni-test命令需要 HBuilderX 4.87+uni-test需要先在 HBuilderX 中安装 uni-app 自动化测试插件- iOS 真机开发需要有效的 Apple 开发者证书
❌ Out of Scope(及替代方案)
- HBuilderX IDE 本身的使用和配置 → 使用 HBuilderX 官方文档
- uni-app 应用代码编写 → 使用对应的前端框架技能(vue3、vue2 等)
- 原生插件开发 → 使用 HBuilderX 原生插件开发文档
- 云端打包和发布 → 使用 uni-app 云端打包文档
- 非 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
| 平台 | uni-launch | uni-logcat | uni-test |
|---|---|---|---|
| Web | ✅ | ✅ | ✅ Chrome/Safari/Firefox |
| Android | ✅ 真机+模拟器 | ✅ | ✅ 真机+模拟器 |
| iOS | ✅ 真机+模拟器 | ✅ | ⚠️ 仅模拟器 |
| HarmonyOS | ✅ 真机+模拟器 | ✅ | ✅ 真机+模拟器 |
| 微信小程序 | ✅ | ✅ | — |
| 支付宝小程序 | ✅ | ✅ | — |
| 抖音小程序 | ✅ | ✅ | — |
Critical: Version Requirements
| 命令 | 最低 HBuilderX 版本 | 说明 |
|---|---|---|
hbuilderx | 任意版本 | 通用包装器,无版本限制 |
uni-launch | 5.0+ | 开发环境启动命令 |
uni-logcat | 4.87+ | 日志查看命令 |
uni-test | 4.87+ | 自动化测试命令 |
检查 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
| 问题 | 解决方案 |
|---|---|
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 使用反斜杠或双引号包裹路径 |
Official References
Audience
| 用户类型 | 使用方式 |
|---|---|
| uni-app 开发者 | 通过命令行快速启动开发环境,替代手动操作 IDE |
| CI/CD 工程师 | 在自动化流水线中集成 uni-app 构建和测试 |
| 团队协作 | 统一团队的开发启动命令,通过 npm scripts 标准化工作流 |
| 多平台开发者 | 一个工具链管理 Web/Android/iOS/小程序等多平台开发 |
自定义选项:
- 指定目标平台(web/app-android/app-ios/mp-weixin 等)
- 指定设备(deviceId/iosTarget)
- 指定浏览器(Chrome/Safari/Firefox)
- 配置日志级别和输出
Gotchas
- 必须先启动 HBuilderX — CLI 依赖 HBuilderX 进程,确保 HBuilderX 已运行或设置
HBUILDERX_CLI_PATH - 版本要求不统一 —
uni-launch需要 5.0+,uni-logcat和uni-test需要 4.87+,使用前确认版本 - iOS 测试仅支持模拟器 —
uni-test app-ios不支持真机,这是平台限制而非工具限制 - 测试插件必须预装 —
uni-test需要先在 HBuilderX 中安装自动化测试插件,否则命令会失败 - npm scripts 参数传递 — 通过
npm run传递 CLI 参数必须加--分隔符 - 自动检测不可靠时手动配置 — 某些环境下自动检测可能失败(如多实例、非标准安装),此时必须设置
HBUILDERX_CLI_PATH - 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"。建议将设置添加到系统环境变量中持久化。
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/full-stack-skills/build-skills/hbuilderx-cli">View hbuilderx-cli on skillZs</a>