384 lines
8.7 KiB
Markdown
384 lines
8.7 KiB
Markdown
# 语音识别插件自定义基座制作指南
|
||
|
||
## ❌ **问题原因**
|
||
|
||
UTS 插件 `xwq-speech-to-text` 依赖第三方 Android 库 `vosk-android`，标准基座中不包含此依赖，因此需要制作**自定义基座**。
|
||
|
||
---
|
||
|
||
## 🔍 **错误信息**
|
||
|
||
```
|
||
error: Unresolved reference: vosk
|
||
import Model from "org.vosk.Model"
|
||
```
|
||
|
||
**原因：**
|
||
- Vosk 语音识别库未编译到基座中
|
||
- 需要制作包含 vosk-android 依赖的自定义基座
|
||
|
||
---
|
||
|
||
## ✅ **解决方案1：制作自定义调试基座（推荐）**
|
||
|
||
### **步骤1：检查环境**
|
||
|
||
#### **1.1 检查 HBuilderX 版本**
|
||
- 要求：HBuilderX 4.63 或更高版本
|
||
- 检查：`帮助` → `关于`
|
||
|
||
#### **1.2 检查 Android SDK**
|
||
- 菜单：`工具` → `设置` → `插件配置` → `Android SDK`
|
||
- 如果未安装，点击"下载Android SDK"
|
||
|
||
---
|
||
|
||
### **步骤2：制作自定义基座**
|
||
|
||
#### **2.1 打开项目**
|
||
1. 在 HBuilderX 中打开项目：`fronted_uniapp`
|
||
2. 确保项目已保存
|
||
|
||
#### **2.2 制作基座**
|
||
1. **右键点击项目根目录**
|
||
2. **选择：`发行` → `原生 App-制作自定义调试基座`**
|
||
3. **配置选项：**
|
||
- ✅ 选择平台：`Android`
|
||
- ✅ 证书：使用 DCloud 公共证书（测试用）
|
||
- ❌ 不勾选"仅打正式包"
|
||
|
||
4. **点击"打包"**
|
||
|
||
#### **2.3 等待打包**
|
||
- 打包时间：约 5-15 分钟
|
||
- 控制台会显示打包进度
|
||
- 打包完成后会提示"打包成功"
|
||
|
||
#### **2.4 下载基座**
|
||
打包完成后，基座文件会自动下载到：
|
||
```
|
||
fronted_uniapp/unpackage/debug/android_debug.apk
|
||
```
|
||
|
||
---
|
||
|
||
### **步骤3：安装自定义基座**
|
||
|
||
#### **3.1 手机连接**
|
||
1. 手机开启 USB 调试
|
||
2. 用数据线连接电脑
|
||
3. 确认手机弹出的授权提示
|
||
|
||
#### **3.2 安装基座**
|
||
**方法1：自动安装**
|
||
- HBuilderX 会自动检测并提示安装
|
||
- 点击"安装"即可
|
||
|
||
**方法2：手动安装**
|
||
```bash
|
||
# 使用 adb 安装
|
||
adb install -r fronted_uniapp/unpackage/debug/android_debug.apk
|
||
```
|
||
|
||
**方法3：直接安装**
|
||
- 将 `android_debug.apk` 复制到手机
|
||
- 在手机上点击安装
|
||
|
||
---
|
||
|
||
### **步骤4：使用自定义基座运行**
|
||
|
||
#### **4.1 运行项目**
|
||
1. 在 HBuilderX 中
|
||
2. 点击工具栏 "运行" → "运行到手机或模拟器" → "运行到 Android App 基座"
|
||
3. **重要：** 选择"自定义基座"（不是"标准基座"）
|
||
|
||
#### **4.2 验证**
|
||
- App 启动后，进入语音测评页面
|
||
- 如果能看到"准备就绪"，说明插件加载成功
|
||
- 如果还是报错，查看控制台日志
|
||
|
||
---
|
||
|
||
## ✅ **解决方案2：云端打包（正式发布用）**
|
||
|
||
如果是正式发布，使用云端打包：
|
||
|
||
### **步骤1：配置应用信息**
|
||
|
||
1. **打开 manifest.json**
|
||
2. **配置基础信息：**
|
||
- 应用名称
|
||
- 应用版本号
|
||
- 应用图标
|
||
- 包名（com.xxx.xxx）
|
||
|
||
### **步骤2：配置证书**
|
||
|
||
#### **2.1 生成证书（如果没有）**
|
||
```bash
|
||
# 使用 Android Studio 或命令行生成
|
||
keytool -genkey -v -keystore release.keystore -alias mykey -keyalg RSA -keysize 2048 -validity 10000
|
||
```
|
||
|
||
#### **2.2 在 HBuilderX 中配置证书**
|
||
1. `manifest.json` → `App 打包配置`
|
||
2. 选择证书文件
|
||
3. 输入证书密码和别名密码
|
||
|
||
---
|
||
|
||
### **步骤3：云端打包**
|
||
|
||
1. **右键项目根目录**
|
||
2. **选择：`发行` → `原生 App-云打包`**
|
||
3. **配置选项：**
|
||
- ✅ 选择平台：`Android`
|
||
- ✅ 使用自有证书
|
||
- ✅ 勾选"打正式包"
|
||
|
||
4. **点击"打包"**
|
||
|
||
5. **等待打包完成**
|
||
- 时间：约 10-20 分钟
|
||
- 完成后会提示下载地址
|
||
|
||
6. **下载并安装**
|
||
- 下载 APK 文件
|
||
- 安装到手机测试
|
||
|
||
---
|
||
|
||
## ✅ **解决方案3：暂时禁用语音功能**
|
||
|
||
如果暂时不需要语音识别，可以：
|
||
|
||
### **方法1：隐藏语音入口**
|
||
|
||
修改首页，隐藏语音测评入口：
|
||
|
||
```vue
|
||
<!-- pages/index/index.vue -->
|
||
<!-- 注释掉或删除语音测评入口 -->
|
||
<!--
|
||
<view class="action-item" @click="goToSpeech">
|
||
<view class="action-icon-wrapper voice">
|
||
<text class="action-icon">🎤</text>
|
||
</view>
|
||
<text class="action-text">语音测评</text>
|
||
</view>
|
||
-->
|
||
```
|
||
|
||
### **方法2：显示提示信息**
|
||
|
||
已修改 `speech.vue`，现在会显示友好提示：
|
||
```
|
||
需要制作自定义基座才能使用语音识别功能。
|
||
|
||
步骤：
|
||
1. HBuilderX菜单：发行 → 原生App-制作自定义调试基座
|
||
2. 选择Android平台
|
||
3. 等待打包完成
|
||
4. 安装自定义基座到手机
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 **常见问题**
|
||
|
||
### **问题1：打包失败 - SDK 未配置**
|
||
|
||
**错误：** `Android SDK path not configured`
|
||
|
||
**解决：**
|
||
1. `工具` → `设置` → `插件配置` → `Android SDK`
|
||
2. 点击"下载 Android SDK"
|
||
3. 等待下载完成
|
||
4. 重新打包
|
||
|
||
---
|
||
|
||
### **问题2：打包失败 - 网络问题**
|
||
|
||
**错误：** `Failed to download dependency`
|
||
|
||
**解决：**
|
||
1. 检查网络连接
|
||
2. 使用国内镜像（config.json 已配置阿里云镜像）
|
||
3. 重试打包
|
||
|
||
---
|
||
|
||
### **问题3：基座安装失败**
|
||
|
||
**错误：** `App not installed`
|
||
|
||
**解决：**
|
||
1. 卸载旧的基座
|
||
2. 清除手机缓存
|
||
3. 重新安装
|
||
|
||
---
|
||
|
||
### **问题4：运行时仍然报错**
|
||
|
||
**检查：**
|
||
1. 是否选择了"自定义基座"运行（不是标准基座）
|
||
2. 自定义基座版本是否最新
|
||
3. 是否需要重新制作基座
|
||
|
||
**重新制作基座：**
|
||
- 删除旧的 `android_debug.apk`
|
||
- 重新执行制作流程
|
||
- 重新安装到手机
|
||
|
||
---
|
||
|
||
### **问题5：插件仍然无法使用**
|
||
|
||
**检查 config.json：**
|
||
```json
|
||
{
|
||
"dependencies": [
|
||
"com.alphacephei:vosk-android:0.3.47"
|
||
]
|
||
}
|
||
```
|
||
|
||
**验证依赖：**
|
||
1. 检查插件配置文件是否正确
|
||
2. 清除缓存重新打包
|
||
3. 查看打包日志是否有错误
|
||
|
||
---
|
||
|
||
## 📋 **制作自定义基座完整流程**
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[开始] --> B[检查 HBuilderX 版本]
|
||
B --> C[配置 Android SDK]
|
||
C --> D[右键项目 → 发行 → 制作自定义调试基座]
|
||
D --> E[选择 Android 平台]
|
||
E --> F[点击打包]
|
||
F --> G[等待 5-15 分钟]
|
||
G --> H[下载基座 APK]
|
||
H --> I[安装到手机]
|
||
I --> J[运行项目 - 选择自定义基座]
|
||
J --> K{语音功能正常?}
|
||
K -->|是| L[完成]
|
||
K -->|否| M[查看日志排查]
|
||
M --> N[重新制作基座]
|
||
N --> G
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 **验证成功的标志**
|
||
|
||
### **1. 控制台日志**
|
||
```
|
||
[Speech] ========== 开始初始化语音模型 ==========
|
||
[Speech] 已保存的模型路径: /storage/...
|
||
[Speech] 模型加载成功
|
||
```
|
||
|
||
### **2. 页面显示**
|
||
- 状态：准备就绪，可以开始说话
|
||
- 调试信息：模型已加载
|
||
|
||
### **3. 功能测试**
|
||
- 点击"开始说话"按钮
|
||
- 说话后能看到识别文本
|
||
- 没有报错提示
|
||
|
||
---
|
||
|
||
## 📱 **自定义基座 vs 标准基座**
|
||
|
||
| 项目 | 标准基座 | 自定义基座 |
|
||
|------|----------|------------|
|
||
| **UTS 插件** | ❌ 不支持第三方依赖 | ✅ 支持 |
|
||
| **打包时间** | 快（秒级） | 慢（5-15分钟） |
|
||
| **更新频率** | 每次运行 | 需要重新制作 |
|
||
| **适用场景** | 普通功能开发 | 使用第三方依赖的插件 |
|
||
| **调试** | 实时同步代码 | 实时同步代码 |
|
||
|
||
---
|
||
|
||
## 💡 **最佳实践**
|
||
|
||
### **开发阶段**
|
||
1. ✅ 制作一次自定义基座
|
||
2. ✅ 安装到测试手机
|
||
3. ✅ 后续开发使用自定义基座运行
|
||
4. ⚠️ 插件更新后需要重新制作基座
|
||
|
||
### **测试阶段**
|
||
1. ✅ 使用自定义基座测试完整功能
|
||
2. ✅ 在不同机型上测试
|
||
3. ✅ 测试语音识别准确性
|
||
|
||
### **发布阶段**
|
||
1. ✅ 使用云端打包
|
||
2. ✅ 使用自有证书
|
||
3. ✅ 打正式包发布
|
||
|
||
---
|
||
|
||
## 📝 **注意事项**
|
||
|
||
1. **自定义基座只用于调试**
|
||
- 不要发布自定义基座给用户
|
||
- 正式发布使用云端打包
|
||
|
||
2. **基座需要定期更新**
|
||
- 插件更新后重新制作
|
||
- HBuilderX 更新后重新制作
|
||
|
||
3. **证书管理**
|
||
- 测试用 DCloud 公共证书
|
||
- 正式发布用自有证书
|
||
- 妥善保管证书文件
|
||
|
||
4. **版本匹配**
|
||
- 自定义基座版本要与 HBuilderX 版本匹配
|
||
- 插件版本要兼容
|
||
|
||
---
|
||
|
||
## 🆘 **获取帮助**
|
||
|
||
### **官方文档**
|
||
- UTS 插件开发：https://uniapp.dcloud.net.cn/tutorial/run/uts-development-android.html
|
||
- 自定义基座：https://uniapp.dcloud.net.cn/tutorial/run/run-app.html#customplayground
|
||
|
||
### **社区支持**
|
||
- DCloud 社区：https://ask.dcloud.net.cn/
|
||
- uni-app 官方 QQ 群
|
||
|
||
### **插件作者**
|
||
- 查看插件详情页的联系方式
|
||
|
||
---
|
||
|
||
## ✅ **总结**
|
||
|
||
### **推荐方案**
|
||
1. **开发调试：** 制作自定义调试基座
|
||
2. **正式发布：** 云端打包
|
||
|
||
### **核心步骤**
|
||
1. 配置 Android SDK
|
||
2. 制作自定义基座
|
||
3. 安装到手机
|
||
4. 选择自定义基座运行
|
||
|
||
### **关键点**
|
||
- ⚠️ 必须使用自定义基座
|
||
- ⚠️ 不能用标准基座
|
||
- ⚠️ 插件更新后需重新制作
|
||
|
||
**现在请按照步骤制作自定义基座，完成后语音识别功能即可正常使用！** 🚀
|