# @dcloudio/hbuilderx-cli 中文文档

规范地址：https://npmcn.com/package/%40dcloudio/hbuilderx-cli/

版本：1\.2\.0
npm 元数据更新时间：2026-09-18T05:08:12.644Z
中文译文更新时间：2026-11-11T17:34:02.296Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dcloudio/hbuilderx-cli
原文对照：https://npmcn.com/package/%40dcloudio/hbuilderx-cli/?lang=original
项目主页：https://github.com/dcloudio/hbuilderx-cli#readme
源码仓库：https://github.com/dcloudio/hbuilderx-cli

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：28.9 kB，10 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=12\.0\.0
- 运行依赖：0 个
- 首次发布：2025-10-23T09:49:07.738Z
- 最新版本发布：2025-12-29T08:08:03.255Z
- 近 30 天下载量：23743（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 3 个）

## 中文简介

HBuilderX CLI 一体化促进单一应用发展

## 安装

```sh
npm install @dcloudio/hbuilderx-cli
```

也可以使用：`pnpm add @dcloudio/hbuilderx-cli`、`yarn add @dcloudio/hbuilderx-cli`、`bun add @dcloudio/hbuilderx-cli`

## README

# HBuilderX-cli

一个便捷的 HBuilderX 命令行工具包装器，让您可以通过 npm scripts 轻松使用 HBuilderX 的各种功能。

## 📋 功能特性

-   🚀 **多平台开发**：支持 Web、Android、iOS、HarmonyOS、小程序、QuickApp 等平台
-   🔧 **日志查看**：实时查看各平台的运行日志
-   🧪 **测试支持**：运行自动化测试
-   ⚡ **快速启动**：通过简单的 npm 命令快速启动开发环境
-   🎯 **配置化**：所有命令配置集中管理，易于扩展

## 🛠️ 安装

### 全局安装（推荐）

```bash
npm install -g @dcloudio/hbuilderx-cli
```

全局安装后，可以直接在任何目录使用 `hbuilderx`、`uni-launch`、`uni-logcat`、`uni-test` 命令。

### 本地安装

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

本地安装后，可以通过 npm scripts 使用，或在项目目录中使用 `npx` 命令。

## 🚀 快速开始

### 1\. 环境准备

确保您已经安装了 **HBuilderX**。HBuilderX-cli 会自动检测已启动的 HBuilderX 进程。

## 📖 命令使用

### 直接调用 CLI (hbuilderx)

`hbuilderx` 命令是一个通用的 HBuilderX CLI 包装器，可以直接传递任何参数给 HBuilderX CLI。如果 HBuilderX 未运行，会自动先启动 HBuilderX。

```bash
# 全局安装后，直接使用命令
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 启动。

```bash
# 全局安装后，直接使用命令
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 平台

```bash
# 使用内置浏览器
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 平台

```bash
# 使用默认设备
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 平台

```bash
# 真机开发
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
```

#### 小程序平台

```bash
# 微信小程序（带运行时日志）
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 启动。

```bash
# 全局安装后，直接使用命令
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 自动化测试插件](https://ext.dcloud.net.cn/plugin?id=5708)

`uni-test` 命令用于运行自动化测试，会自动处理项目打开和 HBuilderX 启动。

```bash
# 全局安装后，直接使用命令
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
```

#### 安装测试插件

1.  打开 HBuilderX
2.  访问 [插件页面](https://ext.dcloud.net.cn/plugin?id=5708)
3.  点击 **下载插件并导入 HBuilderX**

#### 测试命令使用

```bash
# 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

```bash
export HBUILDERX_CLI_PATH="/Applications/HBuilderX.app/Contents/MacOS/cli"
```

#### Windows

```cmd
set HBUILDERX_CLI_PATH="C:\Program Files\HBuilderX\cli.exe"
```

## 🔍 故障排除

### 常见问题

#### 1\. 找不到 HBuilderX

```bash
# 确保 HBuilderX 已启动
# 或设置环境变量
export HBUILDERX_CLI_PATH="/path/to/hbuilderx/cli"
```

#### 2\. HBuilderX 版本过低

如果遇到命令执行错误，请检查 HBuilderX 版本：

```bash
# 检查 HBuilderX 版本
cli --version
```

本工具部分功能需要 **HBuilderX 4.87 或更高版本**，请更新到最新版本。

## 📚 更多信息

-   [HBuilderX 官方文档](https://hx.dcloud.net.cn/cli/README)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。

### 添加新命令

1.  在 `scripts/command-config.js` 中添加配置
2.  更新 `COMMAND_CONFIG.md` 文档
3.  提交 Pull Request

## 📄 许可证

MIT License

## 🙏 致谢

感谢 DCloud 团队提供的 HBuilderX 和 uni-app 框架。

## 常见问题

### @dcloudio/hbuilderx-cli 是什么？

HBuilderX CLI 一体化促进单一应用发展

### 如何安装 @dcloudio/hbuilderx-cli？

在项目目录运行 npm install @dcloudio/hbuilderx-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 uni-test、hbuilderx、uni-launch、uni-logcat，可以用 npx uni-test 直接运行。

### @dcloudio/hbuilderx-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dcloudio\_\_hbuilderx-cli 是否存在。

### @dcloudio/hbuilderx-cli 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dcloudio/hbuilderx-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=12\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dcloudio/hbuilderx-cli 可以商用吗？

@dcloudio/hbuilderx-cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dcloudio/hbuilderx-cli 的下载量有多少？

根据 npm 官方下载统计，@dcloudio/hbuilderx-cli 在 2026/10/12 – 2026/11/10 这 30 天内被下载 23,743 次，日均约 791 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dcloudio/hbuilderx-cli 还在维护吗？

最新版本 1\.2\.0 发布于 2025/12/29（10 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 3 个；首次发布于 2025/10/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。