hbuilderx-cli

HBuilderX CLI リファレンス

本スキルでは、HBuilderX CLI コマンドラインツール（@dcloudio/hbuilderx-cli）を扱います。ユーザーがコマンドラインから uni-app の開発環境を起動したり、プラットフォームのログを確認したり、自動テストを実行したり、HBuilderX CLI を設定したりする場合に使用してください。

HBuilderX CLI は DCloud が公式に提供するコマンドラインツールのラッパーです。開発者は npm scripts やターミナルコマンドから HBuilderX のさまざまな機能を直接利用でき、IDE を手動で操作する必要はありません。

対応範囲

✅ 得意分野

1. コマンドラインから Web、Android、iOS、HarmonyOS、ミニプログラムなど、複数のプラットフォームの開発環境を起動する
2. 各プラットフォームの実行ログ（logcat）をリアルタイムで確認する
3. uni-app の自動テスト（Web/Android/iOS/HarmonyOS）を実行する
4. npm scripts や CI/CD ワークフローに HBuilderX のワークフローを統合する
5. HBuilderX CLI 環境を検出して設定する（自動／手動）

⚠️ 要件

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 開発者証明書が必要です

❌ 対象外（代替手段）

1. HBuilderX IDE 自体の使用方法と設定 → HBuilderX 公式ドキュメントを参照してください
2. uni-app アプリのコード作成 → 対応するフロントエンドフレームワークのスキル（vue3、vue2 など）を使用してください
3. ネイティブプラグインの開発 → HBuilderX ネイティブプラグイン開発ドキュメントを参照してください
4. クラウドでのビルドとリリース → uni-app クラウドビルドドキュメントを参照してください
5. uni-app 以外のプロジェクトのビルドツール → 対応するビルドスキル（webpack、vite など）を使用してください

このスキルを使用する場面

ユーザーがコマンドラインから uni-app の開発を開始したり、実行ログを確認したり、テストを実行したり、npm scripts に HBuilderX のワークフローを統合したり、HBuilderX CLI 環境を設定したりする場合に、このスキルを使用してください。

典型的な利用シーン：

• 「コマンドラインから uni-app の Web 開発を始めるにはどうすればいいですか？」
• 「npm scripts から Android エミュレーターを実行するにはどうすればいいですか？」
• 「uni-app の実行ログを確認するにはどうすればいいですか？」
• 「uni-test はどう設定すればいいですか？」
• 「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 を起動する処理を自動で行います。

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

重要：プラットフォーム対応表

プラットフォーム	uni-launch	uni-logcat	uni-test
Web	✅	✅	✅ Chrome/Safari/Firefox
Android	✅ 実機＋エミュレーター	✅	✅ 実機＋エミュレーター
iOS	✅ 実機＋エミュレーター	✅	⚠️ エミュレーターのみ
HarmonyOS	✅ 実機＋エミュレーター	✅	✅ 実機＋エミュレーター
WeChat ミニプログラム	✅	✅	—
Alipay ミニプログラム	✅	✅	—
Douyin ミニプログラム	✅	✅	—

重要：バージョン要件

コマンド	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"

重要：npm scripts との統合

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 にバックスラッシュを使用するか、パスを二重引用符で囲みます

Official References

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

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

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