WeChat Article to PDF
Convert WeChat public account articles to high-fidelity PDF files, preserving original content, formatting, layout, and images.
Quick Start
To convert a WeChat article, run the bundled script:
python D:\wechat-to-pdf\scripts\wechat_to_pdf.py <URL> [-o OUTPUT] [-f FORMAT] [-t TIMEOUT]
Workflow
When a user provides a WeChat article URL for PDF conversion, follow these steps:
Step 1: Validate Input
Verify the URL belongs to mp.weixin.qq.com. Reject non-WeChat URLs with a clear explanation. Accepted URL patterns:
- https://mp.weixin.qq.com/s/...
- https://mp.weixin.qq.com/s?__biz=...
Step 2: Check Dependencies
Before executing, confirm playwright is installed. If missing, run:
pip install playwright
python -m playwright install chromium
Step 3: Determine Output Path
- If the user specifies a file path or directory, pass it via the
-oargument - If not specified, the script auto-names the PDF using the article title and saves to the current working directory
Step 4: Execute Conversion
Run the conversion script with appropriate arguments:
python D:\wechat-to-pdf\scripts\wechat_to_pdf.py "<URL>" -o "<output_path>" -f <format>
The script handles all conversion steps internally:
1. Opens the article in headless Chromium
2. Waits for content to load
3. Scrolls the page to trigger lazy-loaded images
4. Fixes WeChat's data-src lazy-loading mechanism
5. Injects CSS to hide non-article elements (comments, toolbars, QR codes)
6. Generates PDF with proper margins and background colors
Verification wall auto-fallback: If WeChat shows the "环境异常 / 完成验证后即可继续访问" captcha wall (common for poc_token links or rapid repeated access), the headless attempt is detected and the script automatically retries in headed mode with a persistent profile (~/.wechat-to-pdf-profile). A real browser window pops up; the user completes the slider verification once, after which the script resumes automatically and the verification cookie is reused on later runs. Use --headed to skip the headless attempt when the wall is expected.
Step 5: Verify Output
After execution, confirm:
- The script exited with code 0
- Report the output file path and size to the user
Command Reference
| Argument | Short | Required | Default | Description |
|---|---|---|---|---|
url |
- | Yes | - | WeChat article URL |
--output |
-o |
No | {cwd}/{title}.pdf |
Output file path or directory |
--format |
-f |
No | A4 |
Paper format: A4, A3, Letter, Legal, Tabloid |
--timeout |
-t |
No | 60 |
Page load timeout in seconds |
--headed |
- | No | off | Force headed browser with persistent profile (manual slider supported) |
--profile |
- | No | ~/.wechat-to-pdf-profile |
Persistent profile dir for headed mode; keeps the verification cookie |
--verify-timeout |
- | No | 180 |
Max seconds to wait for manual slider verification in headed mode |
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Argument error |
| 2 | Invalid URL (not a WeChat article) |
| 3 | Missing dependency (playwright not installed) |
| 4 | Page load failure (timeout, network error) |
| 5 | PDF generation failure |
Error Handling
| Scenario | Action |
|---|---|
| Non-WeChat URL | Inform user that only mp.weixin.qq.com URLs are supported |
| Network timeout | Suggest checking network connection or increasing timeout with -t |
| Playwright not installed | Provide installation commands |
| Verification wall (环境异常) | Script auto-retries in headed mode; ask user to complete the slider in the browser window. Re-run with --headed --verify-timeout 300 if more time is needed. The cookie persists in ~/.wechat-to-pdf-profile |
| Images missing in PDF | The script already handles lazy-loading; if issues persist, refer to references/wechat-css-selectors.md for DOM structure updates |
Bundled Resources
scripts/wechat_to_pdf.py- Core conversion script. Accepts CLI arguments, validates URLs, handles lazy-loaded images, and generates PDF via Playwright Chromium. Runs headless by default and automatically falls back to headed mode with a persistent profile when WeChat's verification wall is detected.references/wechat-css-selectors.md- Documents WeChat article page DOM structure, CSS selectors for hidden elements, and the image lazy-loading mechanism. Consult this file when WeChat page structure changes break the conversion.
