xiaozhang/guoyu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
34e71d9bd8
guoyu/Test/备份/_已清理文件备份_周六 22512/md/语音识别插件自定义基座制作指南.md

8.7 KiB
Raw Blame History

语音识别插件自定义基座制作指南

❌ 问题原因

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：手动安装

# 使用 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 生成证书（如果没有）

# 使用 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：隐藏语音入口

修改首页，隐藏语音测评入口：

<!-- 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：

{
  "dependencies": [
    "com.alphacephei:vosk-android:0.3.47"
  ]
}

验证依赖：

  1. 检查插件配置文件是否正确
  2. 清除缓存重新打包
  3. 查看打包日志是否有错误

📋 制作自定义基座完整流程

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 版本匹配
    • 插件版本要兼容

🆘 获取帮助

官方文档

社区支持

插件作者

  • 查看插件详情页的联系方式

✅ 总结

推荐方案

  1. 开发调试： 制作自定义调试基座
  2. 正式发布： 云端打包

核心步骤

  1. 配置 Android SDK
  2. 制作自定义基座
  3. 安装到手机
  4. 选择自定义基座运行

关键点

  • ⚠️ 必须使用自定义基座
  • ⚠️ 不能用标准基座
  • ⚠️ 插件更新后需重新制作

现在请按照步骤制作自定义基座，完成后语音识别功能即可正常使用！ 🚀