Astro preview --background 怎麼用？用 status、logs、stop 管理本機預覽

先確認 Astro 版本，再啟動背景預覽#

preview --background 是 Astro 7.2.0 的新功能。先查專案實際使用的 CLI，避免把最新文件的參數套到仍鎖在舊版的專案：

1
pnpm exec astro --version

接著先建立要檢查的 production output，再啟動背景程序：

1
pnpm build
2
pnpm exec astro preview --background

如果 CLI 回報未知選項，先看版本和 lockfile，而不是先改 port。舊版 Astro 沒有這個 flag；應該安排正式的 Astro 升級，再按照 Astro 7 升級與 Vite 8 的檢查清單 驗證 integration、plugin 和輸出。

用子命令查看狀態與 Log#

背景預覽啟動後，可以在同一個專案脈絡執行：

1
pnpm exec astro preview status
2
pnpm exec astro preview logs
3
pnpm exec astro preview logs --follow

status 適合確認程序是否還在執行與取得預覽資訊；logs 適合先看啟動錯誤，--follow 則用於觀察一段時間內的 request 或 runtime 輸出。完成檢查後不要留下舊程序：

1
pnpm exec astro preview stop

如果你修改了 Markdown、astro.config.mjs 或其他會影響輸出的檔案，請重新執行 pnpm build。背景 preview 不會 watch source，也不會自動更新 dist/；它只會繼續服務上一次成功建出的內容。

CI 可以把啟動與清理寫在同一個流程#

需要對 build 後的 HTML 做 smoke test 時，把程序的停止動作放進 cleanup：

1
set -euo pipefail
2

3
pnpm build
4
pnpm exec astro preview --background
5
trap 'pnpm exec astro preview stop || true' EXIT
6

7
pnpm exec astro preview status
8
curl --fail --silent --show-error http://localhost:4321/ > /dev/null

實際 port 依專案設定與 Astro CLI 輸出調整；重點是不要用背景 shell、kill 或模糊的 process name 猜哪個程序該停。用 Astro 自己提供的 lifecycle 命令，讓 log、失敗狀態和 cleanup 路徑比較容易被閱讀與重跑。

如果 CI 本身已經有 process supervisor、timeout 和 log collector，則可以選擇讓它管理前景程序，不要讓 Astro 的自動背景模式和外部管理器同時接管。

AI coding agent 可能會自動啟用背景模式#

Astro 7.2.0 的 release note 說明，當它偵測到 astro preview 是由 AI coding agent 執行時，可能自動啟用背景模式，讓 agent 得以繼續工作。這對互動式開發很方便，但若 automation runner 預期 preview 綁定在自己的 process group，就應明確關閉：

1
ASTRO_PREVIEW_BACKGROUND=0 pnpm exec astro preview

這個環境變數是 opt-out，不是把舊版 Astro 變出新功能。若版本還不到 7.2.0，仍要用舊的前景 preview 流程，或先升級後再驗證。

Preview 不是部署與 production server#

astro preview 只驗證 astro build 產生的輸出。它不負責：

• 監看原始碼並即時 rebuild。
• 提供 production 的 TLS termination、process supervisor 或 health check。
• 取代 Cloudflare、Caddy 或其他 hosting 的正式部署流程。

如果你是在確認靜態站生成後的路由、資產和 404，可以把它當短生命週期的本機檢查工具；正式部署仍要按照 hosting 的輸出模型與 runtime 邊界處理。啟動成功只能證明 preview server 起來，不能證明 production 的 domain、cache、redirect 和 bindings 都已經正確。

最後可用這個順序排查：先確認 Astro 版本 → 重新 build → 啟動 background preview → 查看 status／logs → 做代表性 request → stop。 這樣能把 build 失敗、preview process 失敗和部署環境問題分開。

常見問題#