Skip to content

Commit d7d0e59

Browse files
author
guomingliang
committed
feat: 初始发布 HBuilderX CLI 工具
支持 uni-app 多平台开发、日志查看和自动化测试功能
1 parent 0a6f749 commit d7d0e59

File tree

10 files changed

+948
-0
lines changed

10 files changed

+948
-0
lines changed

‎other/hbuilderx-cli/COMMAND_CONFIG.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# HBuilderX-cli 命令配置说明
2+
3+
## 可用命令列表
4+
5+
### uni-launch 开发命令
6+
7+
- `npm run dev:web` - Launch web development server
8+
- `npm run dev:app-android` - Launch Android app development
9+
- `npm run dev:app-ios` - Launch iOS app development
10+
- `npm run dev:app-harmony` - Launch HarmonyOS app development
11+
- `npm run dev:mp-weixin` - Launch WeChat Mini Program development
12+
- `npm run dev:mp-alipay` - Launch Alipay Mini Program development
13+
- `npm run dev:mp-baidu` - Launch Baidu Mini Program development
14+
- `npm run dev:mp-xhs` - Launch Xiaohongshu Mini Program development
15+
- `npm run dev:mp-toutiao` - Launch Toutiao Mini Program development
16+
- `npm run dev:mp-qq` - Launch QQ Mini Program development
17+
- `npm run dev:mp-360` - Launch 360 Mini Program development
18+
- `npm run dev:mp-kuaishou` - Launch Kuaishou Mini Program development
19+
- `npm run dev:mp-lark` - Launch Lark Mini Program development
20+
- `npm run dev:mp-jd` - Launch JD Mini Program development
21+
- `npm run dev:quickapp-huawei` - Launch Huawei QuickApp development
22+
- `npm run dev:quickapp-union` - Launch Union QuickApp development
23+
24+
### uni-logcat 日志查看命令
25+
26+
- `npm run logcat:web` - View web platform logs
27+
- `npm run logcat:app-android` - View Android app logs
28+
- `npm run logcat:app-ios` - View iOS app logs
29+
- `npm run logcat:app-harmony` - View HarmonyOS app logs
30+
- `npm run logcat:mp-weixin` - View WeChat Mini Program logs
31+
- `npm run logcat:mp-alipay` - View Alipay Mini Program logs
32+
- `npm run logcat:mp-baidu` - View Baidu Mini Program logs
33+
- `npm run logcat:mp-xhs` - View Xiaohongshu Mini Program logs
34+
- `npm run logcat:mp-toutiao` - View Toutiao Mini Program logs
35+
- `npm run logcat:mp-qq` - View QQ Mini Program logs
36+
- `npm run logcat:mp-360` - View 360 Mini Program logs
37+
- `npm run logcat:mp-kuaishou` - View Kuaishou Mini Program logs
38+
- `npm run logcat:mp-lark` - View Lark Mini Program logs
39+
- `npm run logcat:mp-jd` - View JD Mini Program logs
40+
- `npm run logcat:quickapp-huawei` - View Huawei QuickApp logs
41+
- `npm run logcat:quickapp-union` - View Union QuickApp logs
42+
43+
### uni-test 测试命令
44+
45+
- `npm run test:web-chrome` - Run web tests with Chrome
46+
- `npm run test:web-firefox` - Run web tests with Firefox
47+
- `npm run test:web-safari` - Run web tests with Safari
48+
- `npm run test:app-android` - Run Android app tests
49+
- `npm run test:app-ios-simulator` - Run iOS simulator app tests
50+
- `npm run test:app-harmony` - Run HarmonyOS app tests
51+
- `npm run test:mp-weixin` - Run WeChat Mini Program tests
52+
53+
## 如何添加新命令
54+
55+
现在添加新命令非常简单，只需要在 `scripts/command-config.js` 文件中添加配置即可。
56+
57+
### 配置格式
58+
59+
```javascript
60+
{
61+
scriptName: 'npm-script-name', // package.json 中的脚本名称
62+
command: 'uni-command args', // 实际执行的命令
63+
description: 'Command description' // 命令描述（可选，用于文档）
64+
}
65+
```
66+
67+
### 添加新命令示例
68+
69+
假设你要添加一个新的构建命令 `uni-build`：
70+
71+
1. **创建 bin 文件**：`bin/uni-build.js`
72+
2. **在 package.json 中注册**：
73+
```json
74+
"bin": {
75+
"uni-build": "./bin/uni-build.js"
76+
}
77+
```
78+
3. **在 command-config.js 中添加配置**：
79+
```javascript
80+
{
81+
scriptName: 'build:web',
82+
command: 'uni-build web',
83+
description: 'Build web project'
84+
}
85+
```
86+
87+
### 完整示例
88+
89+
```javascript
90+
// scripts/command-config.js
91+
module.exports = [
92+
{
93+
scriptName: "dev:web",
94+
command: "uni-launch web",
95+
description: "Launch web development server",
96+
},
97+
{
98+
scriptName: "logcat:web",
99+
command: "uni-logcat web",
100+
description: "View web platform logs",
101+
},
102+
{
103+
scriptName: "test:web",
104+
command: "uni-test web-chrome",
105+
description: "Run web tests with Chrome",
106+
},
107+
// 新增命令
108+
{
109+
scriptName: "build:web",
110+
command: "uni-build web",
111+
description: "Build web project",
112+
},
113+
{
114+
scriptName: "dev:app",
115+
command: "uni-launch app",
116+
description: "Launch app development",
117+
},
118+
];
119+
```
120+
121+
### 优势
122+
123+
- ✅ **配置化**：所有命令配置集中管理
124+
- ✅ **易扩展**：添加新命令只需修改配置文件
125+
- ✅ **一致性**：所有命令使用相同的注册逻辑
126+
- ✅ **可维护**：配置和逻辑分离，代码更清晰
127+
- ✅ **文档化**：每个命令都有描述信息
128+
129+
### 注意事项
130+
131+
- 确保 `scriptName` 不与现有脚本冲突
132+
- `command` 必须对应已注册的 bin 命令
133+
- 修改配置后需要重新安装包才能生效

