guoyu/_已清理文件备份_周六 22512/md/APP部署问题排查指南.md

APP 部署问题排查指南

问题一：图标不显示

原因分析

APP 图标是打包在应用内的本地资源，不依赖服务器。

排查步骤

1. 检查图标文件是否存在：

   fronted_uniapp/unpackage/res/icons/
   ├── 72x72.png
   ├── 96x96.png
   ├── 144x144.png
   ├── 192x192.png
   └── 1024x1024.png (iOS)
   

2. 在 HBuilderX 中重新配置图标：

   • 打开 manifest.json
   • 点击 "App图标配置"
   • 重新选择图标文件
   • 点击 "自动生成所有图标并替换"

3. 重新打包 APP

如果是应用内的图标不显示

检查图标引用路径是否正确：

<!-- 正确写法 -->
<image src="/static/icons/xxx.png" />

<!-- 错误写法（不要用相对路径） -->
<image src="../../static/icons/xxx.png" />

---

问题二：应用闪退

可能原因

1. 网络请求异常未处理
2. 内存不足（Vosk 模型约 50MB）
3. 权限问题

排查步骤

1. 查看崩溃日志

• Android：使用 adb logcat 查看日志
• 或在 HBuilderX 中连接手机，查看控制台输出

2. 检查网络请求超时配置

当前配置：fronted_uniapp/utils/config.js

REQUEST_TIMEOUT: 30000  // 30秒

如果服务器响应慢，可以增加超时时间：

REQUEST_TIMEOUT: 60000  // 60秒

3. 检查异常处理

确保所有网络请求都有 try-catch：

try {
    const result = await request.get('/api/xxx')
    // 处理结果
} catch (error) {
    console.error('请求失败:', error)
    // 显示友好提示，不要让应用崩溃
    uni.showToast({ title: '网络异常', icon: 'none' })
}

4. 检查内存使用

Vosk 模型较大，如果手机内存不足可能导致崩溃：

• 在低端设备上测试
• 考虑使用更小的模型

---

问题三：语音识别准确率低

重要说明

语音识别完全在本地进行，不依赖服务器！

使用的技术栈：

• 语音识别：本地 Vosk 模型 (vosk-model-small-cn-0.22)
• 评分算法：本地 JavaScript 计算

影响准确率的因素

1. 环境噪音

   • 安静环境识别率更高
   • 避免背景音乐、人声干扰

2. 麦克风质量

   • 不同手机麦克风质量不同
   • 距离麦克风 20-30cm 最佳

3. 说话方式

   • 语速适中，不要太快
   • 发音清晰
   • 每句话后稍作停顿

4. 模型限制

   • vosk-model-small-cn-0.22 是小型模型，准确率有限
   • 对方言、口音支持较差

提高准确率的方法

方法1：使用更大的模型

下载更大的 Vosk 中文模型（约 1GB），准确率更高：

• vosk-model-cn-0.22（大模型）

但会增加 APP 体积和内存占用。

方法2：使用云端语音识别

改用百度、讯飞等云端语音识别服务，准确率更高：

// 已有的后端接口
export function uploadAndRecognize(audioFilePath, originalContent) {
    // 上传音频到后端，使用百度语音识别
}

后端已经集成了百度语音识别服务，可以考虑使用。

方法3：优化评分算法

当前评分算法在 fronted_uniapp/api/study/voiceEvaluation.js 中：

• 使用编辑距离计算相似度
• 已经做了宽松处理

如果觉得评分太严格，可以进一步调整算法参数。

---

问题四：视频无法播放（服务器部署后）

原因

APP 直接访问后端服务器的 /profile 路径获取视频文件。

排查步骤

1. 检查服务器地址配置

   fronted_uniapp/utils/config.js:

   const DEFAULT_SERVER_HOST = '服务器IP'  // 不能是 localhost
   const DEFAULT_SERVER_PORT = 30091
   

2. 检查 Windows 防火墙

   开放 30091 端口：

   netsh advfirewall firewall add rule name="Study Backend" dir=in action=allow protocol=tcp localport=30091
   

3. 测试视频 URL

   在手机浏览器中访问：

   http://服务器IP:30091/profile/upload/2025/xx/video.mp4
   

---

调试技巧

1. 查看 APP 日志

在 HBuilderX 中：

1. 连接手机（USB 调试模式）
2. 运行 -> 运行到手机
3. 查看控制台输出

2. 使用 Android Studio Logcat

adb logcat | grep -i "uni"

3. 添加调试日志

在关键位置添加日志：

console.log('[DEBUG] 当前服务器地址:', config.API_BASE_URL)
console.log('[DEBUG] 请求URL:', url)
console.log('[DEBUG] 响应数据:', response)

4. 检查网络连接

// 在 APP 中测试网络
uni.request({
    url: 'http://服务器IP:30091/api/health',
    success: (res) => console.log('服务器连接正常'),
    fail: (err) => console.error('服务器连接失败:', err)
})