Astro 与 Headless WordPress 双轨分流架构实践

在现代化 Web 开发中，Headless（无头）架构正变得越来越流行。将 WordPress 作为后台内容管理系统 (CMS)，配合 Astro 这一极致速度的静态站点生成器 (SSG)，可以同时获得 WordPress 无与伦比的编辑体验，以及全站全静态页面的秒开快感。然而，在实际部署中，尤其是在面对复杂的国际网络环境时，如何兼顾国内弱网直连和国外 CDN 边缘加速，是一道必须跨越的工程槛。

本文将分享一套经过工业级实战检验的 Astro + Headless WordPress 智能双轨分流架构。这套方案不仅免去了配置 Cloudflare for SaaS 等繁琐高成本门槛，还能做到国内直连专线极速响应、国外多节点边缘秒开、全站数据闭环高可用。

---

一、 核心痛点与“智能双轨”设计拓扑

在传统的 Headless 部署中，我们通常将 Astro 部署在 Cloudflare Pages 等托管平台上。但 Cloudflare 在中国大陆部分地区的访问速度并不理想。如果全站强制走 CDN，国内体验会大幅降级；如果全站走国内服务器，又无法享受全球边缘缓存的红利。

为此，我们设计了“智能双轨分流（Split-Routing）”架构：

• 🇨🇳 中国大陆访客：通过智能 DNS 直接解析到高带宽的 边缘专线服务器（Edge Node），直连读取本地预编译好的静态 HTML 目录，享受毫秒级渲染。
• 🌐 海外访客：通过智能 DNS CNAME 引导至 Cloudflare Pages 边缘网络，享受 10ms 级别的全球就近静态秒开。
• 🔄 动态穿透回源：对于登录后台、多媒体加载（/wp-content）、REST API（/wp-json）等动态请求，无论国内外，统一穿透代理回 WordPress 源站服务器（Origin Server）。

---

二、 智能双轨分流实践步骤

第一步：智能 DNS 解析配置

这是分流方案的基石。在域名解析控制台（如阿里云解析 DNS 或 DNSPod）中，针对同一域名配置不同的流量走向：

💡 避坑指南： 部分 DNS 厂商支持对根域名 @ 同时添加 A 记录和 CNAME 记录。在实际解析中，解析商会在后台进行“CNAME 扁平化”优化，这不会产生冲突，也不会影响您的邮件解析 MX 记录。

第二步：Cloudflare Pages 边缘中间件配置

为了让海外访客在访问 yourdomain.com 时能够无缝穿透后台，我们必须在 Cloudflare Pages 的根目录下创建一个 functions/_middleware.js 边缘函数。这可以完美解决后台重定向、登录态同步及媒体拉取问题。

我们采用了一套“万无一失”的自动正则匹配逻辑：

export async function onRequest(context) {
  const url = new URL(context.request.url);
  const path = url.pathname;

  // 1. 定义非 WordPress 开头，但需要透传回源站的自定义独立物理目录 (如：纪念日、工具等)
  const dynamicPaths = [
    '/kms',
    '/donate',
    '/custom-app'
  ];

  // 2. 核心匹配逻辑：
  // - 凡是路径以 '/wp-' 开头的（无缝涵盖 /wp-admin, /wp-content, /wp-json, /wp-login.php, /wp-comments-post.php 等）
  // - 凡是路径以 '.php' 结尾的（涵盖 xmlrpc.php, index.php 等所有 PHP 脚本执行）
  // - 匹配上面定义的自定义动态路径
  const isDynamic = 
    path.startsWith('/wp-') || 
    path.endsWith('.php') || 
    dynamicPaths.some(p => path.startsWith(p));

  if (isDynamic) {
    // 穿透代理：将请求隐式转发给回源通道（使用 HTTP 80 避免 SSL 双重握手和 526 证书校验死锁）
    url.protocol = 'http:';
    url.hostname = 'origin-api.yourdomain.com';
    
    const modifiedHeaders = new Headers(context.request.headers);
    modifiedHeaders.set('Host', 'yourdomain.com'); // 锁定 Host 头，确保 WordPress 正确匹配虚拟主机
    
    const modifiedRequest = new Request(url, {
      method: context.request.method,
      headers: modifiedHeaders,
      body: context.request.body,
      redirect: 'manual' // 保持手动重定向，让浏览器自行处理后续跳转
    });
    
    return fetch(modifiedRequest);
  }

  // 如果是普通静态页面，直接向下传递，由 Cloudflare Pages 本地静态缓存秒级吐出
  return context.next();
}

