guoyu/log/备份/md/配置本地Android编译环境.md

# 配置本地 Android 编译环境

## 问题分析

错误信息：
```
找不到名称"vosk"
uni_module [xwq-speech-to-text] (Android) 存在三方依赖或资源引用
```

这是因为 UTS 插件依赖第三方库 `com.alphacephei:vosk-android:0.3.47`，本地编译环境找不到这个库。

## 方案一：配置本地 Android SDK（不推荐，太复杂）

1. 安装 Android Studio
2. 配置 Android SDK
3. 在 HBuilderX 设置中配置 Android SDK 路径
4. 配置 Gradle 环境

**不推荐原因：** 配置复杂，容易出错

## 方案二：使用云端自定义基座（强烈推荐）✅

### 步骤详解

#### 1. 制作云端自定义基座

在 HBuilderX 中：
```
发行 → 原生App-云打包 → 打包为自定义调试基座
```

**重要配置：**
- ✅ 勾选 "打包为自定义调试基座"
- ✅ 选择 Android 平台
- ✅ 证书可以使用 DCloud 公共证书（测试用）
- ✅ 点击打包

#### 2. 等待云端打包完成
- 时间：约 5-10 分钟
- 云端会自动下载和编译 Vosk 依赖
- 完成后会显示下载链接

#### 3. 下载并安装基座
- 下载生成的 APK 文件
- 安装到 Android 手机
- 文件名类似：`__UNI__XXXXX_自定义基座.apk`

#### 4. 在 HBuilderX 中选择自定义基座运行

```
运行 → 运行到手机或模拟器 → 运行到Android App基座
```

选择刚才安装的自定义基座，而不是标准基座。

#### 5. 运行项目
- 现在运行时不会再编译 UTS 插件
- 直接使用基座中已编译好的插件
- 语音识别功能应该可以正常使用

## 关键区别

| 操作 | 本地编译 | 云端编译 |
|------|---------|---------|
| 制作自定义基座 | ❌ 需要配置 Android SDK | ✅ 云端自动处理 |
| 下载依赖 | ❌ 需要手动配置 Maven | ✅ 云端自动下载 |
| 编译 UTS 插件 | ❌ 容易出错 | ✅ 稳定可靠 |
| 推荐程度 | ⭐ | ⭐⭐⭐⭐⭐ |

## 注意事项

### 1. 基座类型选择
在 HBuilderX 运行配置中，确保选择：
```
运行 → 运行到手机或模拟器 → 运行配置
→ 选择 "自定义调试基座"
```

### 2. 修改 UTS 插件代码后
如果你修改了 `xwq-speech-to-text` 插件的代码：
- ❌ 热更新无效
- ✅ 需要重新制作云端自定义基座
- ✅ 重新安装到手机

### 3. 修改 Vue/JS 代码
如果只修改 Vue 或 JS 代码：
- ✅ 热更新有效
- ✅ 不需要重新制作基座

## 验证步骤

完成后，运行日志应该显示：
```
[Speech] ========== 开始初始化语音模型 ==========
[Speech] 模型加载成功
```

而不是：
```
找不到名称"vosk"
uts插件[xwq-speech-to-text]编译失败
```

## 常见问题

### Q: 为什么本地运行还是报错？
A: 确保在运行配置中选择了"自定义调试基座"，而不是"标准基座"。

### Q: 每次修改代码都要重新打包吗？
A: 
- 修改 Vue/JS 代码：不需要
- 修改 UTS 插件代码：需要重新制作基座

### Q: 云打包和自定义基座有什么区别？
A:
- 自定义调试基座：用于开发测试，包含调试功能
- 云打包正式版：用于发布，经过优化和混淆

## 总结

**最简单的方案：**
1. 云端打包自定义调试基座（勾选"打包为自定义调试基座"）
2. 安装到手机
3. 在 HBuilderX 中选择使用自定义基座运行
4. 完成！

不需要配置任何本地 Android 环境。