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

先確認你在哪個 Astro major#

Astro 官方 v7 migration guide 是從 v6 到 v7。若專案還在 Astro 5，先完成 Astro 6 的獨立升級與 baseline，避免把兩個 major 的 breaking change 混在同一個 diff 裡。

先留下版本、lockfile 和建置基準：

1
pnpm list astro --depth 0
2
pnpm why astro
3
pnpm install --frozen-lockfile
4
pnpm check
5
pnpm build

ZeroOne 的現有文章曾記錄 Astro 5.12.8 與 pnpm 9.14.4；實際升級前仍應以專案當下的 pnpm list 與 lockfile 為準。若目前是 Astro 6，可用官方升級工具整理 Astro 與官方 integration 的版本，但執行後要先讀 package.json 和 pnpm-lock.yaml 的 diff：

1
pnpm dlx @astrojs/upgrade

Vite 8：先查 plugin 與 bundler 設定#

Astro 7 使用 Vite 8 作為開發伺服器與 production bundler。多數專案不一定需要改動，但依賴 Vite internals、特定 plugin API 或 bundler 私有行為的 integration 要單獨驗證。

先找出實際設定，不要看到 rollupOptions 就直接刪除：

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

對每一個命中項目回答三個問題：

1. 它是公開 Vite／Rollup 設定，還是依賴私有 API？
2. 它會改變 chunk、asset、SSR 或 dev server 行為嗎？
3. 升級後有沒有對應的 build、preview 或瀏覽器 smoke test？

不要只用「build 成功」判斷 bundler 相容性；還要比對輸出檔案、路由數量、Markdown HTML、client bundle 和 runtime error。

Rust compiler 會讓寬鬆 markup 變成錯誤#

Astro 7 使用新的 Rust-based compiler，對未閉合 tag、無效 HTML 與 JSX-style whitespace 的處理更嚴格。可以先做低成本搜尋，再把真正的修正交給 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'

這些規則只能抓到部分風險。最小回歸範圍應包含巢狀 component、inline 文字空白、<script>／<style>、表單和含有特殊字元的內容。

把穩定功能移出 experimental#

依 Astro v7 migration guide，升級時要盤點這些設定是否還留在舊位置：

• logger 改放到頂層設定。
• queuedRendering 已是預設行為，移除過時旗標。
• rustCompiler 已是預設且唯一的 compiler。
• advancedRouting 已啟用，並保留 src/fetch.ts 這個特殊檔名的語意。
• cache、route rules 等設定若原本放在 experimental，依文件移到頂層。

使用搜尋建立清單，不要批次刪除所有 experimental：

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

沒有使用的功能不要為了「看起來像新版」而新增設定；有使用的功能則為每一項留下 build 或 runtime 證據。

src/fetch.ts 與 Markdown pipeline#

Advanced Routing 讓 src/fetch.ts 成為 request pipeline 的保留檔名。升級前先確認專案是否已有同名檔案，以及它是不是一般 utility；不要在不了解用途時直接覆蓋：

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

Markdown 也要獨立測試。若專案依賴 remark／rehype plugin 的順序、AST 節點、數學公式或自訂 directive，不能只看文章頁面能開啟就算完成：

1
rg -n 'remarkPlugins|rehypePlugins|remark-|rehype-' \
2
  astro.config.mjs src package.json

至少抽查表格、程式碼區塊、數學公式、admonition、圖片 alt、內部連結與 FAQ schema。如果站台有 Content Loader，也要抽查一篇 collection 文章；可參考 Astro Content Loader 的 glob collection 實作 對照資料是否仍能載入。

7.3.3 與 7.3.4 要補哪些 patch 回歸#

升到 7.3.4 不等於只測一次 production build。下面把官方 release notes 的修正範圍改寫成「有使用才執行」的測試表。

建置成功後要驗證實際輸出#

升級最容易漏掉的是「build 成功，但網址或 HTML 變了」。至少確認：

1. 首頁、文章、tag、archive、RSS、sitemap 與英文路徑仍能產生。
2. published、canonical、hreflang 和 trailing slash 沒有改變。
3. heading id、程式碼區塊、數學公式、admonition 與圖片 alt 都保留。
4. local cover、Pagefind index 和 RSS description 都正常。
5. astro preview 能在乾淨環境啟動；--ignore-lock 只用於處理 preview lock，不是繞過所有部署問題。

1
pnpm check
2
pnpm build
3
pnpm astro preview --ignore-lock

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

一個可回滾的升級順序#

1. 保存目前 Astro 5／6 的 pnpm check、pnpm build 與輸出抽查結果。
2. 先完成前一個 major，再升到 Astro 7；每一個 major 都留下獨立 commit。
3. 讀 package、lockfile、Vite plugin、integration 和 experimental 設定的 diff。
4. 先升到目標 7.3.4，再依 7.3.3／7.3.4 表格執行適用的 smoke test。
5. 比較路由、HTML、asset、搜尋索引、RSS 與 runtime metadata。
6. 只有在輸出與必要 runtime 行為都通過後，才合併升級；保留上一個可部署版本作為回退點。

常見問題#