---
title: "Firebase Studio 项目迁移到 Antigravity"
description: "基于 Google 官方迁移文档，梳理 Firebase Studio 项目导出、Antigravity 自动迁移、Firebase CLI 手动迁移、本地预览和发布路径。"
verifiedAt: "2026-05-06"
---

Firebase Studio 的 Code view 是云端 Web 编辑器；Antigravity 是本地运行的 agent-first 开发平台。迁移不是简单“换一个编辑器打开项目”，而是把项目从云端工作区导出到本机，让 Antigravity 在本地文件系统、终端、Firebase CLI 和 agent 工作流里继续推进。

Google 官方迁移文档给了两条路：让 Antigravity agent 自动处理迁移，或者用 Firebase CLI 手动导出。真正落地时，推荐先按自动迁移跑一遍；如果你想节省 AI token、明确知道项目结构，或者需要排查转换细节，再用 CLI 手动处理。

> [!NOTE]
> **这一篇适合谁**：你在 Firebase Studio 里已经有项目，现在要迁移到本地 Antigravity，继续本地预览、调试、部署 Firebase App Hosting 或其他 Firebase 相关服务。

> [!TIP]
> **阅读目标**：读完本章，你应该能判断自己该走 Antigravity agent 自动迁移还是 Firebase CLI 手动迁移，并知道迁移后先预览、再发布。

## 1. 为什么迁移到 Antigravity

Google 官方文档给出的迁移理由可以拆成三点。

| 变化 | 对开发者意味着什么 |
| --- | --- |
| 本地环境控制 | 项目文件、依赖版本、终端、调试工具都回到你自己的机器 |
| 真正 agentic development | agent 可以格式化、测试、修改和推进完整任务，而不只是云端补全 |
| 继续支持 Firebase | 仍然可以用 Firebase CLI、本地 emulator、App Hosting 和部署流程 |

这不是否定 Firebase Studio。更准确地说：Firebase Studio 适合快速原型和云端编辑，Antigravity 更适合把项目带回本地，进入更完整的 agent-first 开发闭环。

## 2. 迁移前准备

官方文档要求先准备三样东西：

