使用 WMPFDebugger 调试微信小程序 — Windows 平台小程序远程调试工具指南

示例：

• 使用 WMPFDebugger 查看微信小程序控制台
• 在 Windows 上调试微信小程序

项目简介

WMPFDebugger 是一个开源工具，通过 Frida 注入微信小程序的 Windows 运行时（WMPF），解除 Chrome 调试协议（CDP）的过滤限制，让你在 Windows 上也能用 Chrome DevTools 调试任意微信小程序。

本文主要介绍如何使用它完成：

在 Windows 微信中打开小程序，用浏览器 DevTools 查看 Console 日志、Network 请求和 Sources 源码

项目地址：

https://github.com/evi0s/WMPFDebugger

验证环境：

开源项目可能会更新，如果命令或界面与本文不同，请优先查看项目最新 README。

最终效果

完成本文操作后，可以实现：

• 在 Chrome / Edge 浏览器中打开 DevTools，查看小程序 Console 日志
• 查看小程序的 Network 请求
• 查看小程序 Sources 源码
• 断点调试小程序 JavaScript

最终使用流程：

克隆并安装依赖
    ↓
启动 WMPFDebugger 服务
    ↓
打开微信小程序
    ↓
浏览器打开 DevTools 连接

使用前准备

开始前需要准备：

• Git
  • 也可以直接去github手动下载
• Node.js >= 22 LTS
• Yarn 包管理器
• Chromium 浏览器（Chrome / Edge）
• 微信 PC 版（已安装 WMPF 运行时）
  • 注意这里演示的版本，这个开源项目适配的版本有限。如果你使用的微信的WMPF版本没有被项目内置，则需要手动去获取Version、LoadStartHookOffset、CDPFilterHookOffset以及SceneOffsets。
  • 但是可以关注下项目的Issues，有很多人会直接发其他版本的值。
  • 具体适配的版本可以查看下载后的项目路径 \WMPFDebugger-main\frida\config\addresses.{WMPF版本}.json
    • 写此文章时，只支持了v11581—v20079。
      • 本文章用的应该是当前最新的v25297

检查环境：

node --version
yarn --version
git --version

如果命令可以正常输出版本号，说明环境已经安装完成。

一、下载项目(手动下载可以跳过此步)

执行：

git clone https://github.com/evi0s/WMPFDebugger

进入项目目录：

cd WMPFDebugger

如果需要固定到指定版本：

git checkout master

确认当前版本：

git rev-parse HEAD

此处可插入项目下载完成后的目录截图

二、安装依赖

yarn install

注意：本项目必须使用 yarn，不要用 npm。也不要删除 yarn.lock。

安装成功后的输出类似：

[1/5] Validating package.json...
[2/5] Resolving packages...
[3/5] Fetching packages...
[4/5] Linking dependencies...
[5/5] Building fresh packages...
success Saved lockfile.
Done in 38.62s.

安装完成后项目目录中会生成 node_modules 目录。

三、修改配置

通常不需要修改配置，默认即可。

可选参数：

示例：

npx ts-node src/index.ts --cdp-port 9000 --debug-main

如何手动适配新版 WMPF

如果你换了微信版本，报 version config not found: 25298(版本号)，需要自行适配。

配置文件位置：

WMPFDebugger/
  └── frida/
      └── config/
          └── addresses.{版本号}.json    ← 就在这里

自行反编译或者去项目Tissues里获取到值后，创建对应版本的 JSON 文件：

{
    "Version": 25298,
    "LoadStartHookOffset": "0xXXXXXXX",
    "CDPFilterHookOffset": "0xXXXXXXX",
    "SceneOffsets": [64, 1496, 8, 1432, 16, 456]
}

文件命名规则： addresses.{WMPF版本号}.json

版本号从哪里看？任务管理器找到 WeChatAppEx.exe 进程 → 右键打开文件位置 → 路径中 RadiumWMPF\{版本号}\extracted\runtime 的数字就是。

四、启动项目

执行：

npx ts-node src/index.ts

注意：一定要在微信已经打开、且 WMPF 运行时已加载的情况下启动。

如果微信还没开，会报 WeChatAppEx.exe process not found 错误。

