# 微信小游戏助手（VSCode 版本）
# 1. 产品简介
微信小游戏助手（VSCode 插件）是一款用于在本地开发环境中完成微信小游戏预览、调试、真机测试与发布的工具。
插件内置 MCP（Model Context Protocol）服务，可与 AI IDE（如 Cursor、CodeBuddy 等）联动，以实现自动化开发流程。
核心定位：
- 面向 AI 编程场景的小游戏运行与调试基础设施。
- 为微信小游戏开发提供一站式能力支持（预览/调试/发布等）。
# 2. 安装
# 2.1 扩展市场安装
- 打开 VSCode/CodeBuddy/Cursor 等 IDE。
- 进入扩展面板（快捷键：
Ctrl+Shift+X/Cmd+Shift+X）。 - 搜索 微信小游戏助手。
- 点击安装。
# 3. 快速开始
# 3.1 项目要求
项目根目录需包含以下文件：
my-game/
├── game.js
├── game.json
└── project.config.json
# 3.2 启动预览
安装完成后，小游戏预览窗口将自动打开。若您手动关闭了窗口，可通过以下两种方式再次开启：
方式一：命令面板
- 调用命令面板（快捷键：
Ctrl+Shift+P/Cmd+Shift+P）。 - 输入
Mini Game，选择"打开预览"即可。
方式二：状态栏
- 点击 VSCode 右下角的"Mini Game Preview"按钮。
启动后将打开预览面板。
# 4. 核心功能
# 4.1 本地预览
- 启动 / 停止 / 重载预览。
- 自动监听文件变更（热更新）。
- 多设备尺寸模拟（手机 / 平板 / 自定义）。
- 内置日志面板（Console 输出）。
# 4.2 真机测试
前置条件
请参考"5.1 权限配置"部分完成配置，之后即可使用真机测试与发布功能。
使用流程
- 点击主界面上的"真机预览"按钮。
- 若未配置权限，将自动弹出权限配置页面；若已配置，则进入下一步。
- 插件将编译项目并生成二维码。
- 使用微信扫码预览。
# 4.3 上传发布
- 点击主界面上的"上传"按钮。
- 在弹出的对话框中填写版本号与项目备注。
- 点击"确认发布"。
在微信开发者平台，进入"管理" > "版本管理" > "开发版本"，即可看到已上传的版本。点击"提交审核"，即可进入后续流程。
# 5. 配置说明
点击预览窗口右上角的"配置"按钮，即可进入配置窗口。
# 5.1 权限配置
权限配置主要包含微信小游戏 AppID 和代码上传密钥：
- 微信小游戏 AppID：在微信公众平台注册获取。
- 代码上传密钥：在微信公众平台 → 开发 → 开发设置 → 小程序代码上传中生成并下载。
⚠️ 重要：请确保 AppID 对应的是"小游戏"类型，而非"小程序"，否则会报错。
- 白名单配置：请务必确认 IP 白名单中已包含您的工作机 IP。
# 5.2 MCP（AI 集成能力）
可在窗口右上角点击"配置"，在弹出面板中选择"MCP接入"选项。该插件支持一键写入 CodeBuddy 的 MCP 配置，其他 IDE 则需要自行配置。
支持的工具：
| 工具 | 说明 |
|---|---|
| run_game | 启动预览 |
| reload_game | 热重载 |
| get_logs | 获取日志 |
| real_device_preview | 真机预览 |
| publish | 发布版本 |
典型使用方式：
- AI 生成代码 → 自动触发预览。
- AI 分析日志 → 自动定位并修复问题。
- AI 调用发布接口 → 自动完成上线流程。
# 5.3 工作空间配置 (WorkSpace)
插件将自动识别包含 game.json 文件的目录并展示在此处。您可以切换当前预览的工作目录，并手动添加其他包含 game.json 的目录。
# 5.4 编译设置
您可以自定义编译参数，以满足特定场景下的编译要求。
# 5.5 通用设置
您可以在此设置是否在打开 VSCode 时自动启动预览窗口。
# 6. 使用场景（重点）
本插件主要适用于以下场景：
- 与 AI IDE（Cursor / CodeBuddy）深度结合。
- AI 自动生成小游戏代码。
- 自动触发预览并进行验证。
- 自动分析日志并修复问题。
- 自动完成版本发布。
简而言之，它作为 AI 开发小游戏流程中的运行与执行层。
# 7. 支持范围与限制
当前版本支持情况如下：
| 类型 | 支持情况 |
|---|---|
| H5 / 原生 JS 小游戏 | ✅ 支持 |
| Cocos | ✅ 支持 |
| Unity | ❌ 不支持 |
| Laya | ❌ 不支持 |
说明：
- 当前仅支持标准的 H5 / JS 结构小游戏以及使用cocos引擎的小游戏。
- 部分引擎（如 Unity、Laya）的项目暂未适配。
- 后续版本将逐步兼容主流游戏引擎。
# 8. 常见问题 (FAQ)
Q1: 插件提示找不到 game.js 文件。
A: 请确保项目根目录下包含 game.js 文件。
Q2: MCP 连接失败。
A: 请检查：
- 检查预览功能是否已成功启动。
- 检查 MCP 配置的端口号是否一致。
- 可尝试重新打开 IDE 再次进行尝试。
Q3: 真机测试时提示 IP 白名单错误。
A: 请登录微信公众平台，将您工作机的公网 IP 地址添加到 IP 白名单中。
Q4: 预览窗口白屏，没有任何内容。
A: 请检查：
- 项目代码是否存在语法或逻辑错误。
- 查看浏览器开发者工具中的 Console 面板，分析具体的错误日志。
# 9. 联系我们
如有任何问题或建议，欢迎通过以下方式联系我们：
QQ 群
微信助手