- Google Antigravity IDE
- Node.js 20 或更高版本（以 [官方 Migration 页](https://antigravity.google/docs/firebase-studio-migration) 当前要求为准）
- Firebase CLI 15.10.0 或更高版本（同上）

本地可以这样确认：

```bash
node --version
npx firebase-tools@latest --version
```

如果你已经全局安装 Firebase CLI，也可以查：

```bash
firebase --version
```

> [!IMPORTANT]
> 迁移前先确认项目能从 Firebase Studio 正常导出。不要在迁移过程中顺手升级框架、换包管理器或重构目录。先把项目完整搬出来，再做工程升级。

```mermaid
flowchart TD
  Studio["Firebase Studio workspace"] --> Export["Zip & Download / studio:export"]
  Export --> Local["解压到本机目录"]
  Local --> Open["用 Antigravity 打开"]
  Open --> Path{"选择迁移方式"}
  Path -->|自动| Agent["@fbs-to-agy-export"]
  Path -->|手动| CLI["Firebase CLI studio:export"]
  Agent --> Preview["本地预览"]
  CLI --> Preview
  Preview --> Deploy["确认后再发布"]
```

## 3. 自动迁移：让 Antigravity agent 处理导出结果

自动迁移适合大多数用户，尤其是你希望 agent 帮你识别项目结构、转换配置并提示下一步操作时。

按官方路径：

1. 在 Firebase Studio workspace 顶部点击 **Move now**。
2. 根据弹出的窗口选择导出方式。
3. 如果看到 **Zip and Download**，直接下载 zip。
4. 如果没有看到下载按钮，打开 command palette，运行 **Firebase Studio: Zip & Download**。
5. 把下载得到的项目解压到本机。
6. 用 Antigravity 打开这个本地目录。
7. 在 Antigravity 的 Agent pane 中输入：

```text
@fbs-to-agy-export
```

官方文档提到，为了优化流程和节省 token，可以选择 Gemini Flash 模型来处理这类高频转换任务。实际操作里，可以把这个理解为：迁移阶段优先用速度和成本更合适的模型，等进入复杂代码判断或架构修改时再切回更强模型。

> [!TIP]
> 如果下载窗口没有出现，先检查浏览器地址栏是否拦截了弹窗，并允许 Firebase Studio 弹出下载窗口。

## 4. 自动迁移时怎么和 agent 配合

`@fbs-to-agy-export` 不是“输入以后就不用管”。官方文档说明，agent 会开始项目迁移，并在过程中请求你的协助。你需要重点盯住三类信息：

- 它识别出的项目类型是否正确。
- 它准备修改哪些文件。
- 它要求你批准哪些命令或操作。

建议把第一次迁移当成一次受控任务：

```text
请迁移这个 Firebase Studio 导出的项目。
执行前先列出你判断的项目类型、将要修改的文件类别、需要我确认的命令。
不要删除原始导出内容。
```

如果迁移报错，不要马上手工大改。先让 agent 基于错误重试一次：

```text
根据刚才的错误重新分析迁移失败原因。
先说明根因和你准备调整的步骤，再继续。
```

## 5. 手动迁移：用 Firebase CLI 导出

如果你不想用 AI token，或者想自己控制转换过程，可以使用 Firebase CLI。

官方给出的命令是：

```bash
npx firebase-tools@latest studio:export <path>
```

这里的 `<path>` 可以指向解压后的项目文件夹，也可以指向原始 `.zip` 文件。运行前建议先创建一个干净输出目录，并保留原始 zip：

```text
project-from-firebase-studio.zip
project-from-firebase-studio/
project-after-export/
```

> [!WARNING]
> 官方文档明确提醒：`studio:export` 当前主要针对 Next.js、Flutter 和 Angular workspace 优化。其他类型项目也能尝试，但迁移不一定完整。

手动迁移适合三种情况：

- 你已经知道项目是 Next.js、Flutter 或 Angular。
- 你希望先看转换结果，再决定是否让 agent 继续处理。
- 自动迁移失败，需要分离“导出问题”和“agent 修改问题”。

<details>
<summary>深读：自动迁移和手动迁移怎么选</summary>

自动迁移更适合“不想自己判断所有项目结构”的用户。你把 Firebase Studio 导出的项目交给 Antigravity，由 agent 识别、解释、请求权限并推进下一步。它的好处是交互成本低，但需要消耗 AI token，也需要你认真审查 agent 准备修改的文件和运行的命令。

手动迁移更适合“项目类型清楚、想先保留转换结果”的场景。你用 Firebase CLI 先把导出内容处理出来，再决定是否让 Antigravity agent 接手调试、预览和部署。它更可控，但要求你理解 Firebase CLI 和项目结构。
</details>

## 6. 本地预览迁移后的项目

项目迁移到 Antigravity 后，先预览，不要马上发布。

官方文档给出的路径是：

1. 在 Antigravity 左侧打开 **Run and Debug**。
2. 点击 play button 启动本地开发服务。
3. 按 terminal 输出的说明打开预览页面。

你要验证的不是“服务能跑起来”这么简单，而是：

- 页面能打开。
- 主要路由能访问。
- Firebase 相关功能没有因为本地环境缺失而直接崩溃。
- `.env`、secrets、Firebase project 选择没有误指向生产环境。
- agent 能解释如何继续调试，而不是盲目发布。

可以让 agent 做一次只读检查：

```text
请检查迁移后的项目能否本地预览。
先不要修改文件。
请告诉我需要安装哪些依赖、运行哪个命令、预览成功后应该检查哪些页面。
```

## 7. 发布：用 agent 或 Firebase CLI 继续走 App Hosting

官方迁移文档说明，Antigravity 可以通过 agent skills 按 Firebase best practices 发布应用。最直接的提示是：

```text
Publish my app
```

当 agent 请求运行 `firebase deploy` 时，你需要明确批准。第一次发布时，agent 可能会引导你完成 App Hosting 流程；如果项目之前已经发布过，它会尝试发布到已有 URL。

> [!IMPORTANT]
> 发布前必须确认 Firebase project、region、App Hosting backend、环境变量和 secrets。`firebase deploy` 是有外部副作用的命令，不要默认允许 agent 自动执行。

推荐发布前加一条约束：

```text
发布前先列出：
1. 当前 Firebase project
2. 将要部署的目标
3. 会运行的命令
4. 可能影响线上用户的风险
等我确认后再执行 firebase deploy。
```

## 8. 后续工作怎么继续

迁移完成后，可以沿着三条线继续：

- **Workflows**：在 agentic chat 里通过 `@workflows <workflow_name>` 继续执行工作流。
- **App Hosting deployments**：用 agent skills、Firebase CLI 或 GitHub 继续部署。
- **Troubleshooting**：部署失败时，先重新认证 Firebase CLI，再检查 project secrets 和本地环境。

常见故障处理顺序：

1. `firebase login` 或重新认证。
2. `firebase projects:list` 确认当前账号能看到目标项目。
3. 检查 `.firebaserc` 是否指向正确项目。
4. 检查本地 `.env` 和 secrets 是否齐全。
5. 再让 Antigravity agent 根据具体错误继续排查。

## 9. 什么时候不要急着迁移

下面几种情况，先停下来盘点：

| 情况 | 原因 |
| --- | --- |
| 项目依赖真实生产 Firebase project | 迁移和预览可能误操作生产资源 |
| 项目里没有清晰 `.firebaserc` | agent 可能无法判断目标 project |
| workspace 不是 Next.js / Flutter / Angular | 官方 CLI 迁移支持可能不完整 |
| 项目有大量 secrets | 先做本地凭据隔离 |
| 团队多人正在改同一项目 | 先确认 Git 分支和冻结窗口 |

迁移的目标不是“把项目弄到 Antigravity 里”，而是让项目进入可验证、可回退、可继续部署的本地开发闭环。

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. 自动迁移和手动迁移分别适合什么场景？
2. 为什么迁移过程中不要顺手升级框架、换包管理器或重构目录？
3. 运行 `firebase deploy` 前必须确认哪些项目和环境边界？

通过标准：你能先保留原始导出物，再选择迁移方式，最后完成本地预览并在人工确认后发布。

## 官方来源

- [Google Antigravity Firebase Studio Migration](https://antigravity.google/docs/firebase-studio-migration) —— 官方迁移流程，包含自动迁移、手动导出、本地预览和发布说明。
- [Google Antigravity Download](https://antigravity.google/download) —— 官方 IDE 下载入口，迁移前需先安装本地工具。
- [Firebase CLI reference](https://firebase.google.com/docs/cli) —— Firebase CLI 官方参考，用于核对 `studio:export`、登录和部署命令。
- [Firebase Tools GitHub Issues](https://github.com/firebase/firebase-tools/issues) —— Firebase Tools 问题跟踪入口，用于排查 CLI 迁移异常。

## 接下来去哪

<Cards>
  <Card title="下载与基础导航" description="如果还没安装 Antigravity，先完成下载、平台检查和基础导航。" href="/docs/antigravity/official/00-getting-started/01-download-navigation" />
  <Card title="Agent Manager" description="迁移项目以后，下一步理解如何在 Agent Manager 里管理任务和 artifacts。" href="/docs/antigravity/official/01-agent-manager" />
</Cards>
