Skip to content

Commit f8b80c2

Browse files
dcloud-wandldcloud-wandl
committed
init
0 parents  commit f8b80c2

File tree

12 files changed

+1044
-0
lines changed

12 files changed

+1044
-0
lines changed

‎.github/workflows/.npmrc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}
2+
registry=https:

‎.github/workflows/main.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: Publish Packages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
jobs:
7+
publish-cli:
8+
runs-on: ubuntu-latest
9+
steps:
10+
- uses: actions/checkout@v3
11+
- uses: actions/setup-node@v3
12+
with:
13+
node-version: "18.x"
14+
registry-url: "https://registry.npmjs.org"
15+
- name: Publish cli
16+
run: |
17+
cd other/hbuilderx-cli
18+
npm publish --access public
19+
env:
20+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎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+
- 修改配置后需要重新安装包才能生效

‎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.

‎README.md‎

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

0 commit comments

Comments
 (0)