WMPFDebugger 常见问题排查指南：安装、版本兼容与运行调试全解析

• 开发工具
• 调试器
• 逆向工程

本篇指南以 WMPFDebugger 官方 FAQ（FAQ.zh.md）为核心，系统梳理微信小程序调试工具在使用过程中高频遇到的安装依赖、版本适配、进程连接与调试异常问题，并给出可复现的解决方案。读完本文，你将掌握 yarn 依赖安装的正确姿势、WMPF 版本号定位与适配方法、小程序闪退与空白页的排查思路，以及 macOS 与 WebView 场景下的特殊处理手段。

一、安装相关：从「卡住」到「跑通」

1.1 为什么必须使用 yarn，而不是 npm？

项目官方在 FAQ 中给出了两条硬性警告：

• 不要使用 NPM 包管理器，此项目使用yarn包管理器；
• 不要删除yarn.lock，frida API 更新很快，需要锁住依赖版本。

从仓库根目录的 package.json 与 yarn.lock 可以看出，项目依赖的核心包括frida（进程注入与 Hook 的底层能力）与ws（WebSocket 服务器），而yarn.lock中锁定的正是 frida 这类快速迭代的二进制依赖版本。一旦删除锁文件或用 npm 重装，frida 版本漂移可能导致 API 不兼容，进而引发运行时异常（见后文 1.3 节的典型报错）。

1.2yarn install卡在Building fresh packages怎么办？

现象：执行yarn install长时间卡在Building fresh packages，或提示需要安装 SDK。

根因：安装过程中需要下载frida的预编译二进制文件，这些文件托管在海外服务器，受网络环境影响可能非常慢或直接超时（FAQ 中引用了 Issue #58）。

解决方案：为安装过程配置代理，加速预编译文件下载：

set HTTP_PROXY=<YOUR_PROXY_ADDR> set HTTPS_PROXY=<YOUR_PROXY_ADDR> yarn

将<YOUR_PROXY_ADDR>替换为你自己的代理地址（例如http://127.0.0.1:7890）。FAQ 同时明确说明：本项目维护者不会对「如何使用代理」等网络/代理类问题提供进一步指导，代理属于通用环境问题。

1.3 报错Cannot read properties of undefined (reading 'parameters')

该报错在 FAQ 中有两条排查路径：

1. frida 版本不兼容：请使用yarn包管理器重新安装依赖，确保yarn.lock中锁定的 frida 版本被完整还原；
2. 权限差异：微信进程权限比node的执行权限高。此时将node提权执行，或让微信降权执行，使两个进程权限对齐。

从实现角度看，src/platform/win32.ts 中findWmpfProcess()会调用enumerateProcesses({ scope: frida.Scope.Metadata })读取进程元数据（如parameters.ppid、parameters.argv），如果 frida 版本不匹配或进程元数据不可读，读取parameters字段就会抛出类似 undefined 异常。这从源码层面印证了「版本锁定 + 权限对齐」两条对策的必要性。

二、版本兼容性：版本号定位与适配策略

2.1Error: [frida] version config not found: XXXXX

现象：启动调试器时报version config not found，其中XXXXX为你的 WMPF 版本号。

根因：当前的 WMPF 版本尚未被本工具适配。每次微信更新都可能附带新版本的 WMPF 运行时，而工具依赖针对特定版本逆向出的函数偏移量来实施 Hook。

解决方案（FAQ 原文）：

• 查看 README.zh.md 中的支持版本列表，确认当前版本是否已支持；
• 如果未支持，可以提交 Issue 请求适配；
• 也可以参照 ADAPTATION.md 自行寻找偏移量进行适配。

源码印证：在 src/index.ts 中，非--auto-detect模式下会尝试读取frida/config/${process.platform}/addresses.${wmpfVersion}.json，读取失败即抛出[frida] version config not found: ${wmpfVersion}。配置文件形如 frida/config/win32/addresses.19871.json：

{ "Version": 19871, "LoadStartHookOffset": "0x25CE150", "CDPFilterHookOffset": "0x30A84E0", "SceneOffsets": [64, 1472, 8, 1408, 16, 456] }

其中的LoadStartHookOffset对应AppletIndexContainer::OnLoadStart入口，CDPFilterHookOffset对应 CDP 消息过滤器，SceneOffsets用于定位「小程序场景号」字段的指针偏移链，详见 frida/hook.js 中patchOnLoadStart与patchCDPFilter的实现。

