run-liyi/wechatpay: A Local Electron Viewer for WeChat Pay Bill Exports

What run-liyi/wechatpay Does With a WeChat Pay Bill Export

WeChat Pay does not give you a queryable statement. It gives you a file. You request a download inside the app, wait for an encrypted archive to reach your mailbox, get the password through 服务通知, and end up with a spreadsheet that has roughly sixteen rows of header and explanatory text above the real table. Reading that by hand across a year of spending is tedious, and pivoting it in Excel means rebuilding the same formulas every time.

This project is a desktop application that takes that spreadsheet and produces the views you would otherwise build yourself: totals for income and expense, a net figure, a transaction count and a date range; breakdowns by payment method, transaction type and status; rankings by merchant, type and payment method; and a trend line you can switch between daily, weekly and monthly. There is also a searchable detail view with filters for direction and status.

The intended user is a single person reviewing their own spending on their own machine. The README is explicit that the app runs entirely locally and does not upload data to a server, and the repository ships only a fabricated sample at sample/demo-bill.xlsx. If you need multi-user reporting, accounting-grade categorisation or bank reconciliation, this is not that tool.

Electron Process Split, SheetJS Parsing and the Header Skip

The architecture follows the standard Electron two-process shape, and the split is visible in the repository layout. main.js owns the window, the file picker dialog, Excel parsing, metadata extraction and report export. renderer.js owns interaction, the analysis functions and chart rendering. preload.js sits between them, and the parse entry point is an IPC handler registered on the main side, which the README shows as ipcMain.handle('parse-bill-file', ...).

The parsing itself is done with xlsx (SheetJS), listed as a dependency at ^0.18.5. The README states that the tool automatically recognises and skips the header block, which is the part of the pipeline that matters most in practice: the column names it expects are 交易时间, 交易类型, 交易对方, 商品, 收/支, 金额(元), 支付方式, 当前状态, 交易单号, 商户单号 and 备注. Those names are the contract. If a future WeChat export renames or reorders them, the analysis functions that group by dimension have nothing to bind to.

Analysis is a set of pure functions over the parsed rows. analyzeOverview computes totals and the time range; analyzeByDimension groups rows by a chosen field and separates income from expense; analyzeTrend buckets rows by day, week or month. Chart.js 4.4 renders the output as bars, pie and doughnut charts, and line charts for trends. The chart theme lives in chart-theme.js at the repository root. The renderer is built with Vite, which is why npm start runs a renderer build before launching Electron.

Installing run-liyi/wechatpay and Reading Your First Bill

The README gives the development path directly: install dependencies, then start. Node.js 14.0 or higher is required for development only, and the packaged builds do not need it.

npm install
npm start

The start script is not a bare electron launch. In package.json it is defined as npm run build:renderer && electron ., so the Vite renderer bundle is produced first and Electron opens the welcome screen afterwards. If you want to work on the interface with hot reload rather than a built bundle, the dev script runs vite on its own.

npm run dev

To produce installers rather than run from source, the platform-specific build scripts wrap electron-builder after the same renderer build. Windows targets NSIS with x64, and the output directory is release.

npm run build:win
npm run build:mac
npm run build:linux

In the running app, the workflow is: click 选择账单文件 in the left panel, pick your exported .xlsx or .xls file, and the parser reports what it found. Switch views from the left navigation. 导出报告 opens a save dialog and writes an Excel workbook with separate sheets for summary, category, daily and detail data. If you want to see the expected shape before touching your own data, open sample/demo-bill.xlsx, which the repository describes as completely fabricated.

The Export Format Is the Hard Boundary

The most consequential limitation is upstream of the code. WeChat offers two bill purposes, and only one of them produces something this tool can read. Choosing 用于个人对账 yields an Excel or CSV file. Choosing 用做证明材料 yields a PDF with an official seal, and the README states plainly that the tool cannot parse it. If you already requested the wrong one, you wait out another delivery cycle.

The second constraint is that a single run handles a single file. The README answers this in its own FAQ: to analyse several periods, merge them in Excel first and import the result. That pushes the awkward part back onto the user, and merging bills by hand risks duplicating the header block the parser is designed to skip.

