如何在 Cloudflare Pages 上使用 Astro SSR 构建一个无头 WordPress 前端界面

为什么选择无头WordPress？

无头WordPress将内容管理与内容呈现分离开来。WordPress继续承担它擅长的任务：存储内容并为编辑人员提供熟悉的管理员界面，而专门的前端框架则负责内容的渲染、路由处理及性能优化。

在以下情况下，这种分离模式会带来显著的优势：

• 如果您的内容团队已经熟悉WordPress，将他们转移到其他系统只会影响工作效率。无头WordPress能够保持他们现有的工作流程，同时为您提供现代化的前端界面。

• 当您的网站需要某种设计或交互方式，而普通的WordPress主题或页面构建工具无法实现时，定制化的仪表板、交互式工具、数据驱动的布局，或是与非WordPress API的集成方案，都是不错的选择。

• 如果您希望获得快速的内容呈现效果以及现代化的开发工具，同时又不想从头开始重建内容管理系统，那么无头WordPress正是您的理想选择。WordPress在处理内容和媒体文件方面表现优异，而基于CDN的JavaScript前端框架也能高效地完成内容分发工作——这种分离架构能让双方各司其职，发挥各自的优势。

• 如果您需要在多个平台上使用相同的内容，那么一个WordPress实例就可以通过同一个REST API同时为营销网站、移动应用以及内部管理界面提供内容支持。

然而，并非所有网站都适合采用无头WordPress架构。如果您的网站只是一个简单的宣传资料，或者只由一个人负责所有的管理员工作，又或者您没有足够的开发资源来维护第二个代码库，那么普通的WordPress主题可能才是更合适的选择。

架构原理

“无头”这一概念意味着要剥夺WordPress的前端处理功能。在这种情况下，WordPress不再负责生成并向用户发送HTML页面，而仅通过REST API来存储和提供内容；真正负责呈现给用户的界面，则由专门的前端框架来完成。

当用户访问网站时，请求会首先到达Cloudflare Pages，然后由Astro服务器处理。Astro会通过WordPress的REST API获取所需内容，生成HTML页面后返回给用户。整个过程中，WordPress从未直接接触用户的浏览器。

内容编辑人员仍然可以通过CMS子域名登录WordPress管理员界面，像平常一样进行内容的编写、发布和管理。一旦内容被发布，就会立即生效——因为Astro会在每次请求时都获取最新的数据，所以根本不需要重新构建页面。

从WordPress 4.7版本开始，REST API就已经成为其内置功能之一。因此，您无需使用GraphQL插件、付费的无头CMS服务，也不需要额外的基础设施支持。

为什么选择Astro？

在这里，您也可以使用Next.js、Nuxt或SvelteKit等框架。但我之所以选择Astro，是因为它的默认配置非常适合这种使用场景。

Astro会将组件编译成普通的HTML代码，并且默认情况下不会向浏览器发送任何JavaScript代码。只有在你确实需要使用客户端JavaScript代码的地方，才应该添加它们。

对于那些由内容管理系统驱动的网站来说，大多数页面其实并不需要使用客户端JavaScript。采用服务器端渲染模式意味着每次请求都会在运行时从WordPress系统中获取最新的数据，因此当内容发生变化时，这些变化会立即生效，而无需重新构建整个网站。Cloudflare提供了官方适配器来处理编译后的输出文件；而Tailwind v4则可以通过Vite插件进行集成，而且完全不需要配置文件。

如果WordPress不是必须使用的工具，我就会选择使用Next.js搭配Payload CMS。Payload是一种基于TypeScript开发的、功能完备的内容管理系统，它可以与Next.js项目一起使用，从一开始就能让你对内容结构有更强的控制能力。但由于我们的需求是必须使用WordPress，而对于那些需要通过WordPress的REST API来构建前端界面的项目来说，Astro无疑是一个更快、更简洁的选择。

基础设施配置

我的配置方案如下：域名是在Namecheap注册的，网站托管在Hostinger提供的共享主机上，同时我也使用Google Workspace作为电子邮件服务。以下步骤适用于任何类型的服务器环境，无论是使用cPanel或hPanel管理的共享主机，还是安装了Apache或Nginx的VPS，甚至是自己管理的服务器。

步骤1：将DNS记录迁移到Cloudflare

首先，你需要将你的域名的名称服务器迁移到Cloudflare。这样不仅可以获得免费的DDoS防护和SSL加密服务，还可以将自定义域名与Cloudflare Pages关联起来。

