movecheck/故障排查流程.md

# 萤石云播放器故障排查流程

> 快速定位和解决问题

---

## 🔍 问题诊断流程图

```
视频无法播放
    ↓
是否显示黑屏？
    ├─ 是 → 检查AccessToken
    │      ├─ 已过期 → 刷新Token
    │      └─ 有效 → 检查设备状态
    │
    └─ 否 → 是否显示加载中？
           ├─ 是 → 检查网络
           │      ├─ 网络正常 → 检查play_url格式
           │      └─ 网络异常 → 修复网络
           │
           └─ 否 → APP是否崩溃？
                  ├─ 是 → 查看崩溃日志
                  │      └─ OutOfMemoryError → 已使用iframe方案？
                  │             ├─ 否 → 切换到iframe方案
                  │             └─ 是 → 检查manifest.json
                  │
                  └─ 否 → 其他问题 → 查看详细日志
```

---

## 🚨 常见错误码速查

### 1. 黑屏不播放

**症状：**
- 页面加载完成
- 显示黑色屏幕
- 无加载提示

**排查步骤：**

```javascript
// ✅ 步骤1: 检查AccessToken
console.log('AccessToken:', accessToken)
console.log('Token长度:', accessToken.length)  // 应该>50

// ✅ 步骤2: 检查play_url格式
console.log('PlayUrl:', play_url)
// 正确格式: ezopen://open.ys7.com/K74237657/1.hd.live

// ✅ 步骤3: 检查iframe URL
console.log('iframeUrl:', iframeUrl)
// 应该包含: https://open.ys7.com/ezopen/h5/iframe?

// ✅ 步骤4: 测试Token有效性
uni.request({
  url: 'https://open.ys7.com/api/lapp/device/list',
  method: 'POST',
  data: { accessToken: accessToken },
  success: (res) => {
    console.log('Token测试结果:', res.data)
  }
})
```

**解决方案：**
```javascript
// 方案1: 刷新Token
uni.removeStorageSync('ezviz_access_token')
const newToken = await tokenManager.getValidAccessToken()

// 方案2: 检查设备序列号
// 确认设备序列号正确，格式: K74237657

// 方案3: 切换清晰度
play_url: "ezopen://open.ys7.com/K74237657/1.sd.live"  // 标清
```

---

### 2. APP 崩溃（OutOfMemoryError）

**症状：**
```
FATAL EXCEPTION: main
java.lang.OutOfMemoryError: Failed to allocate...
```

**检查清单：**

```bash
# ✅ 1. 确认使用iframe方案
grep -r "ezuikit.js" src/
# 如果有结果 → 错误！不应该加载本地SDK

# ✅ 2. 检查manifest.json
cat src/manifest.json | grep largeHeap
# 应该有: "largeHeap": true

# ✅ 3. 查看实际内存使用
adb shell dumpsys meminfo 包名
```

**解决方案：**

```json
// ① 确保manifest.json配置正确
{
  "app-plus": {
    "compatible": {
      "largeHeap": true
    }
  }
}

// ② 使用iframe方案
// src/static/html/ezviz-iframe.html
<iframe src="https://open.ys7.com/ezopen/h5/iframe?..."></iframe>

// ③ 不要加载本地SDK
// ❌ 删除这行：<script src="ezuikit.js"></script>
```

---

### 3. 组件引用错误

**症状：**
```javascript
Cannot read properties of undefined (reading 'initEzuikit')
```

**原因分析：**
```javascript
// ❌ 错误代码
this.$nextTick(() => {
  this.$refs.playerVideoRef.initEzuikit(config)  // ref不存在！
})
this.ezstate = true  // 这时才开始渲染

// 问题：ezstate=false时，组件不在DOM中，ref是undefined
```

**解决方案：**
```javascript
// ✅ 正确代码
// 1. 先渲染组件
this.ezstate = true

// 2. 等待Vue更新DOM
await this.$nextTick()

// 3. 安全调用（添加检查）
if (this.$refs.playerVideoRef) {
  this.$refs.playerVideoRef.initEzuikit(config)
} else {
  console.error('播放器组件未找到')
}
```

---

### 4. 视频画面变形

**症状：**
- 视频能播放
- 画面被拉伸或压缩
- 不是原始比例

**检查代码：**
```scss
// ❌ 错误：直接设置固定高度
.video-content {
  width: 100%;
  height: 100vh;  // 会导致变形！
}

// ✅ 正确：使用padding-top保持16:9
.video-content {
  width: 100%;
  position: relative;
  
  &::before {
    content: '';
    display: block;
    padding-top: 56.25%;  /* 16:9比例 */
  }
  
  :deep(.simple-video-player) {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
  }
}
```

**其他比例参考：**
```scss
/* 16:9 */  padding-top: 56.25%;
/* 4:3 */   padding-top: 75%;
/* 1:1 */   padding-top: 100%;
/* 21:9 */  padding-top: 42.86%;
```

