用途：当需要把项目从其他框架迁移到 Astro、把静态站点转化为 Astro，或升级现有 Astro 代码库时使用本技能。若项目可用 astro-best-practices，应同时应用，使结果符合 Astro 良好默认，而非机械复刻旧系统。
工作流程：先盘点现状，包括路由结构、布局/共享外壳、数据源、样式策略、交互组件、图片处理和部署/运行时要求，据此决定目标为静态、混合或服务端渲染。再选择迁移形态，常见模式有静态 HTML 转为 Astro 页面与布局、Next.js 或 Nuxt 转为 Astro 页面加框架岛、Gatsby 内容/数据流转为内容集合、Astro 大版本升级遵循官方升级指南；对运行时行为较多或交互面较大的应用，优先增量迁移。随后按概念映射而非盲抄文件：共享应用外壳→布局，路由组件→页面或动态路由，Markdown/内容管线→内容集合，纯框架组件→带客户端指令的岛，图片助手→astro:assets 或项目现有图片策略。静态内容通常应改为 .astro。
重建路由与数据流：在 src/pages/ 重建路由，共享包装移入 src/layouts/，结构化内容迁至 src/content/，用 Astro 前言或内容 API 替代框架特有取数方式；原先用 getStaticPaths 风格生成路由的页面，应在 Astro 中显式重建。交互以岛处理：静态外壳保留在 .astro，交互部分保留框架组件作岛，有意识地选择客户端指令，尽量缩小水合范围。最后校验路由一致性、元数据与 head 输出、图片渲染、表单行为、键盘导航、构建与预览行为及部署假设。
Astro 升级：从官方升级指南开始，合适时使用 npx @astrojs/upgrade；官方集成与适配器应随 Astro 一并更新；先在本地和部署环境确认 Node 版本满足要求。Astro 6 需检查：Node 22.12.0 或更新；内容集合使用 src/content.config.*，每个集合定义 loader，移除 type，从 astro/zod 导入 z，用 entry.id 替代 slug，用 render(entry) 替代 entry.render()；移除 legacy.collections 配置；用 import.meta.glob() 或 getCollection() 替代 Astro.glob()；若存在 <ViewTransitions /> 则替换为 <ClientRouter />；getStaticPaths() 中移除 Astro.generator，并将 Astro.site 替换为 import.meta.env.SITE；若升级后校验失败，按 Zod 4 审查自定义 Zod 用法。请查阅对应版本文档以了解破坏性变更，不要假定旧迁移建议仍适用于当前版本。