进阶选项：从 README 与 src/cli.ts 可知，Windows x86_64 还支持--auto-detect命令行参数，运行时自动检测 Hook 偏移量（Beta，尚未测试稳定性），对应 src/index.ts 中的autoDetectConfig()，它会在目标进程中加载 frida/autodetect/win32.js 完成偏移探测。

2.2 如何检查我的 WMPF 版本？

Windows：打开任务管理器，找到WeChatAppEx进程，右键点击「打开文件所在的位置」，查看路径中RadiumWMPF和extracted之间的数字即为版本号。

例如路径为%APPDATA%\Tencent\xwechat\xplugin\Plugins\RadiumWMPF\19871\extracted\runtime，则版本号为19871。

从源码看，src/platform/win32.ts 会通过进程启动参数中的--flue-runtime-dir（旧版本则回退到进程路径）用正则提取数字串作为版本号，与任务管理器查到的目录名一致。

macOS：README 给出了命令行方式：

# 查看版本字符串的数字 grep CFBundleVersion -A 1 "/Applications/WeChat.app/Contents/MacOS/WeChatAppEx.app/Contents/Info.plist"

对应 src/platform/darwin.ts 中读取Info.plist的CFBundleVersion字段的实现。

Linux：进程路径中通常含wmpf_release/xwechat_xxx_2.5.6.25665形式的版本串，src/platform/linux.ts 通过正则从二进制中提取主版本与子版本号，例如得到25665。

2.3 如何更新到最新的 WMPF 版本？

FAQ 按微信大版本分两种情况：

• 微信 4.x 及以上：从官网pc.weixin.qq.com下载最新版微信，最新版 WMPF 会随安装包一同安装；
• 微信 4.x 以下：在微信搜索框输入:showcmdwnd（注意不要按回车触发搜索），弹出命令窗口后输入以下命令并回车等待更新：

/plugin set_grayvalue=202&check_update_force

重启微信后生效。

版本支持范围提示：README 中列出的当前支持版本为 Windows x86_64 25715（最新）/25710/25558/25510/25459/25364 及更早版本（含自动检测 Beta），Linux x86_64 25665（最新）/14978/14910，macOS arm64 269136（最新）。对应的偏移量配置文件均位于 frida/config 目录下按平台与版本号组织。

三、运行与连接问题：闪退、白屏与无流量的系统排查

3.1 启动后小程序闪退怎么办？

FAQ 归纳了三大原因：

1. WebSocket 帧错误（Invalid WebSocket frame: invalid opcode 0）：不要使用全局代理（例如 yakit，参见 Issue #119），全局代理会劫持并破坏本地 WebSocket 流量；
2. 操作顺序错误：必须先运行npx ts-node src/index.ts，然后打开小程序，最后打开开发者工具；顺序不对可能导致闪退；
3. 版本不匹配：确保你的 WMPF 版本在支持列表中。

解决方案：严格按照 README.zh.md 的步骤顺序操作；确认 WMPF 版本已被适配；如果问题持续，尝试重启微信后再运行。

为什么顺序如此重要：从 src/index.ts 的主流程可以看到，启动命令会同时拉起三个关键组件——debugServer（小程序调试服务器，默认端口 9421）、proxyServer（CDP 代理服务器，默认端口 62000）以及fridaServer（自动查找WeChatAppEx进程并注入 frida/hook.js 中的 Hook 代码）。Hook 注入完成后终端会打印you can now open any miniapps，此时打开小程序才会被重定向到本地调试器；再打开 DevTools 访问 CDP 端口。若反序操作（先开 DevTools 或先开小程序），Hook 尚未就位，可能触发小程序崩溃或连接失败。

3.2 macOS 特殊：Error: Unable to access process with pid xxx from the current user account

这是 macOS SIP（System Integrity Protection，系统完整性保护）禁止对受保护进程进行调试所致，FAQ 给出两种解决办法：

1. （推荐）对 WeChatAppEx framework 进行 Ad-Hoc 重签名：

sudo codesign --force --sign - \ --preserve-metadata=identifier,entitlements,requirements \ "/Applications/WeChat.app/Contents/MacOS/WeChatAppEx.app/Contents/MacOS/WeChatAppEx"

2. （不推荐）关闭 SIP。

