migrate

迁移到 Astro

在将项目从其他框架迁移到 Astro、将静态网站转换为 Astro，或升级现有 Astro 代码库时使用此技能。

如果有 astro-best-practices，请与此技能一起应用，确保迁移结果遵循良好的 Astro 默认实践，而不只是机械地复现旧系统。

工作流

1. 梳理当前系统

更改代码之前，先确定：

• 路由结构
• 布局／共享外壳模式
• 数据源
• 样式策略
• 交互式组件
• 图像处理方式
• 部署／运行时要求

这些信息决定目标应采用静态、混合还是服务器渲染模式。

2. 选择迁移方案

常见模式：

• 将静态 HTML 转换为 Astro 页面和布局
• 将 Next.js 或 Nuxt 转换为 Astro 页面及框架岛屿
• 将 Gatsby 内容／数据流转换为内容集合
• 使用官方升级指南升级 Astro 主版本

如果现有应用有显著的运行时行为或大量交互内容，优先采用渐进式迁移计划。

3. 映射概念，而不是盲目复制文件

常见映射：

来源	Astro 目标
共享应用外壳	布局
路由组件	页面或动态路由
Markdown／内容处理流程	内容集合
仅适用于框架的组件	带客户端指令的岛屿
图像辅助工具	astro:assets 或项目当前的图像策略

仅在框架组件仍能发挥作用时保留它们。静态内容通常应转换为 .astro。

4. 重建路由和数据流

对于每个迁移部分：

• 在 src/pages/ 中重建路由
• 将共享包装器移至 src/layouts/
• 将结构化内容迁移至 src/content/
• 用 Astro frontmatter 或内容 API 替换特定于框架的数据获取模式

如果某个页面之前使用 getStaticPaths 样式的路由生成方式，请在 Astro 中明确重建，而不是模拟旧框架的生命周期。

5. 将交互性作为岛屿处理

除非是有意采用兼容性桥接方案，否则不要将整个框架应用原样移植到 Astro 中。

而应：

• 将静态外壳保留在 .astro 中
• 为交互式岛屿保留框架组件
• 有意选择客户端指令
• 尽量缩小水合范围

6. 验证行为并检查回归问题

至少检查：

• 路由一致性
• 元数据和 head 输出
• 图像渲染
• 表单行为
• 键盘导航
• 构建和预览行为
• 部署假设

Astro 升级指南

对于 Astro 到 Astro 的升级：

• 从官方升级指南开始，并在适用于当前代码库时使用 npx @astrojs/upgrade
• 与 Astro 一起更新官方集成和适配器，不要将其当作后续单独处理的事项
• 在排查代码问题之前，先确认本地和部署运行时满足当前 Node 要求
• 升级后重新运行内容、路由和构建检查

对于 Astro 6，请特别检查以下变更点：

• Node 运行时：Astro 6 要求 Node 22.12.0 或更高版本
• 内容集合：使用 src/content.config.*，为每个集合定义 loader，移除 type，从 astro/zod 导入 z，使用 entry.id 替代 slug，并将 entry.render() 替换为 render(entry)
• 旧版集合标记：移除任何 legacy.collections 配置
• 文件查询：将 Astro.glob() 替换为 import.meta.glob()；对于内容集合，则使用 getCollection()
• 视图过渡：如果项目中仍存在 <ViewTransitions />，请替换为 <ClientRouter />
• getStaticPaths()：移除 Astro.generator；如果在 getStaticPaths() 中使用了 Astro.site，请替换为 import.meta.env.SITE
• 自定义架构：如果升级后验证开始失败，请根据 Zod 4 检查自定义 Zod 用法

对于破坏性变更，请使用对应版本的文档。不要假设旧版迁移建议仍适用于当前 Astro 版本。