‎other/hbuilderx-cli/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 HBuilderX CLI Team
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎other/hbuilderx-cli/README.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# HBuilderX-cli
2+
3+
一个便捷的 HBuilderX 命令行工具包装器，让您可以通过 npm scripts 轻松使用 HBuilderX 的各种功能。
4+
5+
## 📋 功能特性
6+
7+
- 🚀 **多平台开发**：支持 Web、Android、iOS、HarmonyOS、小程序、QuickApp 等平台
8+
- 🔧 **日志查看**：实时查看各平台的运行日志
9+
- 🧪 **测试支持**：运行自动化测试
10+
- ⚡ **快速启动**：通过简单的 npm 命令快速启动开发环境
11+
- 🎯 **配置化**：所有命令配置集中管理，易于扩展
12+
13+
## 🛠️ 安装
14+
15+
### 本地安装
16+
17+
```bash
18+
npm install hbuilderx-cli --save-dev
19+
```
20+
21+
## 🚀 快速开始
22+
23+
### 1. 环境准备
24+
25+
确保您已经安装了 HBuilderX 应用程序。HBuilderX-cli 会自动检测已启动的 HBuilderX 进程。
26+
27+
## 📖 命令使用
28+
29+
### 开发命令 (uni-launch)
30+
31+
#### Web 平台
32+
33+
```bash
34+
# 使用默认浏览器
35+
npm run dev:web
36+
37+
# 使用 Chrome 浏览器
38+
npm run dev:web -- --browser Chrome
39+
40+
# 只编译不运行
41+
npm run dev:web -- --compile true
42+
```
43+
44+
#### Android 平台
45+
46+
```bash
47+
# 使用默认设备
48+
npm run dev:app-android
49+
50+
# 指定设备
51+
npm run dev:app-android -- --serial emulator-5554
52+
53+
# 使用自定义基座
54+
npm run dev:app-android -- --playground custom
55+
56+
# 显示原生日志
57+
npm run dev:app-android -- --native-log true
58+
59+
# 编译错误后继续运行
60+
npm run dev:app-android -- --continue-on-error true
61+
```
62+
63+
#### iOS 平台
64+
65+
```bash
66+
# 真机开发
67+
npm run dev:app-ios -- --iosTarget device
68+
69+
# 模拟器开发
70+
npm run dev:app-ios -- --iosTarget simulator
71+
72+
# 指定设备
73+
npm run dev:app-ios -- --serial iPhone-15-Pro
74+
```
75+
76+
#### 小程序平台
77+
78+
```bash
79+
# 微信小程序（带运行时日志）
80+
npm run dev:mp-weixin -- --runtime-log true
81+
82+
# 支付宝小程序
83+
npm run dev:mp-alipay -- --runtime-log true
84+
85+
# 抖音小程序
86+
npm run dev:mp-toutiao -- --runtime-log true
87+
```
88+
89+
### 日志查看命令 (uni-logcat)
90+
91+
```bash
92+
# 查看 Web 日志
93+
npm run logcat:web
94+
95+
# 查看 Android 日志
96+
npm run logcat:app-android -- --serial emulator-5554
97+
98+
# 查看 iOS 日志
99+
npm run logcat:app-ios -- --iosTarget device
100+
101+
# 查看小程序日志
102+
npm run logcat:mp-weixin
103+
```
104+
105+
### 测试命令 (uni-test)
106+
107+
> **⚠️ 重要提示**：使用测试功能前，需要先在 HBuilderX 中安装 [uni-app 自动化测试插件](https://ext.dcloud.net.cn/plugin?id=5708)
108+
109+
#### 安装测试插件
110+
111+
1. 打开 HBuilderX
112+
2. 访问 [插件页面](https://ext.dcloud.net.cn/plugin?id=5708)
113+
3. 点击 **下载插件并导入 HBuilderX**
114+
115+
#### 测试命令使用
116+
117+
```bash
118+
# Web 测试（支持 Chrome、Safari、Firefox，默认为 Chrome）
119+
npm run test:web -- --testcaseFile tests/login.test.js
120+
npm run test:web -- --browser Chrome --testcaseFile tests/login.test.js
121+
npm run test:web -- --browser Safari --testcaseFile tests/login.test.js
122+
npm run test:web -- --browser Firefox --testcaseFile tests/login.test.js
123+
124+
# Android 测试
125+
npm run test:app-android -- --device_id emulator-5554
126+
127+
# iOS 测试（仅支持模拟器）
128+
npm run test:app-ios -- --device_id iPhone-15-Pro
129+
```
130+
131+
**测试平台限制说明：**
132+
133+
- **iOS 平台**：仅支持模拟器测试，不支持真机测试
134+
- **Web 平台**：支持 Chrome、Safari、Firefox 浏览器，默认为 Chrome
135+
- **Android 平台**：支持真机和模拟器测试
136+
- **HarmonyOS 平台**：支持真机和模拟器测试
137+
138+
## ⚙️ 环境配置
139+
140+
### 自动检测（推荐）
141+
142+
HBuilderX-cli 会自动检测已启动的 HBuilderX 进程，无需额外配置。
143+
144+
### 手动配置
145+
146+
如果自动检测失败，可以设置环境变量：
147+
148+
#### macOS/Linux
149+
150+
```bash
151+
export HBUILDERX_CLI_PATH="/Applications/HBuilderX.app/Contents/MacOS/cli"
152+
```
153+
154+
#### Windows
155+
156+
```cmd
157+
set HBUILDERX_CLI_PATH="C:\Program Files\HBuilderX\cli.exe"
158+
```
159+
160+
## 🔍 故障排除
161+
162+
### 常见问题
163+
164+
#### 1. 找不到 HBuilderX
165+
166+
```bash
167+
# 确保 HBuilderX 已启动
168+
# 或设置环境变量
169+
export HBUILDERX_CLI_PATH="/path/to/hbuilderx/cli"
170+
```
171+
172+
## 📚 更多信息
173+
174+
- [HBuilderX 官方文档](https://hx.dcloud.net.cn/cli/README)
175+
176+
## 🤝 贡献
177+
178+
欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。
179+
180+
### 添加新命令
181+
182+
1. 在 `scripts/command-config.js` 中添加配置
183+
2. 更新 `COMMAND_CONFIG.md` 文档
184+
3. 提交 Pull Request
185+
186+
## 📄 许可证
187+
188+
MIT License
189+
190+
## 🙏 致谢
191+
192+
感谢 DCloud 团队提供的 HBuilderX 和 uni-app 框架。

‎other/hbuilderx-cli/bin/uni-launch.js‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
#!/usr/bin/env node
2+
3+
const {
4+
checkHBuilderXEnvironment,
5+
executeCommand,
6+
getCurrentProjectPath,
7+
handleCommandError
8+
} = require('../lib/hbuilderx');
9+
10+
const [...extraArgs] = process.argv.slice(2);
11+
12+
async function main() {
13+
try {
14+
const { path: hbuilderxCli, isRunning } = await checkHBuilderXEnvironment();
15+
const currentProjectPath = getCurrentProjectPath();
16+
17+
const platform = extraArgs[0];
18+
if (!platform) {
19+
console.error('Usage: uni-launch launch <platform> [options]');
20+
process.exit(1);
21+
}
22+
23+
// 如果 HBuilderX 未运行，先执行 open
24+
if (!isRunning) {
25+
console.log('Opening HBuilderX...');
26+
await executeCommand(hbuilderxCli, ['open']);
27+
}
28+
29+
// 再执行 project open
30+
console.log('Opening project...');
31+
await executeCommand(hbuilderxCli, ['project', 'open', '--path', currentProjectPath]);
32+
33+
// 最后执行 launch
34+
console.log(`Launching project on ${platform}...`);
35+
await executeCommand(hbuilderxCli, ['launch', platform, '--project', currentProjectPath, ...extraArgs.slice(1)]);
36+
} catch (error) {
37+
handleCommandError(error, 'launch');
38+
}
39+
}
40+
41+
main();

0 commit comments

Comments
 (0)