# 故障排查处理记录（微信小程序）

## 一、tabBar 图标格式错误

**现象**：微信开发者工具调试器报错：
```
dist/app.json: ["tabBar"]["list"][0]["iconPath"] 文件格式错误，仅支持 .png、.jpg、.jpeg 格式
```
所有 5 组 tabBar 图标（共 10 个）均报此错误。

**原因**：`app.config.ts` 中 tabBar 图标引用的是 `.svg` 文件，微信小程序 tabBar 图标仅支持 PNG/JPG/JPEG 格式，不支持 SVG。

**处理**：
1. 使用 `sharp` 库将 `src/assets/tabbar/` 下 10 个 SVG 文件转换为 81×81 像素的 PNG：
   ```bash
   npm install sharp --no-save --legacy-peer-deps
   node convert-icons.js  # 遍历 tabbar 目录，sharp(svgBuffer).resize(81,81).png().toFile()
   ```
2. 修改 `src/app.config.ts`，将 5 组 tabBar 的 `iconPath` 和 `selectedIconPath` 从 `.svg` 改为 `.png`。
3. 重新编译 `npm run build:weapp`。

**涉及文件**：
- `miniapp/src/assets/tabbar/*.png` -- 新生成的 PNG 图标（10 个）
- `miniapp/src/app.config.ts` -- tabBar 图标路径改为 .png

---

## 二、WebSocket 连接崩溃：onOpen is not a function

**现象**：微信开发者工具调试器报错：
```
[WS] 连接请求已发送
TypeError: this.socket.onOpen is not a function
    at n.value (app-service.js:7176)
```
WebSocket 连接后立即崩溃，页面白屏。

**原因**：`ws.ts` 中使用 `Taro.connectSocket()` 返回值（SocketTask）的 `onOpen`/`onMessage`/`onClose`/`onError` 方法注册回调，但在 Taro 4.x 微信小程序环境中，`connectSocket()` 返回的对象不可靠，不一定包含这些方法。

**处理**：改用 Taro 全局回调 API，不再依赖 SocketTask 实例方法：
- `Taro.onSocketOpen(cb)` 替代 `socket.onOpen(cb)`
- `Taro.onSocketMessage(cb)` 替代 `socket.onMessage(cb)`
- `Taro.onSocketClose(cb)` 替代 `socket.onClose(cb)`
- `Taro.onSocketError(cb)` 替代 `socket.onError(cb)`
- `Taro.sendSocketMessage({ data })` 替代 `socket.send({ data })`
- `Taro.closeSocket()` 替代 `socket.close({})`
- 连接状态用 `this.connected` 布尔值跟踪，替代 `this.socket` 引用

**涉及文件**：
- `miniapp/src/utils/ws.ts` -- 整个 WebSocketManager 类重写为全局 API 方式

---

## 三、API 请求连接被拒绝：ERR_CONNECTION_REFUSED

**现象**：微信开发者工具调试器报错：
```
[Request] GET /rooms 异常: {errMsg: "request:fail net::ERR_CONNECTION_REFUSED", errno: 7}
[Request] GET /devices 异常: {errMsg: "request:fail net::ERR_CONNECTION_REFUSED", errno: 7}
```
所有 API 请求均失败。

**原因**：`config.ts` 中默认 API 地址为 `http://localhost:3000/api/v1`，但后端服务运行在物理机 `100.83.103.1:3000`，Windows 本地没有服务在 3000 端口监听。

**处理**：修改 `miniapp/src/api/config.ts`，将默认 API 地址和 WebSocket fallback 地址从 `localhost:3000` 改为 `100.83.103.1:3000`：
```typescript
const DEFAULT_API_BASE_URL = isH5 ? '/api/v1' : 'http://100.83.103.1:3000/api/v1';
// ...
return `ws://100.83.103.1:3000/ws?token=${token}`;
```

**涉及文件**：
- `miniapp/src/api/config.ts` -- 默认地址改为 100.83.103.1:3000

---

## 四、WebSocket 域名校验失败：url not in domain list

**现象**：微信开发者工具调试器报错：
```
[WS] 连接错误: {errMsg: "fail:url not in domain list"}
[WS] 连接已关闭
```
HTTP 请求正常（返回 401），但 WebSocket 连接被拒绝。

**原因**：微信开发者工具缓存了旧的域名校验状态，即使已在"详情 -> 本地设置"中勾选了"不校验合法域名"，WebSocket 连接仍被拦截。

**处理**：微信开发者工具菜单 -> 清缓存 -> 全部清除 -> 关闭工具重新打开 -> 重新编译。

**注意事项**：
- 微信开发者工具版本：2.01.2510290 win32-x64
- `project.config.json` 中已有 `"urlCheck": false`，但缓存导致未生效
- 清缓存后域名校验恢复正常，WebSocket 连接成功

---

## 五、401 未授权：token 过期

**现象**：微信开发者工具调试器报错：
```
[Request] 401 未授权，清除登录状态
```
小程序自动跳回登录页。

**原因**：之前登录获取的 token 已过期，后端返回 401，`request.ts` 中的 401 拦截器清除 Storage 中的 token/refreshToken/user 并 `reLaunch` 到登录页。

**处理**：重新登录（admin / silk@123）获取新 token 即可。

**涉及文件**：
- `miniapp/src/api/request.ts` -- 401 拦截逻辑（清除登录状态 + 跳转登录页）