HBuilderX-cli
一个便捷的 HBuilderX 命令行工具包装器，让您可以通过 npm scripts 轻松使用 HBuilderX 的各种功能。
📋 功能特性
- 🚀 多平台开发：支持 Web、Android、iOS、HarmonyOS、小程序、QuickApp 等平台
- 🔧 日志查看：实时查看各平台的运行日志
- 🧪 测试支持：运行自动化测试
- ⚡ 快速启动：通过简单的 npm 命令快速启动开发环境
- 🎯 配置化：所有命令配置集中管理，易于扩展
🛠️ 安装
全局安装（推荐）
npm install -g @dcloudio/hbuilderx-cli
全局安装后，可以直接在任何目录使用 hbuilderx、uni-launch、uni-logcat、uni-test 命令。
本地安装
npm install @dcloudio/hbuilderx-cli --save-dev
本地安装后，可以通过 npm scripts 使用，或在项目目录中使用 npx 命令。
🚀 快速开始
1. 环境准备
确保您已经安装了 HBuilderX。HBuilderX-cli 会自动检测已启动的 HBuilderX 进程。
📖 命令使用
直接调用 CLI (hbuilderx)
hbuilderx 命令是一个通用的 HBuilderX CLI 包装器，可以直接传递任何参数给 HBuilderX CLI。如果 HBuilderX 未运行，会自动先启动 HBuilderX。
# 全局安装后，直接使用命令
hbuilderx --version
hbuilderx project open --path /path/to/project
hbuilderx launch web --project /path/to/project
hbuilderx logcat web --project /path/to/project
# 或者通过 npm scripts 使用（本地安装时）
# 在 package.json 中配置：
# "scripts": {
# "hbuilderx": "hbuilderx"
# }
npm run hbuilderx -- --version
npm run hbuilderx -- project open --path /path/to/project
💡 提示：
hbuilderx命令会自动处理 HBuilderX 环境检测和启动，相当于直接调用 HBuilderX CLI，但更加便捷。
开发命令 (uni-launch)
⚠️ 版本要求：
uni-launch命令需要 HBuilderX 5.0 或更高版本，低于此版本将无法使用该命令。
uni-launch 命令用于启动各平台的开发环境，会自动处理项目打开和 HBuilderX 启动。
# 全局安装后，直接使用命令
uni-launch web
uni-launch app-android --deviceId emulator-5554
uni-launch app-ios --iosTarget simulator
# 或者通过 npm scripts 使用（本地安装时）
# 在 package.json 中配置：
# "scripts": {
# "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"
# }
npm run dev:web
npm run dev:app-android -- --deviceId emulator-5554
npm run dev:app-ios -- --iosTarget simulator
Web 平台
# 使用内置浏览器
uni-launch web
# 或（本地安装时通过 npm scripts）
npm run dev:web
# 使用 Chrome 浏览器
uni-launch web --browser Chrome
# 或
npm run dev:web -- --browser Chrome
# 只编译不运行
uni-launch web --compile true
# 或
npm run dev:web -- --compile true
Android 平台
# 使用默认设备
uni-launch app-android
# 或（本地安装时通过 npm scripts）
npm run dev:app-android
# 指定设备
uni-launch app-android --deviceId emulator-5554
# 或
npm run dev:app-android -- --deviceId emulator-5554
# 使用自定义基座
uni-launch app-android --playground custom
# 或
npm run dev:app-android -- --playground custom
# 显示原生日志
uni-launch app-android --native-log true
# 或
npm run dev:app-android -- --native-log true
# 编译错误后继续运行
uni-launch app-android --continue-on-error true
# 或
npm run dev:app-android -- --continue-on-error true
iOS 平台
# 真机开发
uni-launch app-ios --iosTarget device
# 或（本地安装时通过 npm scripts）
npm run dev:app-ios -- --iosTarget device
# 模拟器开发
uni-launch app-ios --iosTarget simulator
# 或
npm run dev:app-ios -- --iosTarget simulator
# 指定设备
uni-launch app-ios --deviceId iPhone-15-Pro
# 或
npm run dev:app-ios -- --deviceId iPhone-15-Pro
小程序平台
# 微信小程序（带运行时日志）
uni-launch mp-weixin --runtime-log true
# 或（本地安装时通过 npm scripts）
npm run dev:mp-weixin -- --runtime-log true
# 支付宝小程序
uni-launch mp-alipay --runtime-log true
# 或
npm run dev:mp-alipay -- --runtime-log true
# 抖音小程序
uni-launch mp-toutiao --runtime-log true
# 或
npm run dev:mp-toutiao -- --runtime-log true
日志查看命令 (uni-logcat)
⚠️ 版本要求：
uni-logcat命令需要 HBuilderX 4.87 或更高版本，低于此版本将无法使用该命令。
uni-logcat 命令用于查看各平台的运行日志，会自动处理项目打开和 HBuilderX 启动。
# 全局安装后，直接使用命令
uni-logcat web
uni-logcat app-android --deviceId emulator-5554
uni-logcat app-ios --iosTarget device
uni-logcat mp-weixin
# 或者通过 npm scripts 使用（本地安装时）
# 在 package.json 中配置：
# "scripts": {
# "logcat:web": "uni-logcat web",
# "logcat:app-android": "uni-logcat app-android",
# "logcat:app-ios": "uni-logcat app-ios",
# "logcat:mp-weixin": "uni-logcat mp-weixin"
# }
npm run logcat:web
npm run logcat:app-android -- --deviceId emulator-5554
npm run logcat:app-ios -- --iosTarget device
npm run logcat:mp-weixin
测试命令 (uni-test)
⚠️ 版本要求：
uni-test命令需要 HBuilderX 4.87 或更高版本，低于此版本将无法使用该命令。
⚠️ 重要提示：使用测试功能前，需要先在 HBuilderX 中安装 uni-app 自动化测试插件
uni-test 命令用于运行自动化测试，会自动处理项目打开和 HBuilderX 启动。
# 全局安装后，直接使用命令
uni-test web --testcaseFile tests/login.test.js
uni-test app-android --device_id emulator-5554
uni-test app-ios --device_id iPhone-15-Pro
# 或者通过 npm scripts 使用（本地安装时）
# 在 package.json 中配置：
# "scripts": {
# "test:web": "uni-test web",
# "test:app-android": "uni-test app-android",
# "test:app-ios": "uni-test app-ios"
# }
npm run test:web -- --testcaseFile tests/login.test.js
npm run test:app-android -- --device_id emulator-5554
npm run test:app-ios -- --device_id iPhone-15-Pro
安装测试插件
- 打开 HBuilderX
- 访问 插件页面
- 点击 下载插件并导入 HBuilderX
测试命令使用
# Web 测试（支持 Chrome、Safari、Firefox，默认为 Chrome）
uni-test web --testcaseFile tests/login.test.js
# 或（本地安装时通过 npm scripts）
npm run test:web -- --testcaseFile tests/login.test.js
uni-test web --browser Chrome --testcaseFile tests/login.test.js
# 或
npm run test:web -- --browser Chrome --testcaseFile tests/login.test.js
uni-test web --browser Safari --testcaseFile tests/login.test.js
# 或
npm run test:web -- --browser Safari --testcaseFile tests/login.test.js
uni-test web --browser Firefox --testcaseFile tests/login.test.js
# 或
npm run test:web -- --browser Firefox --testcaseFile tests/login.test.js
# Android 测试
uni-test app-android --device_id emulator-5554
# 或
npm run test:app-android -- --device_id emulator-5554
# iOS 测试（仅支持模拟器）
uni-test app-ios --device_id iPhone-15-Pro
# 或
npm run test:app-ios -- --device_id iPhone-15-Pro
测试平台限制说明：
- iOS 平台：仅支持模拟器测试，不支持真机测试
- Web 平台：支持 Chrome、Safari、Firefox 浏览器，默认为 Chrome
- Android 平台：支持真机和模拟器测试
- HarmonyOS 平台：支持真机和模拟器测试
⚙️ 环境配置
自动检测（推荐）
HBuilderX-cli 会自动检测已启动的 HBuilderX 进程，无需额外配置。
手动配置
如果自动检测失败，可以设置环境变量：
macOS/Linux
export HBUILDERX_CLI_PATH="/Applications/HBuilderX.app/Contents/MacOS/cli"
Windows
set HBUILDERX_CLI_PATH="C:\Program Files\HBuilderX\cli.exe"
🔍 故障排除
常见问题
1. 找不到 HBuilderX
# 确保 HBuilderX 已启动
# 或设置环境变量
export HBUILDERX_CLI_PATH="/path/to/hbuilderx/cli"
2. HBuilderX 版本过低
如果遇到命令执行错误，请检查 HBuilderX 版本：
# 检查 HBuilderX 版本
cli --version
本工具部分功能需要 HBuilderX 4.87 或更高版本，请更新到最新版本。
📚 更多信息
🤝 贡献
欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。
添加新命令
- 在
scripts/command-config.js中添加配置 - 更新
COMMAND_CONFIG.md文档 - 提交 Pull Request
📄 许可证
MIT License
🙏 致谢
感谢 DCloud 团队提供的 HBuilderX 和 uni-app 框架。