WMPFDebugger: Chrome DevTools for the WeChat Mini-Program Runtime

What WMPFDebugger Actually Patches

WeChat mini-programs do not run in a normal browser tab. They run inside the WeChat Mini-Program Framework, a Chromium-derived runtime that WeChat ships and updates on its own schedule. The README describes the project as a debugger (tweak) that exploits the Remote Debug feature provided by wechatdevtools and patches several restrictions to force the miniapp runtime to expose the full Chrome Debug Protocol. That is the whole idea. Instead of building a bespoke inspector, it makes the runtime look like an ordinary CDP target, so any Chromium-based browser can attach to it.

The audience is narrow and specific. You are building or reverse-engineering mini-programs, you already have WeChat installed on Windows, Linux or macOS, and you want breakpoints, a console and a sources view rather than printf debugging. The README frames this as "yet another" debugger, which is an honest signal: this is one option in a small field, not the only one.

How the Hook, Proxy and CDP Port Fit Together

The moving parts are visible from the repository layout and package.json. The runtime dependencies are frida, protobufjs and ws. Frida is the instrumentation layer that injects the hook script into the miniapp runtime. ws provides the WebSocket side, and protobufjs handles the protocol messages the runtime exchanges. There is also a frida/ directory at the top level and a src/third-party directory, which the README states contains code extracted from wechatdevtools and fully copyrighted by Tencent Holdings Ltd.

The entry point is src/index.ts, described in the README as launching a debug server and a proxy server and injecting the hook script. The browser then connects to a WebSocket endpoint on a local port, which the README gives as 62000 in its example, and that port is configurable through CDP_PORT in src/index.ts. So the data flow is: hook inside the runtime, proxy bridging that to a WebSocket, browser DevTools front end speaking CDP over the socket.

The ordering constraint is the part people miss. The README warns that after starting the server you must launch the miniapp before launching the devtools, otherwise you will probably need to kill the server and redo the steps. The hook has to be in place before the runtime is fully up, so this is not a tool you can attach to a session that is already running.

Installing WMPFDebugger and Attaching a First Session

The prerequisites listed are node.js at LTS v22 or later, yarn, and a chromium-based browser such as Chrome or Edge. The README does not publish an npm package, so installation means cloning the repository. Step 1 clones it and installs dependencies with yarn.

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

Step 2 runs the TypeScript entry point directly with ts-node. This is the process that starts the debug server, the proxy server and the hook injection. Leave it running.

npx ts-node src/index.ts

Step 3 is to launch the miniapp you want to debug. Order matters here, and the README restates it: launch the miniapp before the devtools. Step 4 opens a Chromium-based browser at the DevTools front-end URL with the WebSocket pointing at the local port. The README uses 62000, and notes you can change CDP_PORT in src/index.ts.

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

You should land in a normal DevTools window with a console and a sources view, which is what the repository's screenshots show. Before any of this, though, check that your installed WMPF build is one the project supports. On macOS the README gives a one-liner for reading the bundle version.

grep CFBundleVersion -A 1 "/Applications/WeChat.app/Contents/MacOS/WeChatAppEx.app/Contents/Info.plist"

On Windows the README sends you to Task Manager, then WeChatAppEx, right click, Open file location, and the number between RadiumWMPF and extracted in the path is your version.

The Version Matrix Is the Real Constraint

This is where the project stops being a general-purpose debugger. Support is enumerated per platform and per WMPF build number. Windows has the longest list, from 11581 up through 25715, with an auto-detect mode marked beta that you enable by adding --auto-detect to your launch arguments. Linux has three entries, the newest being 25665. macOS arm64 has exactly one, 269136.

That asymmetry is the honest picture. If you are on macOS and your build is not 269136, the README offers no path except ADAPTATION.md. The README also states that adaptation requests are considered only for newer versions, and that the maintainer needs the binary to attempt it. So a user on an old or unusual build is effectively on their own.

The version list itself is a maintenance liability, but in an unusual direction: most of the entries carry contributor credits, which suggests adaptation is partly crowdsourced rather than done by one person. That is a reasonable model for a project whose target moves whenever Tencent ships a WeChat update. It also means your supported version may be supported because a stranger happened to submit a patch, not because anyone committed to maintaining it.

One entry is marked unstable: 11581, with the note that it will connect but crash the renderer. The README leaves it in the list anyway, which is more useful than silently dropping it.

