跳转到内容

无头(headless)模式的 WordPress 与 Astro

WordPress 是一个内容管理系统,虽然它包含了自己的前端,但也可以作为无头(headless)CMS 用于为你的 Astro 项目提供内容。

WordPress 自带了内置的 WordPress REST API,用于将你的 WordPress 数据连接到 Astro。你还可以选择在你的站点上安装 WPGraphQL 来使用 GraphQL。

在开始前,你需要具备以下条件:

  1. 一个 Astro 项目 - 如果你还没有 Astro 项目,我们的安装指南可以帮助你快速上手;
  2. 一个 WordPress 站点 - 你的站点的 REST API 是 [YOUR_SITE]/wp-json/wp/v2/,并在任何 WordPress 站点上都是默认提供的。你也可以在本地环境上安装 WordPress

你的 WordPress REST API 默认情况下可以被外部请求以无需认证的方式获取数据。这不让用户修改你的数据或站点设置,而是让你在 Astro 项目中使用数据而无需任何凭据。

如果需要的话,你可以选择要求身份验证

通过你的站点唯一的 REST API URL 和内容的路由来获取你的 WordPress 数据(对于博客,通常是 posts),然后你可以使用 Astro 的 set:html={} 指令来渲染数据属性。

例如,要显示一个帖子标题和内容的列表:

---
const res = await fetch("https://[你的站点]/wp-json/wp/v2/posts")
const posts = await res.json()
---
<h1>Astro + WordPress 🚀</h1>
{
posts.map((post) => (
<h2 set:html={post.title.rendered} />
<p set:html={post.content.rendered} />
))
}

WordPress REST API 包含了 全局参数,如 _fieldsembed

所以可通过此 API 获取大量的数据,你也可能希望仅获取特定字段。你可以通过在 API URL 中添加 _fields 参数来限制响应,例如:[你的站点]/wp/v2/posts?_fields=author, id, excerpt, title, link

API 还可以返回与文章相关的内容,例如父级文章的链接或评论。你可以在 API URL 中添加 _embed 参数(例如 [你的站点]/wp/v2/posts?_embed),提示服务器在响应中包含这些嵌入资源。

使用 WordPress 和 Astro 构建博客

段落标题 使用 WordPress 和 Astro 构建博客

该示例从 https://norian.studio/dinosaurs/ 的公共 WordPress API 中获取数据。该 WordPress 站点将有关个别恐龙的信息存储在 dinos 路径下,就像博客将个别博文存储在 posts 路径下一样。

该示例展示如何在 Astro 中复制此站点结构:一个索引页面,列出恐龙并链接至动态生成的个别恐龙页面。

显示 WordPress 文章列表

段落标题 显示 WordPress 文章列表

页面 src/pages/index.astro 列出每个恐龙的描述,并提供链接至其独立页面。

  • 目录src/
    • 目录pages/
      • index.astro
      • 目录dinos/
        • [slug].astro
  • astro.config.mjs
  • package.json

通过 API 获取的对象包含以下属性:

  • title.rendered - 包含文章标题的 HTML 渲染结果;
  • content.rendered - 包含文章内容的 HTML 渲染结果;
  • slug - 包含文章的 slug(用于生成动态生成的个别恐龙页面的链接)。
/src/pages/index.astro
---
import Layout from "../layouts/Layout.astro"
let res = await fetch("https://norian.studio/wp-json/wp/v2/dinos")
let posts = await res.json();
---
<Layout title="Dinos!">
<section>
<h1>List of Dinosaurs</h1>
{
posts.map((post) => (
<article>
<h2>
<a href={`/dinos/${post.slug}/`} set:html={post.title.rendered} />
</h2>
<Fragment set:html={post.content.rendered} />
</article>
))
}
</section>
</Layout>

使用 WordPress API 生成页面

段落标题 使用 WordPress API 生成页面

页面 src/pages/dinos/[slug].astro 为每个恐龙 动态生成了一个页面

/src/pages/dinos/[slug].astro
---
import Layout from '../../layouts/Layout.astro';
const { slug } = Astro.params;
let res = await fetch(`https://norian.studio/wp-json/wp/v2/dinos?slug=${slug}`)
let [post] = await res.json();
// The getStaticPaths() 仅适用于静态的 Astro 站点,
// 在 SSR 模式下你不需要使用这个函数。
export async function getStaticPaths() {
let data = await fetch("https://norian.studio/wp-json/wp/v2/dinos")
let posts = await data.json();
return posts.map((post) => ({
params: { slug: post.slug },
props: { post: post },
}));
}
---
<Layout title={post.title.rendered}>
<article>
<h1 set:html={post.title.rendered} />
<Fragment set:html={post.content.rendered} />
</article>
</Layout>

_embed 查询参数会告诉服务器返回相关的(嵌入的)资源。

src/pages/dinos/[slug].astro
---
const { slug } = Astro.params;
let res = await fetch(`https://norian.studio/wp-json/wp/v2/dinos?slug=${slug}&_embed`)
let [post] = await res.json();
---

返回 _embedded['wp:featuredmedia']['0'].media_details.sizes.medium.source_url 属性,并用于在每个恐龙页面上显示特色图像。(可将 medium 替换为你所需的图像尺寸。)

/src/pages/dinos/[slug].astro
<Layout title={post.title.rendered}>
<article>
<img src={post._embedded['wp:featuredmedia']['0'].media_details.sizes.medium.source_url} />
<h1 set:html={post.title.rendered} />
<Fragment set:html={post.content.rendered} />
</article>
</Layout>

要部署你的网站,请访问我们的部署指南,并按照你偏好的托管提供商的步骤说明进行操作。

以下网站在生产环境中使用 Astro + WordPress:

更多 CMS 指南