启动成功后，控制台会出现：

[server] debug server running on ws://localhost:9421
[server] debug server waiting for miniapp to connect...
[server] proxy server running on ws://localhost:62000
[server] link: devtools://devtools/bundled/inspector.html?ws=127.0.0.1:62000
[frida] script loaded, WMPF version: 25297, pid: 13644
[frida] you can now open any miniapps

判断是否启动成功：

• 没有持续报错；
• 控制台出现 debug server running 和 proxy server running；
• 出现 frida script loaded 并显示了 WMPF 版本号；
• 指定端口开始监听；
• 项目进入等待小程序连接的状态。

五、按照正确顺序操作

这是整个工具最关键的地方，启动顺序不对会直接失败。

正确顺序：

① 启动 WMPFDebugger 服务
        ↓
② 等待服务启动成功（看到 frida script loaded）
        ↓
③ 打开小程序（微信中打开任意小程序）
        ↓
④ 打开浏览器 DevTools

第一步：启动 WMPFDebugger

npx ts-node src/index.ts

正确现象：

[server] debug server running on ws://localhost:9421
[server] proxy server running on ws://localhost:62000
[frida] script loaded, WMPF version: XXXXX

第二步：打开小程序

在微信中打开任意一个小程序（不是公众号文章、不是聊天窗口，是"小程序"），在小程序里随便点击几下。

正确现象：

[miniapp] miniapp client connected

小程序刚打开时可能会反复断连重试几次，这是正常的。当其不再弹出新的连接就代表已经成功了。

第三步：打开浏览器 DevTools

访问链接在输出的信息中可以看到直接复制：

devtools://devtools/bundled/inspector.html?ws=127.0.0.1:62000

注意：必须使用 devtools:// 协议开头，不是 http://。把地址完整复制到 Chrome / Edge 地址栏回车即可。

正确现象：

[cdp] CDP client connected

然后就可以在 DevTools 中看到小程序的控制台输出、网络请求和源码了。

六、具体使用方法

功能一：查看 Console 日志

打开 DevTools 后自动进入 Console 面板，小程序的 console.log() 输出会实时显示在这里。

操作步骤：

1. 确保 WMPFDebugger 已启动；
2. 打开小程序；
3. 打开 DevTools，切换到 Console 面板。

正确结果：

Console 面板中显示小程序的日志输出

功能二：查看 Network 请求

操作步骤：

1. 在 DevTools 中切换到 Network 面板；
2. 刷新小程序或触发网络请求；
3. 查看请求列表和详情。

正确结果：

Network 面板中显示小程序的 HTTP / HTTPS 请求

注意：小程序的请求走的是 WMPF 内部的网络栈，不是浏览器标准请求，部分请求信息可能不完整。

功能三：断点调试 JavaScript

操作步骤：

1. 在 DevTools 中切换到 Sources 面板；
2. 找到小程序源码文件；
3. 点击行号设置断点；
4. 触发该段代码执行。

正确结果：

代码在断点处暂停，可以查看变量、调用栈、单步执行

七、如何验证是否成功

1. 检查项目日志

启动阶段应该出现：

[frida] script loaded, WMPF version: 25297, pid: 13644
[frida] you can now open any miniapps

连接阶段应该出现：

[miniapp] miniapp client connected
[cdp] CDP client connected

2. 检查最终界面

• DevTools 页面不是空白
• Console 面板有日志输出（至少可以看到小程序的日志，或者无日志时不报错）
• 断点可以命中
• 小程序正常运行、没有闪退

3. 执行最小验证

在 DevTools Console 面板执行：

console.log("Hello from DevTools");

预期结果：

Console 面板中显示 "Hello from DevTools"

如果日志、界面和最终功能均符合预期，说明项目已经正常运行。

八、常见问题

1. yarn install 失败 / frida 下载慢

现象

[4/5] Building fresh packages...
error D:\...\node_modules\frida: Command failed.

解决

设置代理后重新安装：

set HTTP_PROXY=http://127.0.0.1:7890  # 端口取决于你使用的代理软件端口
set HTTPS_PROXY=http://127.0.0.1:7890
yarn install

如果仍然失败，可以尝试：

