213 lines
4.9 KiB
Markdown
213 lines
4.9 KiB
Markdown
# 【操作指南】云端打包自定义调试基座
|
||
|
||
## 🎯 目标
|
||
解决 "找不到名称vosk" 和 "uts插件编译失败" 错误
|
||
|
||
## 📋 前提条件
|
||
- ✅ 已安装 HBuilderX
|
||
- ✅ 有 DCloud 账号（用于云打包）
|
||
- ✅ 有 Android 手机用于测试
|
||
|
||
---
|
||
|
||
## 第一步：打开云打包界面
|
||
|
||
1. 在 HBuilderX 中，点击菜单栏：
|
||
```
|
||
发行 → 原生App-云打包
|
||
```
|
||
|
||
2. 会弹出云打包配置窗口
|
||
|
||
---
|
||
|
||
## 第二步：配置打包参数（重要！）
|
||
|
||
### 必选配置：
|
||
|
||
1. **应用名称**：保持默认或自定义
|
||
|
||
2. **应用版本号**：保持默认即可
|
||
|
||
3. **应用版本名称**：保持默认即可
|
||
|
||
4. **打包平台**：
|
||
- ✅ 勾选 `Android`
|
||
- ⬜ 不勾选 iOS（除非你需要）
|
||
|
||
5. **⭐ 关键配置：打包类型**
|
||
```
|
||
✅ 勾选 "打包为自定义调试基座"
|
||
```
|
||
**这是最重要的一步！** 不勾选这个，打出来的是正式包，不是调试基座。
|
||
|
||
6. **证书选择**：
|
||
- 开发测试阶段：选择 `使用 DCloud 公共测试证书`
|
||
- 正式发布：使用自己的证书
|
||
|
||
---
|
||
|
||
## 第三步：提交打包
|
||
|
||
1. 检查配置无误后，点击 `打包` 按钮
|
||
|
||
2. 等待云端打包：
|
||
- 时间：约 5-10 分钟
|
||
- 可以在 HBuilderX 控制台查看打包进度
|
||
- 云端会自动：
|
||
- 下载 Vosk 依赖库
|
||
- 编译 UTS 插件
|
||
- 生成 APK 文件
|
||
|
||
3. 打包成功后，控制台会显示下载链接
|
||
|
||
---
|
||
|
||
## 第四步：下载并安装基座
|
||
|
||
1. **下载 APK**：
|
||
- 点击控制台中的下载链接
|
||
- 或者在 DCloud 开发者中心下载
|
||
- 文件名类似：`__UNI__08E0C13_自定义基座.apk`
|
||
|
||
2. **安装到手机**：
|
||
- 将 APK 传输到 Android 手机
|
||
- 安装 APK（可能需要允许安装未知来源应用）
|
||
- 安装完成后，**不要删除 APK 文件**
|
||
|
||
3. **验证安装**：
|
||
- 在手机上找到应用图标
|
||
- 应用名称可能是 "fronted_uniapp" 或你设置的名称
|
||
- 图标右下角可能有 "自定义基座" 标识
|
||
|
||
---
|
||
|
||
## 第五步：配置 HBuilderX 使用自定义基座
|
||
|
||
1. **打开运行配置**：
|
||
```
|
||
运行 → 运行到手机或模拟器 → 运行配置
|
||
```
|
||
|
||
2. **选择基座类型**：
|
||
- 找到 "Android 基座选择"
|
||
- ⭐ 选择 `自定义调试基座`
|
||
- ❌ 不要选择 "标准基座"
|
||
|
||
3. **点击确定**保存配置
|
||
|
||
---
|
||
|
||
## 第六步：运行项目测试
|
||
|
||
1. **连接手机**：
|
||
- USB 连接手机到电脑
|
||
- 开启手机的 USB 调试模式
|
||
- 确保 HBuilderX 能识别到手机
|
||
|
||
2. **运行项目**：
|
||
```
|
||
运行 → 运行到手机或模拟器 → 运行到Android App基座
|
||
```
|
||
|
||
3. **查看日志**：
|
||
- 如果配置正确，不会再出现 "找不到名称vosk" 错误
|
||
- 应该能看到：
|
||
```
|
||
[Speech] ========== 开始初始化语音模型 ==========
|
||
[Speech] 模型加载成功
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 成功标志
|
||
|
||
### 编译日志应该显示：
|
||
```
|
||
项目 fronted_uniapp 编译成功
|
||
正在同步手机端程序文件...
|
||
应用【fronted_uniapp】已启动
|
||
```
|
||
|
||
### 不应该出现：
|
||
```
|
||
❌ 找不到名称"vosk"
|
||
❌ uts插件[xwq-speech-to-text]编译失败
|
||
❌ uni_module [xwq-speech-to-text] (Android) 存在三方依赖或资源引用
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 常见问题排查
|
||
|
||
### 问题 1：还是报 "找不到名称vosk"
|
||
**原因**：可能没有选择使用自定义基座
|
||
**解决**：
|
||
1. 检查运行配置，确保选择了 "自定义调试基座"
|
||
2. 重新运行项目
|
||
|
||
### 问题 2：打包失败
|
||
**可能原因**：
|
||
- 网络问题：重试打包
|
||
- 账号问题：检查 DCloud 账号是否登录
|
||
- 配置问题：检查是否勾选了 "打包为自定义调试基座"
|
||
|
||
### 问题 3：安装基座后找不到应用
|
||
**解决**：
|
||
- 检查手机是否允许安装未知来源应用
|
||
- 重新安装 APK
|
||
- 查看手机应用列表
|
||
|
||
### 问题 4：运行时连接不到基座
|
||
**解决**：
|
||
1. 确保手机和电脑在同一网络
|
||
2. 重启 HBuilderX
|
||
3. 重启手机上的基座应用
|
||
4. 检查防火墙设置
|
||
|
||
---
|
||
|
||
## 📝 重要提示
|
||
|
||
### 何时需要重新打包基座？
|
||
|
||
✅ **需要重新打包：**
|
||
- 修改了 UTS 插件代码
|
||
- 添加或删除了 uni_modules 插件
|
||
- 修改了 manifest.json 中的原生配置
|
||
- 修改了 Android 权限配置
|
||
|
||
❌ **不需要重新打包：**
|
||
- 修改了 Vue 组件代码
|
||
- 修改了 JS/TS 代码
|
||
- 修改了样式文件
|
||
- 修改了 API 接口调用
|
||
|
||
### 开发流程建议
|
||
|
||
1. **初次开发**：
|
||
- 云端打包自定义调试基座
|
||
- 安装到手机
|
||
- 配置 HBuilderX 使用自定义基座
|
||
|
||
2. **日常开发**：
|
||
- 修改 Vue/JS 代码
|
||
- 直接运行，热更新生效
|
||
- 无需重新打包
|
||
|
||
3. **修改插件后**：
|
||
- 重新云端打包自定义基座
|
||
- 重新安装到手机
|
||
- 继续开发
|
||
|
||
---
|
||
|
||
## 🎉 完成！
|
||
|
||
完成以上步骤后，语音识别功能应该可以正常使用了。
|
||
|
||
如果还有问题，请检查：
|
||
1. 是否下载了 Vosk 模型文件并放到 `/static/` 目录
|
||
2. 是否授予了麦克风权限
|
||
3. 查看完整的错误日志
|