# 常见问题 QA

本文档收集了开发过程中的常见问题和解决方案。

## 转换相关

### Q: 转换后游戏黑屏，控制台没有报错

**可能原因：**
1. CDN 资源未上传或地址错误
2. WASM 文件加载失败
3. WebGL 上下文创建失败

**解决方案：**
1. 检查 CDN 地址配置是否正确
2. 打开开发者工具网络面板，检查资源加载状态，检查Console是否有`onInstantiateSucc`日志输出
3. 尝试设置 `wx-game-kit/config.json--runtime--contextType`配置正确WebGL版本

---

## 网络相关

### Q: WebSocket 连接失败，提示"未完成的操作"

**原因：**
微信小游戏真机只支持 WSS 协议（加密连接），不支持 WS 协议。仅开发者工具支持WS协议。

**解决方案：**
使用 `wss://` 而不是 `ws://`：
```cpp
client->SetConnectUrl("wss://your-server.com/ws");
```

---

### Q: TCP Socket 连接超时

**可能原因：**
1. 服务器地址或端口错误
2. 服务器防火墙阻止连接
3. 域名未在微信后台配置

**解决方案：**
1. 验证服务器地址和端口
2. 检查服务器防火墙配置
3. 在微信公众平台配置合法域名（生产环境）
4. 开发时开启"不校验合法域名"选项

---

### Q: HTTP 请求返回 403 错误

**可能原因：**
1. 域名未在微信后台配置
2. 服务器拒绝请求

**解决方案：**
1. 在微信公众平台 -> 开发设置 -> 服务器域名 中添加请求域名
2. 检查服务器的访问限制

---

### Q: 真机测试时无法访问 localhost

**原因：**
手机和开发机不在同一网络环境，无法直接访问 localhost。

**解决方案：**
1. 获取开发机的局域网 IP 地址
2. 使用 IP 地址替代 localhost
3. 确保手机和开发机在同一 WiFi 网络

---

## 性能相关

### Q: 游戏启动很慢

**可能原因：**
1. WASM 文件过大
2. 首屏资源过多

**解决方案：**
1. 优化代码，减小 WASM 体积
2. 实现资源按需加载

---

### Q: 运行时内存不足

**可能原因：**
1. 初始内存设置过小
2. 资源未及时释放
3. 内存泄漏

**解决方案：**
1. 增加初始内存设置：
```cmake
-s INITIAL_MEMORY=512MB
```
2. 及时释放不需要的资源
3. 使用内存分析工具排查泄漏

---

### Q: 渲染帧率低

**可能原因：**
1. Draw Call 过多
2. 着色器复杂
3. 纹理过大

**解决方案：**
1. 合并网格，减少 Draw Call
2. 简化着色器
3. 使用压缩纹理
4. 降低渲染分辨率

---

## 集成相关

### Q: 链接时报 "undefined symbol"

**可能原因：**
1. 未使用 `--whole-archive`
2. 缺少必要的 jslib 文件

**解决方案：**
1. 确保使用了 `--whole-archive`：
```cmake
-Wl,--whole-archive libwxgamesdk.a -Wl,--no-whole-archive
```
2. 检查是否链接了所有需要的 jslib 文件

---

## 微信 API 相关

### Q: 登录时报错"未开通权限"

**原因：**
小游戏未完成微信认证或未开通相应权限。

**解决方案：**
1. 完成微信小游戏认证
2. 在微信公众平台开通所需权限

---

### Q: 分享图片不显示

**可能原因：**
1. 图片 URL 无法访问
2. 图片格式或尺寸不符合要求

**解决方案：**
1. 使用可公开访问的 HTTPS 图片链接
2. 支持 PNG、JPG 格式

---

## 调试相关

### Q: 如何在微信开发者工具中调试

**方法：**
1. 打开微信开发者工具
2. 导入转换后的项目
3. 使用控制台查看日志
4. 使用 Sources 面板断点调试

---

### Q: 如何查看 WASM 内部的日志

**方法：**
在 C++ 代码中使用 `printf` 或 `std::cout`，输出会显示在开发者工具控制台：

```cpp
#include <cstdio>
printf("Debug: value = %d\n", value);
```

---

### Q: 真机调试时看不到控制台输出

**解决方案：**
1. 使用微信开发者工具真机调试模式（仅支持Android）
2. 小程序右上角--开发调试--打开调试 开启调试模式
3. 将日志写入本地磁盘，上传服务器

---

## 其他问题

---

### Q: 如何获取更多帮助

1. 查阅本文档的相关章节
2. 查看 SDK 源码中的 Demo 示例
3. 提交 GitHub Issue

---

## 问题反馈

如果您遇到本文档未涵盖的问题，欢迎：

1. 在 GitHub 提交 Issue，并附上：
   - 问题描述
   - 复现步骤
   - 错误日志
   - 开发环境信息

2. 提供最小复现代码