# Wedecode: Automated Source Recovery for WeChat Mini-Program Packages

> Wedecode decompiles WeChat mini-program wxapkg packages back to their original source code, supporting cross-platform use on Windows, macOS, and Linux. It is published under GPL-3.0, targets security auditors and developers doing code review, and requires Node.js 18 or later.

**biggerstar/wedecode** — 全自动化，微信小程序 wxapkg 包 源代码还原工具, 线上代码安全审计，支持 Windows, Macos, Linux

- Repository: https://github.com/biggerstar/wedecode
- Stars: 3,202 · Forks: 714
- Language: TypeScript
- License: GPL-3.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/biggerstar-wedecode

## What Wedecode Solves and Who It Is For

WeChat mini-programs are distributed as compiled wxapkg bundles. The source code, WXML templates, WXSS stylesheets, WXS scripts, and JSON configuration files are packed, and in some cases encrypted, before distribution. There is no official way to recover the original source from a deployed package.

Wedecode automates the reverse of that process. It takes one or more wxapkg files and outputs a reconstructed source tree with JS, WXML, WXSS, WXS, JSON, and other asset types restored and formatted. The README states the use case as online code security auditing for quickly finding vulnerabilities and learning decompilation principles. The disclaimer in the repository explicitly restricts usage to cases within national law and prohibits any illegal application.

The primary audience is security engineers auditing deployed mini-programs for vulnerabilities, and developers who need to examine third-party packages or recover code from backups. It is not a tool for bypassing licensing or distributing others' code without permission.

## What Wedecode Recovers and How It Is Organized

Wedecode supports both mini-programs (小程序) and mini-games (小游戏), including sub-packages and plugin code. The output categories, as listed in the README, are:

- JS code recovery
- WXML template code recovery
- WXSS stylesheet code recovery
- WXS script recovery
- JSON file recovery
- Other file types: media assets, WebAssembly, workers, and similar resources
- All output code is formatted (beauty output)

The tool also performs mini-program package scanning and supports automatic decryption of encrypted wxapkg packages. A visual UI is available alongside the CLI.

The top-level repository structure shows a `decryption-tool/` directory, a `src/` directory holding the TypeScript source, a `public/` directory for the browser UI, and a `test/` directory. The project is built with Vite and distributed as an npm package named `wedecode` with the version at 0.0.0 in the current source.

## Four Ways to Run Wedecode

The README describes four distinct run modes, which makes the tool accessible to both engineers comfortable in a terminal and those who prefer a visual interface.

The first mode is online via GitHub Codespaces. If you do not want to install anything locally, you can use the template button in the repository to open a Codespace and run `npm run ui` in the terminal after initialization. This requires a stable internet connection.

The second and most common local mode is global npm installation:

```shell
# Windows
npm i wedecode -g
# macOS
sudo npm i wedecode -g
```

After installation, launch the visual browser UI:

```shell
wedecode ui
```

Or run in interactive CLI mode, which guides you through each step:

```shell
wedecode
```

Or pass arguments directly for a non-interactive run:

```shell
wedecode ./name.wxapkg
wedecode ./  --out ./output_path
```

The fourth mode is running from source:

```shell
git clone https://github.com/biggerstar/wedecode
cd wedecode
npm install
npm run start
```

Node.js v18 or later is required. If npm is slow, the README suggests switching to the Taobao mirror: `npm config set registry https://registry.npmmirror.com`.

## CLI Parameters and Output Structure

The command-line interface accepts a set of named parameters that cover most auditing workflows:

| Parameter | Purpose |
|---|---|
| `ui` | Launch local visual UI |
| `<packages...>` | Path to wxapkg file or directory |
| `-o, --out <path>` | Output directory (defaults to OUTPUT in the same folder) |
| `--open-dir` | Open output directory when done |
| `--clear` | Clear previous output before running |
| `--px` | Parse CSS using px units instead of the default rpx |
| `--unpack-only` | Unpack only, skip decompilation |

