# 常见问题 QA
本文档收集了开发过程中的常见问题和解决方案。
# 转换相关
# Q: 转换后游戏黑屏，控制台没有报错
可能原因：
- CDN 资源未上传或地址错误
- WASM 文件加载失败
- WebGL 上下文创建失败
解决方案：
- 检查 CDN 地址配置是否正确
- 打开开发者工具网络面板，检查资源加载状态，检查Console是否有
onInstantiateSucc日志输出 - 尝试设置
wx-game-kit/config.json--runtime--contextType配置正确WebGL版本
# 网络相关
# Q: WebSocket 连接失败，提示"未完成的操作"
原因： 微信小游戏真机只支持 WSS 协议（加密连接），不支持 WS 协议。仅开发者工具支持WS协议。
解决方案：
使用 wss:// 而不是 ws://：
client->SetConnectUrl("wss://your-server.com/ws");
# Q: TCP Socket 连接超时
可能原因：
- 服务器地址或端口错误
- 服务器防火墙阻止连接
- 域名未在微信后台配置
解决方案：
- 验证服务器地址和端口
- 检查服务器防火墙配置
- 在微信公众平台配置合法域名（生产环境）
- 开发时开启"不校验合法域名"选项
# Q: HTTP 请求返回 403 错误
可能原因：
- 域名未在微信后台配置
- 服务器拒绝请求
解决方案：
- 在微信公众平台 -> 开发设置 -> 服务器域名 中添加请求域名
- 检查服务器的访问限制
# Q: 真机测试时无法访问 localhost
原因： 手机和开发机不在同一网络环境，无法直接访问 localhost。
解决方案：
- 获取开发机的局域网 IP 地址
- 使用 IP 地址替代 localhost
- 确保手机和开发机在同一 WiFi 网络
# 性能相关
# Q: 游戏启动很慢
可能原因：
- WASM 文件过大
- 首屏资源过多
解决方案：
- 优化代码，减小 WASM 体积
- 实现资源按需加载
# Q: 运行时内存不足
可能原因：
- 初始内存设置过小
- 资源未及时释放
- 内存泄漏
解决方案：
- 增加初始内存设置：
-s INITIAL_MEMORY=512MB
- 及时释放不需要的资源
- 使用内存分析工具排查泄漏
# Q: 渲染帧率低
可能原因：
- Draw Call 过多
- 着色器复杂
- 纹理过大
解决方案：
- 合并网格，减少 Draw Call
- 简化着色器
- 使用压缩纹理
- 降低渲染分辨率
# 集成相关
# Q: 链接时报 "undefined symbol"
可能原因：
- 未使用
--whole-archive - 缺少必要的 jslib 文件
解决方案：
- 确保使用了
--whole-archive：
-Wl,--whole-archive libwxgamesdk.a -Wl,--no-whole-archive
- 检查是否链接了所有需要的 jslib 文件
# 微信 API 相关
# Q: 登录时报错"未开通权限"
原因： 小游戏未完成微信认证或未开通相应权限。
解决方案：
- 完成微信小游戏认证
- 在微信公众平台开通所需权限
# Q: 分享图片不显示
可能原因：
- 图片 URL 无法访问
- 图片格式或尺寸不符合要求
解决方案：
- 使用可公开访问的 HTTPS 图片链接
- 支持 PNG、JPG 格式
# 调试相关
# Q: 如何在微信开发者工具中调试
方法：
- 打开微信开发者工具
- 导入转换后的项目
- 使用控制台查看日志
- 使用 Sources 面板断点调试
# Q: 如何查看 WASM 内部的日志
方法：
在 C++ 代码中使用 printf 或 std::cout，输出会显示在开发者工具控制台：
#include <cstdio>
printf("Debug: value = %d\n", value);
# Q: 真机调试时看不到控制台输出
解决方案：
- 使用微信开发者工具真机调试模式（仅支持Android）
- 小程序右上角--开发调试--打开调试 开启调试模式
- 将日志写入本地磁盘，上传服务器
# 其他问题
# Q: 如何获取更多帮助
- 查阅本文档的相关章节
- 查看 SDK 源码中的 Demo 示例
- 提交 GitHub Issue
# 问题反馈
如果您遇到本文档未涵盖的问题，欢迎：
在 GitHub 提交 Issue，并附上：
- 问题描述
- 复现步骤
- 错误日志
- 开发环境信息
提供最小复现代码