Weixin MiniGame Helper

微信小游戏预览、真机测试和发布工具。 在 VSCode 中一站式完成微信小游戏的开发调试、真机预览和版本发布，同时支持 AI 编程工具（Cursor、CodeBuddy 等）通过 MCP 协议直接操控游戏。

✨ 功能特性

🎮 本地预览

在 VSCode 面板中实时运行微信小游戏，无需微信开发者工具
完整的 wx.* API 兼容层，覆盖 Canvas、音频、网络、存储、设备传感器等常用 API
多机型模拟（iPhone、Android、iPad 等），工具栏一键切换
文件变更自动检测，支持热重载

📱 真机测试

一键生成真机预览二维码，微信扫码即可在手机上测试
密钥通过 VSCode Secrets API 加密存储，安全可靠
自动识别 IP 白名单错误并给出解决指引

🚀 版本发布

直接从 VSCode 提交新版本到微信平台进行审核发布
支持指定版本号和发布说明

🤖 MCP 集成（AI 工具协作）

扩展激活时自动启动内嵌 MCP 服务器（默认 http://127.0.0.1:43210/mcp）
提供 5 个 MCP 工具：启动预览、重载游戏、获取日志、真机测试、版本发布
支持一键写入 Cursor / CodeBuddy 的 MCP 配置
AI 编程工具可直接操控游戏预览和发布全流程

🚀 快速开始

安装扩展：在 VSCode 扩展市场搜索 Weixin MiniGame Helper 安装
打开小游戏项目：在 VSCode 中打开包含 game.js 的目录
启动预览：使用命令面板（Ctrl+Shift+P / Cmd+Shift+P）输入 小游戏：打开预览
真机测试：命令面板输入 小游戏：真机测试，按提示配置 AppID 和密钥后扫码预览

📋 命令列表

命令	说明
`小游戏：打开预览`	打开预览面板，自动启动游戏
`小游戏：重新加载预览`	重载当前游戏预览
`小游戏：停止预览`	停止预览服务
`小游戏：真机测试`	生成真机预览二维码
`小游戏：MCP 配置`	在预览面板打开 MCP 配置页
`小游戏：复制 MCP 配置`	复制 MCP 配置 JSON 到剪贴板
`小游戏：清除真机测试配置（AppID 和密钥）`	删除已保存的密钥信息

所有命令可通过 Ctrl+Shift+P（macOS: Cmd+Shift+P）打开命令面板，输入「小游戏」快速搜索。

⚙️ 配置

扩展设置

设置项	说明
`miniGamePreview.appId`	微信小游戏 AppID（也可从 `project.config.json` 自动读取）
`miniGamePreview.privateKey`	代码上传密钥内容（PEM 格式，建议使用 Secrets 存储）
`miniGamePreview.privateKeyPath`	密钥文件路径（`.key` 文件）

真机测试配置

真机测试需要微信小游戏 AppID 和代码上传密钥：

在微信公众平台获取小游戏 AppID
在开发 → 开发设置 → 小程序代码上传中下载密钥文件
首次运行「小游戏：真机测试」时，扩展会弹出配置向导，引导你安全保存这些信息

安全说明：密钥通过 VSCode Secrets API 加密存储，不会以明文形式写入任何配置文件。

🔗 MCP 集成

扩展激活后会自动启动 MCP 服务器，AI 编程工具可通过以下配置接入：

自动配置（推荐）

在预览面板点击「MCP 配置」Tab，一键写入 Cursor 或 CodeBuddy 的配置文件。

手动配置

在 AI 工具的 MCP 配置文件中添加：

{
  "mcpServers": {
    "weixin-minigame-helper": {
      "url": "http://127.0.0.1:43210/mcp"
    }
  }
}

MCP 工具列表

工具	功能	参数
`run_game`	启动游戏预览	`workspacePath`（必填）
`reload_game`	热重载游戏	`workspacePath`（可选）
`get_logs`	获取游戏控制台日志	`filter`（可选，正则表达式）
`real_device_preview`	生成真机预览二维码	`workspacePath`（必填）
`publish`	发布版本到微信平台	`workspacePath`（必填）、`version`（必填）、`desc`（可选）

MCP 服务器使用固定端口 43210。若被占用会自动递增（最多尝试 10 次），可在「MCP 配置」Tab 中查看实际端口。

🌐 微信 API 兼容层

预览环境内置了完整的 wx.* API 模拟层，主要覆盖：

核心系统：wx.createCanvas()、wx.getSystemInfo()、wx.getWindowInfo() 等
网络与存储：wx.request()、wx.getStorageSync()、wx.setStorageSync() 等
媒体与渲染：wx.createImage()、wx.createInnerAudioContext()、wx.createOffscreenCanvas() 等
设备传感器：加速度计、陀螺仪、震动、电池等
输入与交互：触摸事件、wx.showToast()、wx.showModal() 等
帧动画：requestAnimationFrame()、cancelAnimationFrame()

兼容层持续完善中，可满足绝大多数微信小游戏的本地预览需求。

❓ 常见问题

Q: 提示「未找到 game.js」

确保打开的目录包含 game.js 文件。可通过预览面板的「WorkSpace」Tab 手动指定子目录路径。

Q: MCP 工具连接失败

检查端口是否与配置一致（默认 43210）。在预览面板「MCP 配置」Tab 可查看当前端口。

Q: 真机测试提示「IP 不在白名单」

在微信公众平台 → 开发 → 开发设置 → 小程序代码上传 → IP 白名单中添加本机公网 IP。

Q: 真机测试提示「app.js not found」（errcode 800059）

所用 AppID 对应的是「小程序」而非「小游戏」。请确认在微信公众平台注册时选择了「小游戏」类型。

Q: 密钥验证错误（invalid private key）

执行命令「小游戏：清除真机测试配置」后重新配置，确保密钥与 AppID 对应同一账号。

🔌 其他平台

本工具同时支持以下运行模式：

WorkBuddy 插件 — 作为 CodeBuddy/WorkBuddy 的 AI Agent 插件使用，通过斜杠命令驱动小游戏预览和发布
OpenClaw CLI — 独立命令行工具，适用于无 IDE 环境下的 CI/CD 自动化流程

📚 相关链接

Happy Coding! 🎉

微信小游戏助手

Weixin Mini Game