迁移 Docusaurus 到 Astro Starlight

为什么从 Docusaurus 迁移到 Astro Starlight

Docusaurus 在 React 文档生态中表现出色。团队可以快速搭建具有版本管理、搜索和 MDX 支持的文档网站。但它会向每个访问者传输完整的 React 运行时，这个重量在每次 Lighthouse 审计中都会显现。

Astro Starlight 专为文档而构建。它默认渲染静态 HTML，除非你明确选择加入，否则零 JavaScript，并开箱即用提供内置搜索、侧边栏导航和国际化支持。你的 MDX 文件可以直接转移。Astro 团队始终保持迁移路径文档齐全。

如果你的 Docusaurus 网站在移动设备上感觉缓慢，如果随着文档增长构建时间不断增加，或者你厌倦了在本应是静态内容上对抗 React 水合问题——Starlight 解决了所有这些问题。

Docusaurus 大规模运行的真实问题

客户端 JavaScript 开销

Docusaurus 向浏览器传输 React。每次页面加载都包含 React 运行时、React DOM 和客户端路由层。对于 99% 的页面都是静态文本和代码块的文档网站，这是死重。移动设备 Lighthouse 分数通常在 45-65 之间。

构建性能降级

当你的文档集合增长到数百页以上时，Docusaurus 的构建速度会明显放慢。Webpack 捆绑使其更糟。拥有 500+ 文档页面的团队报告构建时间超过 5 分钟，这会破坏 CI/CD 反馈循环。

插件生态系统锁定

Docusaurus 插件与其内部架构紧密耦合。需要自定义 remark 插件？它们工作正常，但配置层增加了复杂性。想要交换搜索提供者？你在 Docusaurus 的预设系统中工作，这限制了可能性。

侧边栏配置刚性

Docusaurus 侧边栏配置使用特定的 JSON/JS 模式，包含 category、items 和 type 字段。它可以工作，但对于具有深层嵌套的大型文档树，配置变得不易管理。重新排序部分需要编辑配置文件，而不仅仅是移动文件。

React 组件依赖项

Docusaurus 中的自定义组件是在客户端水合的 React 组件。如果你构建了交互式示例、选项卡式内容或自定义警告，它们都会承担 React 水合成本——即使交互性很小。

Astro Starlight 提供什么

默认零 JS

Starlight 生成纯静态 HTML 和 CSS。除非你明确添加交互式岛屿，否则没有框架运行时传输到浏览器。文档页面在 3G 连接上以不到 200ms 的速度加载。Lighthouse 分数始终达到 95-100。

MDX 兼容性

Starlight 默认包含 Astro 的 MDX 集成。你现有的 .mdx 文件立即工作。前置元数据字段映射清晰—— title、description、sidebar_label 都有 Starlight 等价物。Remark 和 rehype 插件不需要更改即可转移。

内置 Pagefind 搜索

Starlight 附带 Pagefind，一个在构建时索引你的 HTML 并完全在浏览器中运行的静态搜索引擎。没有外部服务、没有 API 密钥、没有 Algolia 爬取延迟。搜索离线工作，并将大约 10KB 添加到你的捆绑中。对于特别需要 Algolia 的团队，有一个官方 Starlight DocSearch 插件。

基于文件的侧边栏生成

Starlight 可以从你的文件结构自动生成侧边栏。将 MDX 文件放在文件夹中，它显示在侧边栏中。你仍然可以使用显式配置进行覆盖，但默认行为消除了大多数侧边栏配置维护。

具有类型安全的内容集合

Starlight 使用 Astro 的内容集合，在构建时根据 Zod 模式验证你的前置元数据。前置元数据字段中的拼写错误会在部署前被捕获，而不是被用户发现。

我们的迁移流程

第 1 阶段：审计和规划

