Article Migration

把旧平台文章和图片迁移到本站

这个流程适合从微博长文、公众号、Notion、语雀、旧博客或网页访谈中迁移内容。目标是让正文变成 Jekyll Markdown，让阅读用图片进入 Pages，让原始图片留在本地归档。

迁移脚本tools/migrate-article-images.mjs
站点图片assets/img/posts/<slug>/
原图归档archive/raw-images/<slug>/
文章草稿_posts/YYYY-MM-DD-slug.md

流程总览

1 准备旧文

从旧平台保存 HTML，或把网页正文复制成一个本地 `.html` / `.md` 文件。

2 运行脚本

脚本读取正文，提取图片，生成 Jekyll front matter 和 Markdown 草稿。

3 整理图片

原图进入本地归档，站点展示图进入 `assets/img/posts`，正文图片路径自动替换。

4 预览发布

本地构建确认排版、链接、图片体积和移动端阅读，再推送到 GitHub Pages。

目录长什么样

输入 migration/inbox/article.html

旧平台复制出来的 HTML 或 Markdown。

→
脚本处理 npm run migrate:article

提取正文、下载图片、替换路径。

→
输出 _posts/

文章、站点图片和本地原图归档。

第一步：保存旧平台正文

优先保存 HTML

HTML 通常能保留图片顺序、链接、加粗、标题层级和图注。只复制纯文本会丢掉图片位置，后面要花更多时间补。

推荐放置位置

把待迁移文件放到 `migration/inbox/`。这个目录只是本地工作区，不需要发布到 Pages。

```text migration/ inbox/ old-article.html ```

第二步：运行迁移命令

最常用的命令如下。`slug` 会成为图片目录名，也会进入文章文件名，建议使用英文、数字和短横线。

```powershell npm run migrate:article -- --input migration\inbox\old-article.html --title "文章标题" --date 2026-07-16 --slug article-slug --source-title "原平台" --source-url "https://example.com/article" ```

如果只是想先看会输出什么，不写入文件，可以加 `--dry-run`。

```powershell npm run migrate:article -- --input migration\inbox\old-article.html --title "文章标题" --slug article-slug --dry-run ```

第三步：检查输出结果

生成的文章

文章会写入 `_posts`，顶部自动带有标题、日期、分类、来源和迁移信息。

_posts/
  2026-07-16-article-slug.md

图片输出

展示图会进入 Pages，原图留在本地归档。`archive/` 已经被 `_config.yml` 排除，不会发布。

assets/img/posts/article-slug/
  01-abcd1234.webp
  02-efgh5678.webp

archive/raw-images/article-slug/
  01-abcd1234.jpg
  02-efgh5678.png
  migration-report.json

第四步：启用图片压缩

脚本本身不强制依赖图片库。没有压缩库时，它会先复制图片，保证迁移不中断。想自动生成 WebP 展示图，可以安装 `sharp`。

```powershell npm install --no-save sharp ```

安装后再次运行迁移命令，展示图会按默认宽度和质量压缩。

```powershell npm run migrate:article -- --input migration\inbox\old-article.html --title "文章标题" --slug article-slug --max-width 1600 --quality 78 ```

推荐图片规格

图片类型 建议宽度 处理建议
普通配图 1200-1600px 压成 WebP，单张尽量控制在 200KB-800KB。
手机截图 900-1200px 保留清晰文字，避免过度压缩。
扫描图局部 1600-2200px 正文只放阅读用图，完整原图包放本地归档或外部链接。
GIF 按原文件 脚本会保留 GIF，不转 WebP，避免动图失效。

常见问题

情况 处理方式
图片下载失败 查看 `migration-report.json` 的 `failures`。旧平台可能防盗链，可以先手动下载图片，再把 Markdown 里的图片路径指向本地文件。
正文格式很乱 优先找平台的 HTML 导出。没有导出时，复制网页正文到本地 HTML，再运行脚本，最后人工校对标题层级和列表。
图片太多 先迁移全部图片，再筛掉正文不需要的图片。保留原图归档，Pages 只放阅读需要的展示图。
想先生成草稿 加 `--draft`，输出到 `_drafts/slug.md`，确认无误后再改成 `_posts/YYYY-MM-DD-slug.md`。

发布前检查

  • 文章标题、日期、分类和来源链接已经确认。
  • 正文图片都指向 `/assets/img/posts/article-slug/`。
  • `archive/raw-images/` 只保留在本地，不进入 GitHub Pages。
  • 运行 `bundle exec ruby -S jekyll build` 后没有新增错误。
  • 打开本地预览检查手机端、暗色主题、长图和图注。