---

### 5. 加载很慢

**症状：**
- 长时间显示"正在加载..."
- 超过10秒没反应

**排查步骤：**

```javascript
// ✅ 1. 测试网络速度
uni.request({
  url: 'https://open.ys7.com',
  success: (res) => {
    console.log('萤石云连接正常')
  },
  fail: (err) => {
    console.error('网络异常:', err)
  }
})

// ✅ 2. 切换清晰度
// 高清 → 标清
play_url: "ezopen://open.ys7.com/K74237657/1.sd.live"

// ✅ 3. 检查设备状态
import deviceChecker from '@/utils/ezvizDeviceChecker.js'
const result = await deviceChecker.comprehensiveCheck(play_url)
console.log('设备状态:', result)
```

**优化方案：**
```javascript
// 方案1: 预加载AccessToken
onLoad() {
  // 提前获取token
  tokenManager.getValidAccessToken()
}

// 方案2: 添加超时处理
setTimeout(() => {
  if (this.loading) {
    this.error = true
    this.errorText = '加载超时，请重试'
  }
}, 15000)  // 15秒超时

// 方案3: 使用标清
play_url: "ezopen://open.ys7.com/K74237657/1.sd.live"
```

---

## 🛠 调试工具

### 1. Chrome 远程调试

```bash
# ① 启用ADB调试
adb devices

# ② 在Chrome中打开
chrome://inspect/#devices

# ③ 找到WebView进程，点击inspect
```

### 2. ADB 日志查看

```bash
# 查看所有日志
adb logcat

# 只看错误
adb logcat *:E

# 过滤关键字
adb logcat | grep -i "chromium\|console\|memory"

# 查看崩溃日志
adb logcat | grep -i "fatal\|crash"
```

### 3. 控制台调试

```javascript
// 在Vue组件中
console.log('[调试] 初始化配置:', config)
console.log('[调试] ref存在:', !!this.$refs.playerVideoRef)
console.log('[调试] ezstate:', this.ezstate)

// 在HTML中
<script>
  console.log('[iframe] 开始初始化')
  console.log('[iframe] AccessToken:', accessToken.substring(0, 20))
  console.log('[iframe] PlayUrl:', playUrl)
</script>
```

---

## 📋 完整检查清单

### 部署前检查

```
□ 萤石云账号配置
  □ AppKey已配置
  □ AppSecret已配置
  □ 设备序列号正确
  □ 验证码正确

□ 文件完整性
  □ EzvizVideoPlayerSimple.vue 存在
  □ ezviz-iframe.html 存在
  □ ezvizTokenManager.js 存在
  □ pages.json 配置正确
  □ manifest.json 配置正确

□ 代码正确性
  □ 使用iframe方案（非SDK）
  □ 组件调用顺序正确
  □ 16:9比例设置正确
  □ 横屏配置正确

□ 功能测试
  □ AccessToken获取成功
  □ 视频能正常播放
  □ 播放/暂停功能正常
  □ 刷新功能正常
  □ 切换摄像头正常
```

### 运行时检查

```
□ 网络连接正常
□ AccessToken未过期
□ 设备在线
□ 内存占用<200MB
□ 无崩溃
□ 画面不变形
□ 音频正常
```

---

## 🆘 紧急修复

### 快速恢复（5分钟）

如果系统完全不能用，按以下步骤快速恢复：

```javascript
// ① 清除所有缓存
uni.clearStorageSync()

// ② 使用备用Token（临时）
const backupConfig = {
  accessToken: "at.4dd7o6hgdb9ywl9c283g0hj27e789uru-2a5ejk6tkf-19b1cb1-azyfqm3a",
  play_url: "ezopen://open.ys7.com/K74237657/1.sd.live"  // 标清
}

// ③ 重启APP
// 在 APP.vue 的 onLaunch 中清除缓存
onLaunch() {
  console.log('APP启动，清除缓存')
  uni.clearStorageSync()
}
```

---

## 📞 获取帮助

### 查看日志位置

```
✅ Vue组件日志：开发者工具 Console
✅ APP日志：adb logcat
✅ web-view日志：Chrome inspect
✅ 萤石云日志：萤石云控制台
```

### 常用命令

```bash
# 连接设备
adb devices

# 查看日志
adb logcat | grep -i "console"

# 清除APP数据
adb shell pm clear 包名

# 重启APP
adb shell am force-stop 包名
adb shell am start 包名/.MainActivity
```

---

## 🔗 相关文档

- 📖 [完整指南](./萤石云APP对接完整指南.md)
- 📝 [快速参考](./README-萤石云对接.md)
- 🌐 [萤石云API文档](https://open.ys7.com/doc/)

---

**最后更新：** 2025-10-06  
**版本：** v1.0

---

💡 **提示：** 90%的问题都是 AccessToken 过期或配置错误导致的！