Where WMPFDebugger Breaks or Is the Wrong Tool

The first failure mode is a WMPF version newer than anything listed. There is no forward compatibility guarantee, and auto-detect is explicitly labelled beta. If WeChat updates underneath you, expect to redo the attach and possibly to file an adaptation request and wait.

The second is the start order. Because the hook must be injected before the runtime is fully up, attaching to an already-running miniapp means killing the server and repeating steps 2 through 4. For anyone used to attaching a debugger to a live process, this is a real workflow cost.

The third is the embedded browser. The README points to EXTENSION.md for debugging web pages of the WeChat embedded browser, and then says plainly that this feature has many limitations currently and is simply a basic workaround. If your problem lives in the embedded browser rather than the mini-program runtime, this project is not the answer, and the README says so.

The fourth is legal and licensing, not technical. src/third-party contains code extracted from wechatdevtools, and the README states that code is fully copyrighted by Tencent Holdings Ltd. The project as a whole is GPLv2, but that does not launder the provenance of that directory. If you plan to redistribute anything, that directory is the thing to look at first.

Finally, the README's own support posture is a constraint. It directs you to FAQ.zh.md, which is Chinese only, and warns that newly submitted issues with existing solutions in the FAQ will be closed without any response. If you cannot read Chinese and your question is already answered there, you may get nothing back.

How It Differs from WeChatOpenDevTools and Similar Tools

The related searches around this project point at WeChatOpenDevTools, Wxhelper and Wedecode. What distinguishes WMPFDebugger is the mechanism described in its README: it exploits the Remote Debug feature from wechatdevtools and patches restrictions so the runtime speaks full CDP to a stock Chromium browser. The practical consequence is that you use the DevTools front end you already know, at devtools://devtools/bundled/inspector.html, rather than a custom inspector UI. Tools that ship their own interface trade that familiarity for not depending on a Chromium browser being installed and pointed at the right WebSocket URL.

The second difference is the frida dependency. Instrumentation through Frida is what lets the project inject a hook into a running native runtime, and it is also why platform coverage is uneven: the Windows list is long, Linux has three builds, macOS arm64 has one. A tool that does not hook the native runtime would not have that per-platform version matrix, but it would also not need one.

I would not treat any of these as strictly better. The right question is which one supports the exact WMPF build you have installed, because that is the binding constraint for all of them.

Licence, Attribution and Upgrade Cost

WMPFDebugger is licensed under GPLv2, and package.json records the SPDX identifier as GPL-2.0-only. The README spells out the obligations: if you redistribute, modify or publish a derivative, you must comply with GPLv2, preserve applicable copyright and license notices, and meet the GPLv2 source-code requirements when distributing covered binaries or modified versions. It also asks, separately from the licence, that you not remove existing attribution or contributor credits and that you acknowledge WMPFDebugger and its contributors as upstream. That last part is a request, not a condition, and the README says as much. This is a description of what the project states, not legal advice; if you are shipping something derived from it, have someone qualified read the licence and the third-party directory.

Upgrade cost is dominated by the version matrix. Upgrading WeChat can move you off a supported WMPF build. The README gives two paths for getting a newer WMPF. On WeChat version 4.x and above, download the latest installer from pc.weixin.qq.com, since the WMPF bundle ships inside it. Below 4.x, type :showcmdwnd in the search bar without hitting enter, then run /plugin set_grayvalue=202&check_update_force in the command window and restart WeChat. Neither path tells you whether the resulting build is one WMPFDebugger supports, so check the version list after upgrading, not before. If it is not listed, ADAPTATION.md is the next file to open.

Editorial conclusion

Adopt WMPFDebugger if you are debugging a mini-program against a WMPF build that appears in the Windows, Linux or macOS version lists, and if you can start the server before the miniapp every time. Do not adopt it if your WeChat build is newer than the newest listed version and you are not willing to adapt it yourself through ADAPTATION.md, or if you need a supported, vendor-backed toolchain. Before anything else, confirm your installed version by checking the number between RadiumWMPF and extracted in the WeChatAppEx file path, and read FAQ.zh.md, because the README states that issues with existing solutions there are closed without response.

Frequently asked questions

Official sources

1. evi0s/WMPFDebugger on GitHub
2. Issues
3. License: GPL-2.0
4. README