将 Gatsby 迁移到 Astro | Social Animal

开发者为什么离开 Gatsby 转向 Astro

Gatsby 曾经很不错。它开创了基于 React 的静态站点生成器类别，并向数千名开发者介绍了 JAMstack。但它已经停滞不前。Netlify 在 2023 年初收购了 Gatsby，开发速度已降至冰点，插件生态系统正在恶化，大型内容站点的构建时间仍然慢得令人难以接受。

Astro 的构建初衷就是解决 Gatsby 造成的问题。默认零 JavaScript，使用内容集合替代 GraphQL 复杂性，构建速度让 Gatsby 相形见绌。如果你正在维护一个 Gatsby 内容站点，迁移到 Astro 不仅仅是升级——而是早就该做的事。

驱动迁移的 Gatsby 痛点

简单数据的 GraphQL 复杂性

Gatsby 的 GraphQL 数据层在发布时是创新的。对大多数内容站点来说也过度设计了。想列出你的博客文章？写 GraphQL 查询。想从 markdown 文件中提取 frontmatter？GraphQL 查询。想显示图片？用特殊组件包装的 GraphQL 查询。

对于有 50 个页面的营销站点，你需要维护数十个 GraphQL 查询，只是为了呈现位于你自己文件系统中的内容。这种抽象增加了认知开销，却没有相应的好处。

扩展性差的构建时间

Gatsby 的构建流程通过其 GraphQL 层处理每个页面，运行图像转换，并为每条路由生成完整的 React 包。一个 500 页的内容站点可能需要 10-15 分钟来构建。一个 2,000 页的站点？即使启用了增量构建，你也在看 30+ 分钟。

每次内容更新都意味着等待。每次修复错字都意味着等待。你的内容团队开始对这个工具感到厌倦。

插件生态系统正在衰退

Gatsby 的优势是其插件生态系统——gatsby-plugin-image、gatsby-plugin-sharp、gatsby-source-filesystem、gatsby-transformer-remark。这些插件中的许多已有超过一年没有进行任何有意义的更新。依赖冲突增加。安全建议堆积。你运行 npm audit，看到 47 个漏洞，其中大多数深埋在 Gatsby 依赖树中。

重型 JavaScript 包

Gatsby 为每个访客发送整个 React 运行时，即使是完全不需要交互的页面。静态的「关于我们」页面仍然会下载 React、ReactDOM 和 Gatsby 的运行时。你的 Lighthouse 分数会下降，Core Web Vitals 会崩溃，连接速度较慢的用户会付出代价。

Astro 提供的功能

内容集合替代 GraphQL

Astro 的内容集合是为内容站点专门设计的。在 TypeScript 中定义模式，将你的 markdown 文件放在一个文件夹中，用 getCollection('blog') 查询它们。无 GraphQL。无特殊插件。开箱即用的类型安全 frontmatter 验证。

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    date: z.date(),
    tags: z.array(z.string()),
    image: z.string().optional(),
  }),
});

就这样。无 gatsby-node.js，无 createPages API，无 GraphQL fragments。你的数据获取是需要它的组件中的单个函数调用。

默认零 JavaScript

Astro 默认不发送任何客户端 JavaScript，除非你明确选择加入。一个 50 页的营销站点向浏览器发送纯 HTML 和 CSS。当你需要交互性——联系表单、图像轮播、搜索小部件——你可以使用 Astro 的 Islands 架构来只水合那个组件。

结果是：Lighthouse 在移动设备上的评分为 95-100，无需任何优化技巧。

亚秒级构建

Astro 运行在 Vite 上。一个 500 页的内容站点在 30 秒内构建完成。一个 2,000 页的站点在 2 分钟内构建。开发中的热模块替换是即时的。你的内容团队可以在毫秒内预览更改，而不是等待 Gatsby 的开发服务器重新编译其 GraphQL 模式。

框架无关的组件

已经从 Gatsby 站点有 React 组件？Astro 在构建时或客户端渲染它们——由你选择。想逐渐迁移到 Astro 组件，或为特定功能尝试 Vue 或 Svelte？Astro 在同一项目中支持所有这些。

我们的 Gatsby 到 Astro 迁移流程

第 1 阶段：审计和架构（第 1 周）

我们首先通过映射你现有的 Gatsby 站点——每个页面模板、每个 GraphQL 查询、每个插件依赖、每个动态路由来启动。我们记录你的 gatsby-node.js 配置，识别自定义源插件，并编目所有第三方集成。

从那里，我们设计 Astro 架构：内容集合模式、布局层次结构、集成选择和部署目标。

第 2 阶段：内容迁移（第 2 周）

我们构建自动化迁移脚本，将你的内容从 Gatsby 的结构转换为 Astro 内容集合。Frontmatter 模式得到验证和规范化。MDX 组件被映射到其 Astro 等价物或包装为框架 islands。

Gatsby 的 gatsby-image 用法被转换为 Astro 的内置 <Image /> 组件，它原生处理响应式图像、格式转换和延迟加载——无需插件链。

第 3 阶段：模板和组件转换（第 2-3 周）

Gatsby 页面模板变成 Astro 布局和页面。不需要客户端交互的 React 组件变成 Astro 组件——更简洁、更快、零 JS。交互式组件保留为 React（或重写）并使用 client: 指令进行部分水合。

我们用 Astro 集成替换 Gatsby 插件：

• gatsby-plugin-sitemap → @astrojs/sitemap
• gatsby-plugin-feed → 使用 @astrojs/rss 的自定义 RSS
• gatsby-plugin-mdx → 通过 @astrojs/mdx 的内置 MDX 支持
• gatsby-plugin-sharp → 内置的 astro:assets 图像优化

第 4 阶段：SEO 保护（第 3 周）

这是迁移成败的地方。我们实施全面的 URL 保护策略：

• 301 重定向用于任何 URL 结构更改，在托管级别配置以实现零延迟重定向
• 规范标签在每个页面上匹配你现有的 URL 结构
• 结构化数据（JSON-LD）迁移和验证，通过 Google 的富结果测试
• 元标签精确保留——标题标签、描述、Open Graph、Twitter Cards
• XML 网站地图重新生成并提交给 Google Search Console
• 内部链接审计以捕获迁移后的任何损坏的引用

我们在启动后 30 天内监控 Google Search Console，以立即捕获索引问题。

第 5 阶段：测试和启动（第 4 周）

针对你现有 Gatsby 站点的完整视觉回归测试。性能基准并排比较。无障碍审计。跨浏览器测试。我们部署到暂存 URL 供你的团队审查，然后无停机时间切换。

如果你的 Gatsby 站点使用了 service worker（gatsby-plugin-offline 常见），我们部署一个替换 service worker，强制现有访客浏览器上的缓存失效——这是大多数迁移指南完全跳过的步骤。

时间表和价格

一个典型的、有 50-200 页的内容站点的 Gatsby 到 Astro 迁移运行 3-4 周，起价为 $8,000。有自定义源插件、复杂动态路由或繁重 CMS 集成的较大站点可能需要 5-6 周。

范围因素包括：唯一页面模板的数量、自定义 Gatsby 插件、第三方 API 集成，以及你是否想保留 React 组件或将所有内容转换为原生 Astro。

底线

Gatsby 并未消亡，但它没有变得更好。Astro 正在积极开发，拥有蓬勃发展的社区，并且从一开始就是为内容丰富的网站设计的。迁移路径文档齐全，性能收益是即时的，你的开发团队会感谢你消除了 GraphQL 样板代码。

停止维护一个停滞不前的框架。迁移到快速发展的框架。