# @brainwebuk/astro-payload-live-preview [Payload CMS](https://payloadcms.com) 的 [Astro](https://astro.build) [实时预览](https://payloadcms.com/docs/live-preview/overview) —— 在您输入时即可在 Payload 管理面板中看到草稿内容的更新。 本软件包为 Astro 实现了 Payload 的[服务端实时预览](https://payloadcms.com/docs/live-preview/server)模式：每次保存文档（草稿保存、自动保存或发布）时，管理面板都会通知您的 Astro 站点，站点会在服务器上重新渲染路由并原地替换为新的 HTML —— 如果您使用 Astro 的 ``，则无需整页刷新。 ``` ┌─────────────────────────┐ save / autosave ┌──────────────────────────┐ │ Payload admin panel │ ──── postMessage ───► │ Your Astro site (SSR) │ │ (Live Preview iframe) │ │ │ └─────────────────────────┘ │ → re-fetch + DOM swap │ └──────────────────────────┘ ``` ## 环境要求 - **在 SSR 模式下运行的 Astro 4、5 或 6** —— `output: 'server'`（或在预览路由上设置 `export const prerender = false`），搭配任意 adapter。静态生成的页面如果不重新构建，则无法反映已保存的更改。 - **Payload 3.x** 运行在您的 Astro 服务器可以访问的任何地方（独立应用、同一个 monorepo 等）。 - 在您想要预览的集合上启用**草稿 + 自动保存**（autosave 让人感觉它是实时的 —— 建议设置一个较短的间隔，例如 `100`）。 ## 安装说明 ``` npm install @brainwebuk/astro-payload-live-preview # 或者 pnpm add @brainwebuk/astro-payload-live-preview ``` ## 使用方法 **1. 在您的 Payload 配置中配置实时预览**，指向您的 Astro 站点。包含一个预览 secret，这样只有管理面板才能查看草稿： ``` // payload.config.ts export default buildConfig({ admin: { livePreview: { collections: ['posts'], url: ({ data }) => `${process.env.ASTRO_URL}/posts/${data.id}?preview=${process.env.PREVIEW_SECRET}`, }, }, collections: [ { slug: 'posts', fields: [{ name: 'title', type: 'text', required: true }], versions: { drafts: { autosave: { interval: 100 }, }, }, }, ], }) ``` **2. 在您的 Astro 页面上渲染 ``**，仅在预览 secret 匹配时获取草稿： ``` --- // src/pages/posts/[id].astro import { RefreshRouteOnSave } from '@brainwebuk/astro-payload-live-preview' const isPreview = Astro.url.searchParams.get('preview') === process.env.PREVIEW_SECRET // Fetch from Payload however you like: Local API, REST, or GraphQL. // Pass draft: true (Local API) or ?draft=true (REST) when previewing. const post = await fetchPost(Astro.params.id, { draft: isPreview }) if (!post) { return new Response(null, { status: 404 }) } ---

{post.title}

{isPreview && } ``` `serverURL` 是您的 Payload 管理面板的源（例如 `http://localhost:3000`）。它用于验证传入的 `postMessage` 事件的来源。 **3. （推荐）将 `` 添加到您的布局中**，以实现无闪烁刷新： ``` --- import { ClientRouter } from 'astro:transitions' --- ``` 使用 `` 时，每次保存都会原地替换 DOM 并保留滚动位置。如果不使用它，该组件将回退到标准的整页重新加载 —— 仍然可用，只是不够流畅。 ## API ### `` Astro 组件。渲染一个不可见的自定义元素，用于监听 Payload 文档事件并在每次保存时刷新当前路由。 ### `subscribeToRefresh({ serverURL, refresh })` / `unsubscribeFromRefresh(subscription)` 底层辅助函数（也可从 `@brainwebuk/astro-payload-live-preview/client` 获取），适用于希望使用自定义刷新策略连接自己的客户端脚本的情况。 ## 获取草稿内容 您的 Astro 服务器与 Payload 分开运行，因此草稿访问需要明确的策略。此处以及[示例](./example)中使用的模式如下： 1. 在 `admin.livePreview.url` 查询字符串中放入一个 secret（`?preview=...`）。 2. 在 Astro 端，将其与您环境中的同一个 secret 进行比较。 3. 仅在匹配时使用 `draft: true` 进行获取。 如果您通过 REST 而非 Local API 获取，请对服务器到服务器的请求进行身份验证（例如 API 密钥用户），因为默认情况下访问草稿需要经过身份验证的用户。 ## 示例 [`example/`](./example) 目录包含一个完整可用的设置：一个 Payload 应用（`example/payload`）和一个 Astro 站点（`example/website`），它们通过 Local API 共享一个 MongoDB 数据库。 ``` pnpm install # 复制 .env 示例并根据需要进行调整 cp example/payload/.env.example example/payload/.env cp example/website/.env.example example/website/.env # 需要 localhost:27017 上运行 MongoDB（例如 docker run -p 27017:27017 mongo） pnpm dev:payload # Payload admin on http://localhost:3000 pnpm dev:website # Astro site on http://localhost:4321 ``` 然后在管理面板中打开一篇文章并选择 **Live Preview** 标签页。编辑内容会自动保存，并在您输入时显示在预览窗格中。 ## 工作原理 - Payload 的管理面板将您的 Astro 页面嵌入到 iframe（或弹出窗口）中，并在每次保存时通过 `window.postMessage` 发出 `payload-document-event`。 - 本软件包的组件发送 [`ready`](https://payloadcms.com/docs/live-preview/server#building-your-own-router-refresh-component) 握手信号，监听文档事件（根据 `serverURL` 验证事件来源），并通过 `astro:transitions/client` 的 `navigate()` 进行刷新 —— 当未启用视图过渡时，则回退到 `window.location.reload()`。 - 与 Payload 的 React `RefreshRouteOnSave` 不同，它特意**不**在挂载时刷新：Astro SSR 页面在 iframe 加载时会重新渲染，如果在整页重新加载回退机制下进行挂载时刷新，将会导致死循环。 ## 开发说明 这是一个 pnpm 工作区： - `package/` — 可发布的软件包（源码在 `package/src` 中，示例直接调用它，因此更改会立即生效） - `example/` — Payload + Astro 演示应用 ``` pnpm build # build the package (dist/) pnpm release # build + publish to npm ``` ## 许可证 [MIT](./LICENSE.md) 由 [BrainWeb](https://www.brainweb.co.uk/)（英国诺福克的一家网页设计工作室）构建和维护

标签：Astro, CMS, Payload, SSR, Syscall, Web开发, 实时预览, 自动化攻击