為 Zephyr 設定 Astro
設定
請先閱讀網站既有的 astro.config.*、其 output 模式與適配器，以及已安裝的 astro 版本，再進行編輯。保留其現有的 integrations 與選項。若缺少 zephyr-astro-integration，僅在獲得依賴變更授權時才安裝；它只會在編譯時期需要，因此開發依賴就已足夠。
已安裝的套件宣告 astro 同儕依賴為 ^4.0.0 || ^5.15.8 || ^6.4.6 || ^7.0.7，並使用 Astro 提供的 Vite 版本。將 withZephyr() 作為 integrations 的最後一項加入：
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import { withZephyr } from 'zephyr-astro-integration';
export default defineConfig({
site: 'https://example.com',
integrations: [mdx(), sitemap(), withZephyr()],
});
Astro 會依序執行 astro:build:done 鉤子，一次一個整合，而 Zephyr 會從該鉤子上傳檔案。將其列在最後可讓先前的整合（例如 sitemap）寫入的檔案在上傳前存在。預設匯出即為同一個 withZephyr 函式。請勿同時將 vite-plugin-zephyr 加入 vite.plugins；該整合已負責發布作業。
Module Federation
此整合不會設定 Module Federation，也不會將 zephyr:dependencies 解析為遠端 URL。其 mfConfigs 與 federation 選項是未經修改直接轉送的發布中繼資料，僅在 TAP 套件中需要。在設定前請先閱讀發布詳細資料。共用的 zephyr-module-federation 指南涵蓋跨專案的主機與遠端模型。
僅限靜態輸出
此整合會上傳 Astro 傳遞給 astro:build:done 的目錄，且從不傳送伺服器進入點或快照類型。該目錄即為客戶端輸出，因此它發布的是靜態網站。若使用 output: 'server' 或適配器，僅會發布客戶端與預先渲染的檔案；隨選路由、API 端點與中介軟體則不會發布。請勿將此整合視為 SSR 部署路徑，也不要在未經授權的情況下移除使用者的適配器以強行配合；請改為回報此限制。
此整合也會從網站的 .env 檔案載入 ZE_PUBLIC_* 值，並改寫 import.meta.env.ZE_PUBLIC_* 與 process.env.ZE_PUBLIC_* 的讀取，以便環境可以在建置後覆寫這些值。共用的 zephyr-core 指南涵蓋此模型。
避免誤導性的修正
- 請勿將成功的
astro build視為發布。建置鉤子中的 Zephyr 錯誤會被記錄，且建置會繼續進行，除非設定了ZE_FAIL_BUILD=true；只有無效的target會立即擲出錯誤。 - 請勿在一般網站上設定
target: 'tap-app'。TAP 會停用ZE_PUBLIC_*改寫，並需要成對的 federation 中繼資料。 - 請勿假設原始碼映射檔會被發布；一般網站的
.map檔案會被跳過。 - 請勿將憑證放入
ZE_PUBLIC_*；這些值為客戶端可見。
驗證完成
使用網站既有的套件執行器，執行已授權的建置。確認輸出目錄包含預期的頁面與資產，且 Zephyr 回報成功的發布並附上版本 URL。沒有憑證的建置可以確認本機輸出的正確性，但無法確認即時部署的成功。請報告此區別，並清楚說明伺服器渲染的路徑不在發布範圍內。
若失敗，請保留可操作的錯誤訊息，並修正對應的設定。請勿在未經授權的情況下擅自變更網站的輸出模式、壓制錯誤，或宣稱部分建置已部署。