第三步：边缘专线 Nginx 配置

在边缘服务器（国内直连节点）上，我们需要编写 Nginx 配置，使其既能充当 Astro 本地编译的静态服务器，又能承担动态回源的反代网闸。

# 1. Astro 静态分发
location / {
    root /www/wwwroot/yourdomain.com/dist;
    index index.html;
    
    # 支持 WordPress 后台“预览”功能
    if ($args ~* "preview=true|p=") {
        rewrite ^(.*)$ /__wp_preview__$1 last;
    }
    
    try_files $uri $uri/index.html $uri/ =404;
}

# 2. 后端预览专用反代
location ~ ^/__wp_preview__(.*) {
    internal;
    proxy_pass https://10.0.0.5$1$is_args$args; # WordPress 源站内网IP/VPN-IP
    proxy_set_header Host yourdomain.com;
    proxy_ssl_server_name on;
    proxy_ssl_name yourdomain.com;
    proxy_ssl_verify off;
}

# 3. 动态穿透与多媒体资源回源
location ~* ^/(wp-admin|wp-includes|wp-json|wp-content|wp-login.php|xmlrpc.php) {
    proxy_pass https://10.0.0.5; # 反代至 WordPress 源站
    proxy_set_header Host yourdomain.com;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_ssl_server_name on;
    proxy_ssl_name yourdomain.com;
    proxy_ssl_verify off;

    # 对于媒体库静态资源，可以在边缘 Nginx 配置强缓存
    if ($uri ~* \.(gif|jpg|jpeg|png|bmp|webp|svg|ico)$) {
        expires 7d;
        add_header X-Cache "MEDIA-HIT";
    }
}

第四步：一键发布、双轨自动部署 Pipeline

为了让两地（Cloudflare Pages 边缘静态和边缘专线 Nginx）数据时刻保持一致，我们必须实现“一地编译，多端部署”。

我们可以在边缘服务器上部署一个极简的 Node.js 自动化 Webhook（监听在内部端口如 9000），并在 WordPress 插件（如过渡状态钩子 transition_post_status）中监听文章发布事件。当您点击“发布”时：

1. WordPress 触发 Webhook ➜ 边缘服务器拉取最新代码并执行 npm run build（耗时约 15 秒）。
2. 编译完成后，静态 HTML 直接进入边缘专线的 Nginx 根目录中（国内更新瞬间完成）。
3. 脚本末尾追加 npx wrangler pages deploy dist，将增量静态文件秒级推送到 Cloudflare Pages（海外部署秒级完成）。

---

三、 架构优势总结

这套方案运行平稳后，网站架构会呈现出极强的稳定性和美感：

1. 零延迟跳转闪烁： 所有的动态/回源请求在边缘就已经完成了隐式转发，访客浏览器的地址栏不会发生 302 重定向式的域名跳转，视觉效果浑然一体、极度丝滑。
2. 坚不可摧的安全壁垒： 真正的 WordPress 源站（数据库、核心 PHP）可以完全隐藏在内网或专用 VPN（如 Tailscale）之后，不向公网暴露任何直连入口，天然免受各类针对 WP 的恶意漏洞扫描。
3. 极致性价比： 完全免费地让非托管域名绑定在了 Cloudflare Pages 项目自定义域上，解决了域名托管迁移的痛点，零资金投入，直接白嫖了全球最顶级的边缘算力与静态加速。

至此，一个“面向未来的高性能无头博客”正式合拢。你可以专注在温润平静、充满艺术气息的内容创作中，而所有的访问加速与数据同步，都已在默默运转的黑科技静谧流淌。