WMPFDebugger 安装使用教程 (Windows 10)

一、工具简介

WMPFDebugger 是一个用于调试微信小程序的调试工具，利用微信开发者工具的远程调试功能，通过注入 Frida 脚本来突破小程序运行时的限制，使其支持完整的 Chrome Debug Protocol (CDP)，从而可以直接使用 Chrome/Edge 等浏览器的开发者工具进行调试。

项目地址: https://gitcode.com/gh_mirrors/wm/WMPFDebugger

二、环境要求

2.1 必需软件

2.2 安装 Node.js (推荐使用 nvm 管理)

# 安装 nvm-windows
# 下载地址: https://github.com/coreybutler/nvm-windows/releases

# 安装 Node.js LTS 版本
nvm install 22

# 切换到 Node.js 22
nvm use 22

# 验证安装
node -v
npm -v

三、安装步骤

3.1 克隆项目

# 从 GitCode 克隆
git clone https://gitcode.com/gh_mirrors/wm/WMPFDebugger.git

# 进入项目目录
cd WMPFDebugger

3.2 安装依赖

# 使用 npm 安装
npm install

# 或使用 yarn
yarn install

3.3 运行项目

npm run start

四、常见问题及解决方案

4.1 ES Module 导入错误

错误信息:

SyntaxError: Cannot use import statement outside a module

原因: 项目使用 ES Module 语法，但 Node.js 默认使用 CommonJS。

解决方案:

项目已配置 tsx 作为运行器，会自动处理 TypeScript 和 ES Module。如果遇到问题，可以检查 package.json:

{
  "scripts": {
    "start": "tsx src/index.ts"
  },
  "devDependencies": {
    "tsx": "^4.19.0"
  }
}

4.2 第三方模块 require 错误

错误信息:

Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported

原因: 项目中 src/third-party/ 目录下的文件是 CommonJS 模块，在 ES Module 环境下需要特殊处理。

解决方案:

这些文件已重命名为 .cjs 扩展名，代码中使用 createRequire 来加载:

import { createRequire } from "node:module";
const require = createRequire(import.meta.url);

const codex = require("./third-party/RemoteDebugCodex.cjs");
const messageProto = require("./third-party/WARemoteDebugProtobuf.cjs");

4.3 Frida 模块未安装

错误信息:

Cannot find module 'frida'

解决方案:

npm install frida

如果网络问题导致安装失败，可以切换 npm 源:

# 切换到官方源
npm config set registry https://registry.npmjs.org/

# 安装
npm install frida

# 安装完成后可切换回国内镜像
npm config set registry https://registry.npmmirror.com/

4.4 frida 目录缺失

错误信息:

Error: [frida] hook script not found

原因: frida/ 目录未从 Git 检出。

解决方案:

# 恢复 frida 目录
git checkout HEAD -- frida

4.5 端口绑定失败 (EINVAL)

错误信息:

Error: listen EINVAL: invalid argument 0.0.0.0:9421

可能原因:

1. Windows NAT 服务异常
2. VPN/代理软件干扰
3. 防火墙/杀毒软件阻止
4. 端口被系统保留

解决方案:

# 方案1: 重启 Windows NAT 服务 (管理员权限)
net stop winnat
net start winnat

# 方案2: 检查端口排除范围
netsh interface ipv4 show excludedportrange protocol=tcp

# 方案3: 临时禁用 VPN/防火墙后重试

# 方案4: 使用自定义端口运行
npx ts-node src/index.ts --debug-port 8080 --cdp-port 9222

4.6 端口权限不足 (EACCES)

错误信息:

Error: listen EACCES: permission denied 0.0.0.0:62000

解决方案:

# 以管理员身份运行 PowerShell
# 或更换为非保留端口 (如 9222)

五、使用方法

5.1 启动调试服务

npm run start

成功启动后会显示:

[server] debug server running on ws://localhost:9421
[server] debug server waiting for miniapp to connect...
[server] proxy server running on ws://localhost:9222
[server] link: devtools://devtools/bundled/inspector.html?ws=127.0.0.1:9222

5.2 启动小程序

1. 打开微信 PC 版
2. 启动任意需要调试的小程序
3. 确保小程序版本与 frida/config/ 中的配置文件匹配

5.3 打开开发者工具

在 Chrome 或 Edge 浏览器中访问:

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

5.4 命令行参数

npx ts-node src/index.ts --help

# 可用参数:
#   --debug-port <port>  调试服务器端口 (默认: 9421)
#   --cdp-port <port>    CDP 代理服务器端口 (默认: 9222)
#   --debug-main         输出主进程调试信息
#   --debug-frida        输出 Frida 客户端信息

六、支持的微信版本

查看完整支持列表请参考项目 README.md

七、查看当前 WMPF 版本

1. 打开任务管理器
2. 找到 WeChatAppEx.exe 进程
3. 右键 → 打开文件位置
4. 查看路径中 RadiumWMPF 后面的数字

八、注意事项

1. 启动顺序: 先启动调试服务器，再打开小程序，最后打开 DevTools
2. 版本匹配: 小程序版本必须在 frida/config/ 中有对应配置
3. 网络环境: 确保没有 VPN 或代理干扰本地端口绑定
4. 权限问题: 如遇权限问题，尝试以管理员身份运行

九、故障排除

如果遇到问题，按以下顺序排查:

1. 检查 Node.js 版本 (node -v 应为 v22+)
2. 检查依赖是否完整 (npm install)
3. 检查 frida/ 目录是否存在
4. 检查端口是否被占用或保留
5. 尝试以管理员权限运行
6. 查看项目 Issues: https://github.com/evi0s/WMPFDebugger/issues

十、安装效果

本教程基于 Windows 10 环境，Node.js v22 测试编写