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

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