When processing a directory, Wedecode compiles all wxapkg files found there. For sub-packages, the README recommends placing them alongside the main package in the same directory so the tool can resolve cross-package dependencies. If a dependency is missing, the output will contain placeholder templates rather than real code, because WeChat checks for all declared sub-packages at runtime and generates defaults for missing ones.

Output follows a predictable structure:

```
OUTPUT
├── app.json
├── pages/
├── components/
└── @babel/
```

## The Polyfill Mechanism for Overriding Compiled Modules

Wedecode includes a polyfill system that lets auditors replace specific compiled output modules with custom JS files before decompilation runs. This is useful when a particular module compiles to code that is hard to read and you have a known-good replacement.

To use it, create a `polyfill/` subdirectory in the same directory as your target wxapkg files, then place JS files at paths that match the output module names:

```
├── target_dir
│   ├── xxx.wxapkg
│   └── polyfill/
│       └── @babel/
│           └── array.js
```

If the output would contain `@babel/array.js`, Wedecode finds the polyfill and uses your file instead of the decompiled version. The output structure mirrors the polyfill path:

```
OUTPUT
└── @babel/
    └── array.js
```

This mechanism is specific to Wedecode and is not present in simpler wxapkg unpackers. It reduces the manual cleanup step after decompilation when you already know what a module should contain.

## License Implications and Limitations

Wedecode is released under GPL-3.0. This is a copyleft license: if you build a tool or service that incorporates Wedecode's code and distribute it, you must release the source of that tool under GPL-3.0 as well. For internal security auditing use where you do not distribute software containing Wedecode's code, the GPL-3.0 terms are generally less restrictive. For any commercial product that ships Wedecode as a component, legal review is necessary before distribution.

The tool works only with the wxapkg format used by WeChat. Other mini-program platforms use different package formats, and the README makes no claims about supporting them.

The package version in package.json is 0.0.0, which signals that the project does not yet use semantic versioning in a formal way. There are no GitHub releases. The last push was on 2026-08-27, which is recent. The npm package name is `wedecode` and the binary is installed as `wedecode`.

A naming note: a company called Wedecode (wedecode.io) operates independently from this repository. Search results for the name will return both. This tool is the biggerstar/wedecode project on GitHub, an npm package for wxapkg decompilation, with no relationship to that company.

The npm package version in package.json is 0.0.0, which indicates the project has not yet adopted semantic versioning. There are no GitHub releases to track. Running `npm view wedecode` in a terminal shows the current published version on the npm registry.

## Conclusion

Wedecode is worth using for legitimate security audits of WeChat mini-programs when you need a cross-platform tool with an optional GUI and automatic package decryption. Its GPL-3.0 license means any application you build on top of it must also be released under GPL-3.0 if distributed. Verify that your use case falls within your local legal framework before proceeding. The polyfill override mechanism is a practical feature for auditors who need to replace specific compiled modules with readable versions. The project does not support mini-program package formats outside the wxapkg format.

## FAQ

### How do I install Wedecode on macOS?

Run `sudo npm i wedecode -g` in your terminal. Node.js v18 or later is required. After installation, run `wedecode ui` to open the visual interface or `wedecode` for the interactive CLI.

### What happens if some wxapkg sub-packages are missing during decompilation?

The README explains that WeChat checks for all declared sub-packages and generates default templates for any that are missing. Wedecode will output those default templates rather than real source code. To get complete output, place all sub-packages in the same directory before running the tool.

### Can Wedecode decompile encrypted wxapkg files automatically?

Yes, automatic decryption of mini-program packages is listed as a supported feature in the README.

## Sources

- [biggerstar/wedecode on GitHub](https://github.com/biggerstar/wedecode)
- [Issues](https://github.com/biggerstar/wedecode/issues)
- [License: GPL-3.0](https://github.com/biggerstar/wedecode/blob/main/LICENSE)
- [README](https://github.com/biggerstar/wedecode/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/biggerstar-wedecode