Astro 7.4.2 升級檢查：Node.js 門檻、開發伺服器與建置回歸

7.4.2 先核對 Node.js，再檢查 dev 與 build 是否互相干擾#

7.4.2 的 package.json宣告 engines.node: >=22.23.4。這是套件最低門檻，不代表任何高於該數字的舊 patch 都已包含最新安全修正。官方此次提高門檻的理由是 10 月 Node.js 安全更新；若使用 Node.js 24 或 26，仍需核對自己版本線的安全 patch，可參考 Node.js 更新判斷與回歸清單。

在專案根目錄、本機終端與 CI 的安裝階段各執行一次下列唯讀指令；部署時若有 server runtime，也在那個環境核對。靜態站則先確認實際負責 build 的環境：

1
node --version
2
node -p 'JSON.stringify({ executable: process.execPath, node: process.versions.node, platform: process.platform, arch: process.arch })'
3
pnpm list astro --depth 0

把每個環境的結果列在同一份升級紀錄中。只修改 .nvmrc 或 CI matrix 而未核對實際 binary，不能證明平台已採用新版本；engines 通過也不能取代依賴安裝和應用測試。

這次修正的驗收依功能分流，沒有使用的項目標示不適用：

先建立升級前的可重現基準，再逐項驗收。若只能執行 production build，就把 dev、adapter 與載入順序測試記為未驗證，不要把整份清單勾選完成。

先確認你在哪個 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 的回歸項目#

如果從 7.3.2 或更舊版本升級，下列歷史 patch 的修正仍適合作為回歸範圍。它們不是本次 7.4.2 才加入的功能；只測一次 production build 也無法涵蓋 dev 行為。

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

升級最容易漏掉的是「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. 固定目標 Astro 7.4.2 與對應 Node.js 安全 patch，再依本次與歷史修正清單執行適用的 smoke test。
5. 比較路由、HTML、asset、搜尋索引、RSS 與 runtime metadata。
6. 只有在輸出與必要 runtime 行為都通過後，才合併升級；保留上一個可部署版本作為回退點。

常見問題#