其中重签名方案风险更低：它在保留原有 identifier、entitlements、requirements 元数据的前提下，仅以临时身份（-）对目标可执行文件重签，从而绕过 SIP 对调试附加的限制。

3.3 打开devtools://devtools/bundled/inspector.html?ws=127.0.0.1:62000后页面空白

可能原因及解决方案：

1. 操作顺序错误：确保先打开小程序，再打开此链接。因为 CDP 代理只有在小程序成功回连到调试服务器后才有消息可转发（见 src/index.ts 中proxymessage的转发逻辑）；
2. 连接已断开：检查终端中是否有报错信息，必要时重新从第二步开始（即重新运行npx ts-node src/index.ts后再依次打开小程序与 DevTools）。

端口可调：FAQ 所指 URL 中的62000为默认 CDP 端口，定义于 src/cli.ts，可通过--cdp-port <port>参数修改（合法范围为 1~65535，见parse_port校验逻辑），同时--debug-port可修改小程序调试服务器端口（默认 9421，该默认值不建议随意更改，因为 Hook 写入的回连地址是固定的ws://localhost:9421，见 frida/hook.js）。

3.4 小程序无限加载中

FAQ 给出的临时对策：关闭本项目调试器，打开小程序正常加载一次，然后再打开本项目调试器，再打开小程序。

本质上是让小程序在无 Hook 状态下完成一次正常启动，清掉上次调试会话遗留的状态，再恢复调试环境重新加载。

3.5 启动成功但没有 Network 流量

排查重点：检查小程序是否内嵌 WebView。WebView 为独立进程，不属于小程序进程，需要单独调试（参见 Issue #60）。

补充说明：如果小程序使用了<webview>标签，也可以通过 EXTENSION.md 描述的方法附加到 WebView 标签页进行调试。

3.6 微信内置浏览器 / 公众号页面调试

FAQ 明确指出：基础支持已有，具体方法参见 EXTENSION.md，且目前仅有基础调试功能，不如小程序调试完善。

该扩展方案的核心思路是利用已有的调试协议：

1. 先按 README.zh.md 完整跑通一次小程序调试会话（建议用微信官方小程序 Demo 这类极简小程序初始化会话）；
2. 在 DevTools 中打开Protocol Monitor面板，启用 CDP 命令编辑器；
3. 发送Target.getTargets命令，在响应中列出所有浏览器标签页目标，定位想要调试的标签并复制其targetId；
4. 发送Target.attachToTarget并填入该targetId，即可附加到目标标签页。

注意事项：附加成功后Element 面板不会更新，无法用于检查 DOM 树；调试期间不能关闭小程序，否则会话会终止。

四、FAQ 之外：与文档配套的调试流程速览

FAQ 多次引用 README 中的操作顺序，这里将完整流程浓缩如下，便于对照排障：

1. 准备环境：node.js（至少 LTS v22）+ yarn 包管理器 + 基于 Chromium 的浏览器（Chrome、Edge 等）；
2. 安装依赖：git clone后执行yarn（务必保留yarn.lock，勿用 npm）；
3. 启动调试器：npx ts-node src/index.ts——同时启动调试服务器（9421）、CDP 代理服务器（62000）并向小程序运行时注入 Hook 代码；
4. 打开小程序：等待终端出现可打开小程序的提示后再操作；
5. 打开 DevTools：访问devtools://devtools/bundled/inspector.html?ws=127.0.0.1:62000。

此外，FAQ 中「版本不兼容」「闪退」「空白页」等多处问题，都与 frida/hook.js 中的两个核心 Hook 行为强相关：

• patchOnLoadStart（HookAppletIndexContainer::OnLoadStart）：将小程序启动场景号改写为1101（远程调试模式），并将回连 WebSocket 地址改写为ws://localhost:9421，同时把远程调试模式标志置 1；
• patchCDPFilter（Hook CDP 消息过滤器）：放行调试器发往小程序的 CDP 命令，绕过内置过滤器对本地调试来源的限制。

理解这两个 Hook 的职责，有助于判断「版本配置缺失」「无 CDP 流量」「小程序拒绝回连」等现象的根因方向。

五、总结：一张表记住 FAQ 排查要点

FAQ 面向的正是真实使用中最高频的排障场景；当遇到文档未覆盖的新问题时，官方也建议在提交 Issue 前先对照 FAQ 与已有 Issues，避免重复提问被直接关闭。

• 开发工具
• 调试器
• 逆向工程