There is also no documented rollback or data-migration path, because there is no persistent store to migrate: the app reads a file, holds the parsed rows in memory, and writes a report only when you ask it to. That is good for privacy and bad for anyone expecting sessions to resume. The README does not document a way to save and reopen an analysis.

Finally, the export is capped at one year of transactions, a limit WeChat imposes rather than the project. Long-horizon analysis therefore means stitching exports together outside the tool.

How It Differs From a Spreadsheet PivotTable or a Finance App

The obvious alternative is the spreadsheet you already have. Excel or LibreOffice can produce every number this app shows: sum by 交易对方, count by 支付方式, a pivot chart by month. The difference is setup cost and repetition. A PivotTable is rebuilt or refreshed for each new export, and the sixteen-row header block has to be handled before any pivot works. This project encodes that handling once, in the parser, and applies it on every import. If you analyse one bill a year, the spreadsheet wins on simplicity. If you import monthly, the fixed pipeline earns its place.

A second alternative is a hosted personal-finance service that aggregates accounts and categorises spending automatically. Those services generally require handing transaction data to a third party, which is exactly what the README's privacy section is written to avoid. This project's trade-off is the inverse: no server, no account, no automatic categorisation of merchants into budget buckets, and no cross-institution view. It only knows what is in the WeChat Pay export you hand it.

Licence, Maintenance and What an Upgrade Costs

The README ends with an MIT License section, and package.json carries "license": "MIT" with the package name wechat-bill-analyzer at version 1.0.0. MIT is permissive: you can use, modify and redistribute the code, including in closed products, provided the copyright notice and permission notice are preserved. That is a description of the licence text, not legal advice, and the repository has no separate LICENSE file at its root, so the README and package.json are the only statements of terms you can point at.

The last push to the default branch was on 2026-05-29. The repository is not archived, but there have been no releases retrieved, and the dependency set is pinned to Electron ^28, Vite ^5.4.21, Chart.js ^4.4.1 and xlsx ^0.18.5. Those carets mean an npm install today resolves newer minor versions than the author last ran, which is the usual source of surprise in an Electron project: a major Electron bump changes the runtime, and the Vite renderer build in the start script has to keep working with it.

Upgrade cost, then, is mostly dependency drift rather than feature work. The scripts for that are already present: npm run typecheck runs tsc --noEmit against the TypeScript configuration, npm test runs node --test, and npm run audit:ci runs npm audit --omit=dev --audit-level=high. Those three are the cheapest way to find out whether a fresh clone still behaves.

The Pre-Commit Scan for Bill Files

One part of the repository is aimed at contributors rather than users, and it is worth knowing about if you fork it. Because bill exports carry names, phone numbers and transaction identifiers, the project ships two defences. The .gitignore ignores *.xlsx, *.xls and *.csv at the root and in subdirectories, with sample/ as the only exception, and also ignores data/, userData/ and exported reports. The second is scripts/precommit-secret-scan.sh, a hook that blocks staged bill files outside sample/ and content matching WeChat bill headers, phone numbers or ID numbers.

The README offers two ways to enable it, either by symlinking it into .git/hooks/pre-commit or by pointing core.hooksPath at scripts/githooks after copying the script there. It also documents an escape hatch: SKIP_BILL_SCAN=1 git commit ... bypasses the scan, with a warning to use it carefully. The honest caveat is that a hook is only active on machines where someone enabled it; a fresh clone has no protection until you run one of those two commands.

Editorial conclusion

Adopt it if you already have a WeChat Pay Excel export from the 用于个人对账 option and you want charts and an Excel summary without sending financial data anywhere. Do not adopt it if your bill arrived as a stamped PDF, or if you need to merge several export periods in one pass, because the README states each run handles one file. Before trusting it, clone the repository, run npm install and npm start, and open sample/demo-bill.xlsx to confirm the parser handles your column layout and that the first rows of your own file are skipped correctly.

Frequently asked questions

Official sources

1. Issues
2. README
3. run-liyi/wechatpay on GitHub