yarn cache clean
# 或删除 node_modules 和 yarn.lock 后重新 install
rm -rf node_modules
yarn install

2. 项目启动报 WeChatAppEx.exe process not found

原因

微信的 WMPF 运行时还没加载，WeChatAppEx.exe 进程不存在。

解决

1. 先打开微信；
2. 在微信中随便打开一个小程序（触发 WMPF 加载）；
3. 重新运行 npx ts-node src/index.ts。

可以用任务管理器确认 WeChatAppEx.exe 是否存在。

3. 项目启动成功，但没有效果

排查顺序

1. 是否按照正确顺序启动（服务 → 小程序 → DevTools）；
2. 小程序是否已经打开（微信中打开小程序页面，不是停留在聊天列表）；
3. WMPF 版本是否在支持列表中；
4. 浏览器地址是否正确（必须是 devtools:// 开头）；
5. 端口是否被防火墙拦截；
6. 控制台中是否存在连接错误；
7. 是否开了全局代理工具（如 yakit）——会导致 Invalid WebSocket frame 错误。

4. 端口被占用

Windows：

netstat -ano | findstr :62000
netstat -ano | findstr :9421

找到占用端口的程序后：

• 关闭该程序；
• 或使用 --cdp-port 和 --debug-port 修改端口；
• 然后重新启动项目。

5. 小程序闪退

常见原因：

• 全局代理工具（如 yakit）导致 WebSocket 帧错误，关闭代理工具再试；
• 操作顺序不对：先开小程序再启动服务容易闪退；
• WMPF 版本不在支持列表中。

6. Error: [frida] version config not found: XXXXX

当前 WMPF 版本还没有被适配。可以在 GitHub的Issue 查看有人适配没有，或自行适配。

九、停止项目

在启动项目的终端中按：

Ctrl + C

确认项目已经停止：

netstat -ano | findstr :62000
netstat -ano | findstr :9421

如果端口不再被占用，说明项目已正常停止。

十、卸载与清理

如果不再使用，直接删除项目目录即可：

cd ..
rmdir /s WMPFDebugger

没有全局安装依赖，不涉及环境变量或系统配置更改。

项目原理简述

WMPFDebugger 的工作过程可以简单理解为：

微信小程序（WMPF 运行时）
        ↓
Frida 注入 flue.dll
   ├─ patch OnLoadStart → 强制开启调试模式
   ├─ patch CDP 过滤器 → 放行调试协议消息
   └─ patch 场景号 → 伪装成调试允许的场景
        ↓
debug server (9421) ← 接收小程序调试消息
        ↓
proxy server (62000) ← 转换为标准 CDP 协议
        ↓
浏览器 DevTools ← 显示 Console / Network / Sources

一句话总结：

用 Frida 给微信小程序的 WMPF 运行时打三个 Patch，解除微信的调试限制，再把私有协议转成 Chrome 看得懂的 CDP 协议。

WMPF 每次更新都会变更函数地址和结构体偏移，这就是为什么每个版本需要单独的适配配置。

总结

本文使用 WMPFDebugger 实现了：

在 Windows 微信中打开小程序后，用 Chrome DevTools 查看 Console 日志、Network 请求和 Sources 源码

完整流程：

准备环境 (Node.js + yarn)
    ↓
下载项目 (git clone)
    ↓
安装依赖 (yarn install)
    ↓
启动项目 (npx ts-node src/index.ts)
    ↓
打开微信小程序
    ↓
打开浏览器 DevTools
    ↓
验证功能

使用时主要注意：

1. 运行环境版本：Node.js 必须是 22 以上 LTS 版本；
2. WMPF 版本兼容：如果报 version config not found 说明需要适配；
3. 启动顺序：服务 → 小程序 → DevTools，顺序错了一定要重来；
4. 全局代理工具会导致连接失败，启动前请关闭；
5. 小程序刚打开时反复断连是正常的，几秒后会稳定；

快速命令

# 1. 下载项目
git clone https://github.com/evi0s/WMPFDebugger

# 2. 进入目录
cd WMPFDebugger

# 3. 安装依赖
yarn install

# 4. 启动项目
npx ts-node src/index.ts