在迁移之前，请确保所有的DNS记录都已经被正确转移，包括网站的A记录或CNAME记录。对于电子邮件服务来说，你需要从你的邮件服务提供商的管理面板中获取MX、SPF、DKIM和DMARC等设置信息，并先将这些信息添加到Cloudflare的DNS系统中；否则，在DNS记录传播完成之前，你的电子邮件服务可能会出现故障。

步骤2：创建内容管理系统的子域名

你需要将WordPress网站迁移到cms.yourdomain.com这个子域名上，这样主域名就可以被Astro使用了。在Cloudflare的DNS设置中，添加一条A记录，将cms指向你的服务器IP地址；如果你的托管服务使用的是CDN服务，也可以使用CNAME记录。然后，在你的主机管理面板中创建这个子域名，并将其指向相同的WordPress目录。

有一点需要注意：你的服务器需要拥有自己的SSL证书，这样才能确保Cloudflare与你的网站服务器之间的连接能够正常工作。虽然Cloudflare会在其边缘节点处理SSL加密任务，但如果你的网站服务器没有SSL证书，就会出现525错误。

在Hostinger平台上，新创建的子域名并不会自动配置SSL证书。你需要通过hPanel手动安装SSL证书；在cPanel平台上，可以使用Let’s Encrypt服务；而在VPS上，则可以使用Certbot工具来生成SSL证书。

将WordPress网站从主域名上迁移到子域名上，也会导致你的主域名的/wp-admin路径不再存在，这样可以降低安全风险。不过，在子域名上，默认的登录路径仍然是/wp-admin。这是你需要首先进行修改的地方——关于这个问题的更多细节，请参见文末的“注意事项”部分。

WordPress配置设置

告知WordPress网站实际位于子域名上

在wp-config.php文件中，在“配置完成，无需再编辑！”这条注释之前：

define('WP_HOME', 'https://cms.yourdomain.com');  
define('WP_SITEURL', 'https://cms.yourdomain.com');  

WordPress管理界面现在的地址是cms.yourdomain.com/wp-admin。使用根域名的旧路径已经不再有效，这是有意为之的。

必须使用的插件：Redirect and Preview

WordPress在wp-content目录下有一个名为mu-plugins的文件夹。放在这个文件夹中的插件会被视为必须使用的插件。它们会在每次请求时自动加载，优先于其他普通插件，并且无法通过管理界面来激活或禁用它们。因此，将这些插件放在这里正是为了确保某些功能不会被意外关闭。

创建文件wp-content/mu-plugins/headless-redirect.php：

<?php  
/*
插件名称：Headless Redirect  
描述：将前端访问者重定向到Astro网站，并修改WordPress的预览链接设置。  
*/

add_action('template_redirect', function() {
    if (is_user_logged_in()) return;
    if ($_SERVER['HTTP_HOST'] === 'cms.yourdomain.com') {
        wp_redirect('https://yourdomain.com', 302);
        exit;
    }
});

add_filter('preview_post_link', function(\(link, \)post) {
    $token = HEADLESS-preview_SECRET;
    \(type  = \)post->post_type;
    return 'https://yourdomain.com/preview?type=' . \(type . '&id=' . \)post->ID . '&token=' . $token;
}, 10, 2);

当WordPress准备渲染页面时，template_redirect插件会被执行。如果访问者未登录且请求来自CMS子域名，系统会将其重定向到主前端页面；已登录的编辑人员则可以正常进入管理界面。而发送到/wp-json/...的REST API请求不会经过template_redirect处理，因此不受其影响。

preview_post_link插件会改变编辑人员在预览文章时所看到的页面内容。默认情况下，WordPress会使用自己的主题进行预览，但在无头架构中，这个主题会导致页面显示为空白。
这个插件会将预览链接替换为指向您Astro平台/preview页面的请求，同时传递文章ID、文章类型以及一个秘钥。Astro平台的预览页面会利用这些信息通过REST API获取文章内容，并将其以与在线版本完全相同的方式呈现出来。

清理插件

现在该删除所有用于渲染前端的插件了：页面构建工具、缓存插件以及用于配置服务器环境的插件等。

不过，您应该保留Akismet、Wordfence和Yoast SEO插件。Yoast会直接在REST API响应中添加SEO元数据和Open Graph信息，而这些数据会被Astro平台的post.yoast_head_json字段读取。

接下来，将当前激活的主题切换为一个轻量级的默认主题。虽然WordPress要求至少有一个激活主题，但实际上没有人会看到这个默认主题。

Astro前端

首先使用pnpm create astro@latest命令创建项目，然后安装Cloudflare适配器和Tailwind插件：

pnpm add @astrojs/cloudflare
pnpm add -D @tailwindcss/vite tailwindcss

