---
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="/zh-Hant/docs/antigravity/official/00-getting-started/01-download-navigation" />
  <Card title="Agent Manager" description="遷移專案以後，下一步理解如何在 Agent Manager 裡管理任務和 artifacts。" href="/zh-Hant/docs/antigravity/official/01-agent-manager" />
</Cards>
