weijuesen
111 lines
4.4 KiB
Markdown
111 lines
4.4 KiB
Markdown
# 故障排查处理记录（微信小程序）
|
||
|
||
## 一、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 拦截逻辑（清除登录状态 + 跳转登录页）
|