guoyu/log/备份/md/【操作指南】云端打包自定义基座.md

【操作指南】云端打包自定义调试基座

🎯 目标

解决 "找不到名称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. 查看完整的错误日志