为 Zephyr 配置 Astro
设置
在编辑之前，请先阅读网站现有的 astro.config.*、其 output 模式和适配器，以及已安装的 astro 版本。保留其现有的集成和选项。如果缺少 zephyr-astro-integration，仅当授权进行依赖更改时才安装它；它仅在构建时使用，因此开发依赖就足够了。
已安装的包声明了 astro 的 peer 依赖为 ^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 中；集成已经负责发布。
模块联合
此集成不配置模块联合，也不将 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_*重写，并要求配对联合元数据。 - 不要假设源代码映射被发布；普通站点的
.map文件会被跳过。 - 不要将凭据放在
ZE_PUBLIC_*中；这些值是客户端可见的。
验证完成
使用站点现有的包运行器执行授权的构建。确认输出目录包含预期的页面和资源，并且 Zephyr 报告了成功的发布，并附带版本 URL。没有凭据的构建可以验证本地输出的正确性，但不能验证实时部署的成功。报告这一区别，并明确说明服务器渲染的路由不在发布的范围内。
失败时，保留可操作的错误并修复匹配的配置。不要静默更改站点的输出模式、抑制错误或声称部分构建已部署。