astro.config.mjs

import { defineConfig } from 'astro/config'
import cloudflare from '@astrojs/cloudflare'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  output: 'server',
  adapter: cloudflare({ imageService: 'passthrough' }),
  vite: { plugins: [tailwindcss()] },
})

output: 'server' 这个设置会使 Astro 进入完全的 SSR 模式。如果不使用这个选项，Astro 会在构建时预先渲染页面，而这会导致那些依赖于在构建时还不存在的 WordPress 内容的动态路由（比如 /blog/[slug]）无法正常工作。

imageService: 'passthrough' 这个设置对于使用 Cloudflare Workers 是必不可少的。Astro 的默认图像处理服务依赖于 Sharp，而 Sharp 又需要用到 child_process 和 fs 这些 Node.js 内置模块。但在 Cloudflare Workers 环境中，这些模块并不存在，因此会导致部署失败。将 imageService 设置为 ‘passthrough’ 可以完全跳过图像处理步骤，直接使用标准的 标签来显示图片。

.env

WORDPRESS_API_URL=https://cms.yourdomain.com

在部署之前，请将这个变量添加到 Cloudflare Pages 项目设置中的 “环境变量” 部分。

src/lib/wordpress.js

这个文件是所有 WordPress API 请求的集中处理点。将所有的 API 请求集中在这个文件中，意味着如果 API 地址或认证信息发生变化，只需要修改这一个文件即可。

_embed 这个参数非常重要。默认情况下，帖子的响应内容只包含帖子本身的数据，而推荐图片、作者信息以及分类信息则是单独存在的实体，它们各自都有独立的 ID。如果没有 _embed 这个参数，就需要通过额外的 API 请求来获取这些信息。而添加了这个参数之后，所有相关的信息都会被一起包含在同一个响应结果中。

cache: 'no-store' 这个设置在每次进行 API 请求时都是必须使用的。Cloudflare Workers 内部会使用一个独立的缓存系统来存储请求结果，这个缓存系统与 HTTP 中的 Cache-Control 头信息是分开管理的。如果不禁用这个缓存功能，Cloudflare 会在边缘服务器上缓存你的 WordPress API 响应结果。因此，当编辑者发布一篇新帖子时，由于系统中仍然保存着旧版本的帖子内容，前端页面可能会显示旧版本的信息。

const WP_URL = import.meta.env.WORDPRESS_API_URL

const fetchWP = (path) =>
  fetch(`\({WP_URL}\){path}`, { cache: 'no-store' }).then((r) => r.json())

export const getPosts = (page = 1, perPage = 10) =>
  fetchWP(`/wp-json/wp/v2/posts?_embed&per_page=\({perPage}&page=\){page}`)

export const getPostBySlug = async (slug) => {
  const posts = await fetchWP `/wp-json/wp/v2/posts?_embed&slug=${slug)`
  return posts[0]
}

export const getCategories = () =>
  fetchWP `/wp-json/wp/v2/categories`

export const getPostsByCategory = (categoryId, page = 1) =>
  fetchWP `/wp-json/wp/v2/posts?_embed&categories=\({categoryId}&page=\){page}`)

export const getAllPostsForSitemap = () =>
  fetchWP `/wp-json/wp/v2/posts?_fields=slug,modified&per_page=100`

站点地图功能使用_fields而非_embed来获取所需的字段，从而确保请求的体积保持较小。
src/middleware.js
中间件会在每个请求被处理之前被执行。这个中间件会为所有的服务器端渲染响应添加Cache-Control: no-store头信息，这样Cloudflare就不会缓存这些已渲染的HTML页面。
export function onRequest(_context, next) {
  return next().then(response => {
    const newResponse = new Response(response.body, response)
    newResponse.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate')
    newResponse.headers.set('CDN-Cache-Control', 'no-store')
    return newResponse
  })
}

Astro提供的原始Response对象的头部信息是不可变的，因此不能直接使用.headers.set()来修改这些头部信息。解决办法是使用原始的响应体作为参数来创建一个新的Response对象，因为新对象的头部信息是可以被修改的，所以此时就可以使用.set()方法了。CDN-Cache-Control是Cloudflare专门设置的一个头部信息，它用于控制边缘节点上的缓存行为，这个头信息的设置与标准的Cache-Control头信息是相互独立的。
src/layouts/Layout.astro
每个页面都会经过这个布局结构。HTML结构、元标签以及全局导入的内容都放在这里，这样就不需要在每个页面上都重复编写这些内容了。
---
interface Props {
  title: string
  description?: string
}
const { title, description = '' } = Astro.props
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />