从 Squarespace 迁移到 SWA + Astro 的规划与实践

📢 本文同步发布於公众号：Power Platform · 最佳实践
🔗 原文链接：https://johnliu.net/blog/planning-and-migrating-from-squarespace-to-swa-and-astro/

---

从 Squarespace 迁移到 SWA + Astro 的规划与实践

当我们把 johnliu.net 从 Squarespace 迁移出来时，目标并不是做一个更炫酷的网站。目标很简单：更简单的所有权、更低的成本，以及一套我们能在未来几年持续维护的方案。

让这件事成功的原因很简单：用 agent 完成繁重的工作，然后在继续下一步之前逐一审查每个环节。

Astro + Azure Static Web Apps 恰好符合这个需求：内容优先的页面、最少的客户端 JavaScript、简单的 GitHub 部署，以及静态托管。

如果完全靠人工完成这种规模的迁移，考虑到重定向、脚本编写、QA 和返工，通常需要 3-6 周的工作量。借助 agent 辅助脚本编写和人工审查关卡，我们在 1 天加 2 个晚上就完成了——同时还在做着全职工作。

像这样的传统重建通常风险高、成本大、周期长。仅成本一项就常常让项目早早夭折。Agent 改变了这一点：更少的手动劳作、更快的迭代循环，从数周缩短到数天。

从清单盘点开始

我们从完整的 Squarespace 导出开始。唯一的导出格式是 WordPress XML。

基于这个文件，一个 agent 生成了解析器，将每篇文章提取为带有 frontmatter 的 Markdown。一次运行就产出了 625 个可迁移的文件。

然后我们验证了四件事：

迁移本质上是一个披着 UI 外衣的链接保留问题。如果 URL 失效，内容实际上就等于丢失了。

Agent 把这变成了快速循环：导出、对比、映射、验证、重复。

保留旧路径

第一个硬任务是重定向。

从搜索、书签和旧链接过来的用户不应该感受到平台的变化。所以我们为旧的 Squarespace 路径和旧的分类/标签页面构建了明确的规则。

原则：每一条旧路径要么被精确保留，要么被显式重定向。

分层迁移内容

内容迁移分层进行效果最好：

这让我们得到了一个干净的 Astro content collection，而不是一堆一次性的页面。

这正是 agent 最能发挥价值的地方：大规模转换、规范化和检查。

Agent 构建的迁移工具

最大的速度提升来自 agent 生成的一次性支持脚本：

这些粘合性工作通常是迁移卡壳的地方。有了 agent，我们能够快速生成、运行、验证和优化。

迁移中最大的风险是看不见的回归：深层链接断裂、分析数据不连续，以及定时发布内容的行为与预期偏离。每一个一次性脚本都必须搭配验证检查，而不能盲目信任。

让文章发布变得简单

未来的发布也需要保持简单：

不需要特殊的编辑器，不需要脆弱的发布工作流。

把评论当作独立决策

评论是一个独立的决策。我们选择了 Giscus，因为它把讨论保留在 GitHub Discussions 中，避免了后端/审核基础设施。

权衡：评论者需要一个 GitHub 账号。对于这个受众来说，这是可以接受的。

迁移方式：脚本提取和映射，能干净映射的直接导入，其余的保留归档路径。

让上线保持平淡无奇

有了静态技术栈，上线可以保持平静：

没有数据库迁移，没有应用服务器切换，没有午夜惊魂。

这不是一次快速的……