PubArticle2MD 项目复盘：从“能跑”到“可交付”

Mon, 04 May 2026 00:00:00 +0000

这篇文章记录 PubArticle2MD 的完整落地过程。

项目目标不复杂：把公众号文章转成 Markdown 或 PDF，并且给出三种可用形态：

在线可用（GitHub Pages）
本地源码可跑
桌面 EXE 可直接用

真正的难点不在“功能写出来”，而在“交付后别人也能稳定用”。下面按时间顺序展开。

1. 项目目标

初始目标有 4 个：

参考 wechat2pdf 思路，实现公众号文章转 Markdown/PDF。
支持本地运行，尽量不把内容上传到第三方。
提供 PWA 入口，发布到 GitHub Pages。
争取提供普通用户可直接运行的 EXE。

测试文章： https://mp.weixin.qq.com/s/5BOAnJ5H4seYxSbXWi5Ibg

2. 第一版实现：先把主链路跑通

项目先拆成两层：

前端（PWA）：输入链接、选择抓取模式、预览内容、下载文件。
后端（Node API）：/api/health、/api/parse、/api/export/markdown、/api/export/pdf。

PDF 由 Playwright 在后端渲染，优先保证稳定性。

核心代码位置：

public/app.js
server/index.js
desktop/main.js

第一版发布后，基本功能可用，但工程问题开始集中出现。

3. 问题一：GitHub Pages 404

现象

Pages 地址访问 404，页面提示： There isn't a GitHub Pages site here.

排查结果

部署日志显示，问题不在前端资源，而在 Pages 发布状态。工作流存在，但站点链路没有完整激活。

处理方式

检查仓库 Pages 配置。
重新触发部署。
部署后回测 URL。

恢复后的在线入口： https://yourpapayouknow.github.io/PubArticle2MD/

4. 问题二：有 Actions 不代表“可直接使用”

当时发现一个常见误区：流水线很多，但用户路径不清晰。

后续做了收敛：

CI 负责基本检查。
Deploy GitHub Pages 只负责发布 public/。
README 只讲用户需要的路径，删掉不必要的流程噪音。

目标从“流程完整”改为“用户可用”。这一步很关键。

5. 问题三（核心问题）：EXE 是前端壳，不是完整应用

现象

桌面版运行后：

选择本地 API 会报“当前环境没有本地 API 服务”。
运行模式一直显示“纯前端模式（GitHub Pages）”。

根因

桌面进程只做了 loadFile(index.html)，没有启动本地服务。

前端会请求 ./api/health 判断本地 API 是否存在。服务没启动，检测自然失败，所以始终落在纯前端模式。

修复动作

Electron 主进程直接启动本地 API。
- host=127.0.0.1
- port=0（自动分配端口，避免冲突）
窗口优先加载本地 API URL；失败再降级到本地 HTML。
在 before-quit 里关闭 server，避免残留进程。
/api/health 增加 runtime 字段，前端按运行态显示文案：
- 本地 API 模式（桌面 EXE 内置后端）
- 本地 API 模式（Node 服务）
- 纯前端模式（GitHub Pages）

修复后，EXE 从“页面容器”变成了“前后端一体应用”。

6. 问题四：桌面版要稳定，运行环境必须随包

桌面版即使能启动，如果依赖没打进包，用户机器仍会失败。

这里主要处理两件事：

后端代码进包。
Playwright Chromium 随包。

对应改动

package.json 的 build.files 增加 server/**/*。
新增脚本 scripts/ensure-playwright-browsers.js：
- 打包前检查 .local-browsers
- 缺失时自动安装 Chromium
extraResources 加入浏览器目录。
启动时设置 PLAYWRIGHT_BROWSERS_PATH=resources/playwright-browsers。
排除 asar 内重复浏览器资源，避免包体翻倍。

这一步解决了“本机可用、别人不可用”的典型问题。

7. 问题五：Windows 本地发布脚本首次失败

现象

执行以下命令首次失败：

1

npm run release:local -- --tag v1.0.2

报错停在：npm.cmd run desktop:dist。

根因

Windows 下子进程执行 .cmd 时，spawnSync 的默认参数不稳定。

修复

在 scripts/release-local.js 中对 Windows 开启 shell: true。

随后发布链路跑通：

本地构建 EXE
创建 GitHub Release
上传发布资产

版本地址： https://github.com/yourpapayouknow/PubArticle2MD/releases/tag/v1.0.2

8. 当前状态

项目目前可以对外稳定使用：

Pages 在线版可用。
EXE 内置本地 API，不再是前端壳。
PDF 依赖环境已随包。
本地打包和发布流程可复现。
文档已按用户路径重写。

9. 使用方法

9.1 在线版（无需安装）

地址： https://yourpapayouknow.github.io/PubArticle2MD/

步骤：

输入公众号链接。
直连失败时切换“代理 URL”或“粘贴 HTML”。
点击解析。
下载 Markdown ZIP 或 PDF。

示例链接： https://mp.weixin.qq.com/s/5BOAnJ5H4seYxSbXWi5Ibg

9.2 桌面 EXE（推荐）

打开 Release： https://github.com/yourpapayouknow/PubArticle2MD/releases/tag/v1.0.2
下载并运行 EXE。
确认运行模式显示为“本地 API 模式（桌面 EXE 内置后端）”。

9.3 本地源码运行

1
2
3


npm install
npm run install:chromium
npm start

访问：http://127.0.0.1:8787

9.4 命令行批量转换

1

npm run convert -- --url "https://mp.weixin.qq.com/s/5BOAnJ5H4seYxSbXWi5Ibg" --outdir outputs

9.5 本机打包并发布

1
2


gh auth login
npm run release:local -- --tag v1.0.2

10. 这次复盘的核心结论

这个项目最大的收获，不是“做完了一个工具”，而是把工具做成了可交付物。

判断标准很直接：

用户能在线用。
用户能安装用。
开发者能本地复现。
版本能持续发布。

从结果看，真正推动项目跨过这道线的，往往不是新功能，而是对“不可用细节”的持续修复。

Github-Pages on iwmei的博客