Featured image of post PubArticle2MD 项目复盘：从“能跑”到“可交付”
Tech 项目复盘 Electron 工程实践

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

一次真实的工具落地过程：需求、踩坑、修复、封装与发布

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

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

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

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

1. 项目目标

初始目标有 4 个：

  1. 参考 wechat2pdf 思路，实现公众号文章转 Markdown/PDF。
  2. 支持本地运行，尽量不把内容上传到第三方。
  3. 提供 PWA 入口，发布到 GitHub Pages。
  4. 争取提供普通用户可直接运行的 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 发布状态。工作流存在，但站点链路没有完整激活。

处理方式

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

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

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

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

后续做了收敛：

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

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

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

现象

桌面版运行后：

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

根因

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

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

修复动作

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

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

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

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

这里主要处理两件事：

  1. 后端代码进包。
  2. Playwright Chromium 随包。

对应改动

  1. package.json 的 build.files 增加 server/**/*。
  2. 新增脚本 scripts/ensure-playwright-browsers.js：
    • 打包前检查 .local-browsers
    • 缺失时自动安装 Chromium
  3. extraResources 加入浏览器目录。
  4. 启动时设置 PLAYWRIGHT_BROWSERS_PATH=resources/playwright-browsers。
  5. 排除 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。

随后发布链路跑通：

  1. 本地构建 EXE
  2. 创建 GitHub Release
  3. 上传发布资产

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

8. 当前状态

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

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

9. 使用方法

9.1 在线版（无需安装）

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

步骤：

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

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

9.2 桌面 EXE（推荐）

  1. 打开 Release： https://github.com/yourpapayouknow/PubArticle2MD/releases/tag/v1.0.2
  2. 下载并运行 EXE。
  3. 确认运行模式显示为“本地 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. 这次复盘的核心结论

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

判断标准很直接：

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

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

comments powered by Disqus
© 2017 - 2026 iwmei