Astro 7 升級前要檢查什麼？從 Astro 5／6 到 Vite 8 的建置清單

先確認你在哪個 Astro major#

Astro 官方 v7 migration guide 是從 v6 到 v7；如果專案還在更舊版本，文件建議先完成前一個 major 的升級。不要把 Astro 5、6、7 的所有 breaking changes 一次混在同一個 diff 裡。

我在 ZeroOne 專案本機查到目前版本是 Astro 5.12.8、pnpm 9.14.4：

1
pnpm list astro --depth 0
2
pnpm why astro

升級前先建立分支並保存基準：

1
git switch -c chore/astro-7-upgrade
2
pnpm install
3
pnpm check
4
pnpm build

如果目前是 Astro 5，先依 Astro 6 的 migration guide 完成一次獨立檢查；確認 baseline build 通過後，再進入 v7。若已在 v6，官方推薦用這個工具同步更新 Astro 與官方 integrations：

1
pnpm dlx @astrojs/upgrade

執行升級工具後先看 package.json 與 pnpm-lock.yaml 的 diff，不要在沒有讀過相依版本的情況下直接提交。

Vite 8：先查自訂 plugin 與 bundler 設定#

Astro 7 使用 Vite 8 作為開發伺服器與 production bundler。官方指南指出，多數 Astro 專案可能不需要修改，但依賴 Vite internals 的 integration、plugin 或設定要另外檢查。

可以先搜尋：

1
rg -n 'rollupOptions|esbuild|vite|plugin' astro.config.mjs package.json src

不要只看到 rollupOptions 就直接刪除。先確認它是否只是一般 Rollup 相容設定、是否有自訂 plugin、是否引用 Vite 私有 API，再對照 Vite 8 migration guide 測試。升級後至少要重新跑：

1
pnpm check
2
pnpm build

如果 build 速度變快，也要把「輸出檔案、路由數量、Markdown HTML 和 client bundle」一起比對；速度不能取代產出正確性。

Rust compiler 會把寬鬆 markup 變成 build 問題#

Astro 7 使用新的 Rust-based compiler，官方列出的行為差異包括：

• 未閉合的非 void HTML 或 component tag 會報錯。
• 不再把語意不合法的 HTML 自動重排成另一種結構。
• JSX-style whitespace handling 可能改變 inline element 之間的空白。

升級前可先做基本搜尋，然後依 pnpm check 和 pnpm build 的錯誤逐一修正：

1
rg -n '<(p|div|span|section|main|article|Layout)([^>]*)$' src --glob '*.astro'
2
rg -n '>\s*<(span|a|strong|em)' src --glob '*.astro'

這兩個搜尋只能抓到一部分風險，不能當成 HTML parser。真正的驗證仍是 build、檢查產出的 HTML，以及在瀏覽器確認文字空白、巢狀結構和互動元件。

把已穩定的 experimental 設定移到正確位置#

Astro v7 migration guide 列出幾個不再需要留在 experimental 的設定：

• logger 改放到頂層。
• queuedRendering 已是預設行為，移除舊旗標。
• rustCompiler 已是預設且唯一的 compiler。
• advancedRouting 已啟用；同時要注意 src/fetch.ts 是保留檔名。
• cache 與 routeRules 若原本在 experimental，要移到頂層。

先找出專案是否真的有這些設定：

1
rg -n 'experimental|queuedRendering|rustCompiler|advancedRouting|routeRules|src/fetch\.ts' \
2
  astro.config.mjs src package.json

沒有使用的功能不要為了「跟新版本一致」而新增設定；有使用的功能才依 migration guide 移動，並為每個設定留下 build 或 runtime 驗證。

src/fetch.ts 與 Markdown pipeline 是兩個容易漏查的邊界#

Advanced Routing 讓 src/fetch.ts 成為 Astro request pipeline 的入口，但 v7 把它列為保留檔名。如果你的專案原本就有同名檔案，升級前要先確認它的用途；不要直接覆蓋。

1
test -e src/fetch.ts && sed -n '1,220p' src/fetch.ts || true

另一個邊界是 Markdown。Astro 7 引入新的預設 Markdown processor；如果專案依賴 remark／rehype plugin 的順序、AST 節點或自訂 directive，不能只看文章頁面還能打開就算完成。

ZeroOne 目前的設定檔有多個 remarkPlugins、rehypePlugins、數學公式、GitHub card 和自訂 admonition。升級時應先列出它們：

1
rg -n 'remarkPlugins|rehypePlugins|remark-|rehype-' astro.config.mjs src

如果某個 plugin 依賴 unified pipeline，對照 Astro 文件是否需要明確使用 @astrojs/markdown-remark；不要在沒有測試所有 Markdown 文章前，直接接受預設 processor。應至少抽查表格、程式碼區塊、數學公式、directive、內部連結與 FAQ schema。

移除項目要在升級前找出來#

Astro v7 migration guide 也列出先前已 deprecated 或被移除的項目，例如 @astrojs/db。搜尋的目的不是把所有命中都批次刪掉，而是先知道哪一項會影響 runtime：

1
rg -n '@astrojs/db|getContainerRenderer|astro:transitions' \
2
  package.json pnpm-lock.yaml astro.config.mjs src

如果沒有命中，記錄為已確認；如果有命中，就單獨建立 migration commit，避免和 Vite、Markdown、HTML 變更混在一起。

建置通過後，還要驗證網站輸出#

靜態部落格最容易漏掉的是「build 成功，但產出的 HTML 或網址變了」。升級後至少檢查：

1. 首頁、文章、tag、archive、RSS、sitemap 與英文路徑仍能產生。
2. published、canonical、hreflang 和 trailing slash 沒有改變。
3. Markdown heading id、程式碼區塊、數學公式與 admonition 沒有消失。
4. 圖片路徑、local cover、Pagefind index 和 RSS description 都正常。
5. 針對一篇使用 Content Loader 的文章，再確認資料仍能載入；可搭配 Astro Content Loader 的 glob collection 實作 對照。

若是 CSP、遠端圖片或 SEO 設定在升級後出現差異，應回到各自的檢查清單，例如 Astro CSP inline script 與 style 的 Report-Only 驗證 和 遠端圖片白名單設定，不要把所有輸出問題都歸咎於 Vite。

一個可回滾的 Astro 7 升級流程#

可以把整個變更切成以下順序：

1. 保存 Astro 5／6 的 pnpm check、pnpm build 與輸出抽查結果。
2. 依官方 migration guide 先完成前一個 major，再升到 Astro 7。
3. 讀 package.json、lockfile 與 integration diff。
4. 盤點 Vite plugin、experimental 設定、src/fetch.ts 和 Markdown plugin。
5. 逐項修正 compiler、Markdown 或 integration 問題。
6. 重跑 check、build，並抽查路由、HTML、搜尋索引和社群 metadata。
7. 只有在輸出與必要 runtime 行為都通過後，才合併升級。

這樣做的重點是保留一個能回到「已知可用」的節點。Astro 7 帶來的功能很多，但升級是否安全取決於你的 integration、Markdown pipeline 和實際產出，不是 release note 上的功能數量。

常見問題#