我们从盘点你的 Docusaurus 网站开始——页面数量、自定义组件、插件用途、侧边栏结构、版本管理设置和任何自定义主题。我们将每个 Docusaurus 功能映射到其 Starlight 等价物，并标记需要自定义解决方案的差距。

第 2 阶段：Starlight 搭建

我们使用 yarn create astro --template starlight 启动一个新的 Starlight 项目，并将其配置为与你现有网站的结构相匹配。我们设置内容集合、配置 astro.config.mjs，并建立与当前 URL 结构镜像的文件夹层次结构。

第 3 阶段：内容迁移

MDX 文件的转移需要最少更改。我们处理：

• 前置元数据重新映射：Docusaurus 特定字段如 sidebar_position、sidebar_label 和 slug 转换为 Starlight 的前置元数据模式
• 导入语句更新：组件导入从 Docusaurus 路径更改为 Astro 组件路径
• 警告语法：Docusaurus 使用 :::note 语法；Starlight 使用 <Aside> 组件或其自己的警告语法
• 选项卡组件：来自 Docusaurus 的 <Tabs> 和 <TabItem> 被 Starlight 的内置选项卡组件替换

第 4 阶段：侧边栏配置重新映射

Docusaurus 侧边栏配置使用 category/items 模式被转换为 Starlight 侧边栏配置格式。在可能的情况下，我们切换到由文件结构驱动的自动生成侧边栏，将配置维护减少到零。

// Docusaurus sidebars.js
module.exports = {
  docs: [
    { type: 'category', label: 'Getting Started', items: ['intro', 'installation'] },
  ],
};

// Starlight astro.config.mjs
starlight({
  sidebar: [
    { label: 'Getting Started', autogenerate: { directory: 'getting-started' } },
  ],
})

第 5 阶段：插件和集成映射

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

• @docusaurus/plugin-google-gtag → Astro 的 @astrojs/partytown 与内联 gtag
• @docusaurus/plugin-sitemap → @astrojs/sitemap
• Algolia DocSearch → Pagefind（内置）或 starlight-docsearch 插件
• @docusaurus/plugin-client-redirects → Astro 配置中的重定向或 astro-redirect
• 自定义 remark/rehype 插件 → 直接转移，相同插件生态系统

第 6 阶段：搜索迁移

如果你使用 Algolia DocSearch，我们默认迁移到 Pagefind。Pagefind 在构建时索引，不需要外部服务，并提供带有模糊匹配的即时搜索。如果你的团队特别需要 Algolia——用于分析或 AI 提供的答案——我们改为配置官方 starlight-algolia 插件。

第 7 阶段：QA 和启动

我们对旧网站和新网站进行完整爬取比较，验证每个 URL 解析，测试搜索功能，验证移动设备渲染，并确认 Lighthouse 分数达到我们的目标。

SEO 保护策略

文档网站积累了显著的搜索权限。我们保护每一点：

• URL 对等：我们完全匹配你现有的 URL 结构。如果 Docusaurus 提供 /docs/getting-started，Starlight 提供相同路径
• 301 重定向：对于必须更改的任何 URL，我们在 Vercel 或 Cloudflare 上配置服务器级重定向
• 规范标签：每个页面都获得适当的规范 URL
• 网站地图生成：@astrojs/sitemap 生成提交到 Search Console 的更新网站地图
• 元数据保护：标题标签、元描述和 Open Graph 标签从现有前置元数据转移
• 结构化数据：我们在适用处添加特定于文档的 JSON-LD

时间表和定价

大多数 Docusaurus 到 Starlight 迁移在 1-3 周内完成，具体取决于网站复杂性：

• 小型网站（少于 50 页、最少自定义组件）：1 周，起价 $3,000
• 中型网站（50-200 页、自定义组件、版本管理）：2 周，起价 $6,000
• 大型网站（200+ 页、重度自定义、多个区域设置）：3+ 周，起价 $10,000

每个项目始于免费迁移审计，我们评估你的特定 Docusaurus 设置并提供准确的范围和时间表。