silk/故障排查处理记录（微信小程序）.md

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

一、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：

   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：

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 拦截逻辑（清除登录状态 + 跳转登录页）