反向代理设置

创建 Worker

创建一个 Cloudflare Worker，拦截发往文档子路径的请求并代理到 Fern：

1
const SUBPATH = "/docs";
2
const FERN_HOST = "mydomain.com";
3
4
export default {
5
  async fetch(request) {
6
    const url = new URL(request.url);
7
8
    if (
9
      url.pathname !== SUBPATH &&
10
      !url.pathname.startsWith(`${SUBPATH}/`)
11
    ) {
12
      return new Response("Not found", { status: 404 });
13
    }
14
15
    const upstreamUrl = new URL(request.url);
16
    upstreamUrl.protocol = "https:";
17
    upstreamUrl.hostname = "app.buildwithfern.com";
18
    upstreamUrl.port = "";
19
20
    const proxiedRequest = new Request(upstreamUrl, request);
21
    proxiedRequest.headers.set("x-fern-host", FERN_HOST);
22
23
    return fetch(proxiedRequest);
24
  },
25
};

将 SUBPATH 和 FERN_HOST 替换为您的子路径和裸域名。

将 Worker 附加到路由

在 Cloudflare 控制台的 Workers Routes 下，将 Worker 附加到路由模式，如 mydomain.com/docs/*。

检查冲突的缓存规则

Worker 会转发 Fern 的 Cache-Control 头，因此缓存自动生效。在 Cloudflare 控制台中确认没有 Page Rule 或 Cache Rule 为 /docs* 设置了”Cache Level: Cache Everything” — 如果存在，请移除或使用”Cache Level: Bypass”覆盖。

添加 Fern 源站

在 CloudFront 分配中，前往 Origins 并创建新源站：

在 Add custom header 下添加：

将 mydomain.com 替换为您的裸域名（不含子路径）。

为文档路径创建缓存行为

前往 Behaviors 并创建新行为：

AllViewerExceptHostHeader 将所有查看器头、查询字符串和 Cookie 转发到源站，同时让 CloudFront 将 Host 头设置为 app.buildwithfern.com。这是必需的 — Fern 源站使用 Host 头进行路由，并拒绝不识别的主机名请求。

验证行为顺序

CloudFront 按顺序评估行为。确保 /docs* 行为位于默认（*）行为之上，以便文档请求被路由到 Fern 源站而非您的主站点。

添加重写规则

在 netlify.toml（或 _redirects）中：

1
[[redirects]]
2
  from = "/docs/*"
3
  to = "https://app.buildwithfern.com/docs/:splat"
4
  status = 200
5
  force = true
6
7
  [redirects.headers]
8
    x-fern-host = "mydomain.com"

为文档路径禁用速率限制

Fern 通过并发请求预热页面缓存来重新验证文档站点。Netlify 的流量规则可能将此视为恶意流量并阻止请求，导致重新验证失败。

如果您在 Netlify 控制台的 Security > Traffic rules 下启用了速率限制，请添加规则将文档子路径（/docs/*）排除在速率限制之外。

检查代理超时

Fern 的重新验证端点在预热页面缓存时流式传输长时间运行的响应。Netlify 将代理重写请求限制为 26 秒，对于超过几百页的站点，这可能在预热完成前终止流。

如果重新验证持续失败并显示”terminated”状态，此超时很可能是原因。请联系 Netlify 支持请求增加站点超时，或联系 Fern 支持获取替代预热方案。

添加带转换的路由

使用带转换规则的路由在一步中重写路径并设置 x-fern-host：

1
{
2
  "$schema": "https://openapi.vercel.sh/vercel.json",
3
  "routes": [
4
    {
5
      "src": "/docs(/.*)?",
6
      "dest": "https://app.buildwithfern.com/docs$1",
7
      "transforms": [
8
        {
9
          "type": "request.headers",
10
          "op": "set",
11
          "target": { "key": "x-fern-host" },
12
          "args": "mydomain.com"
13
        }
14
      ]
15
    }
16
  ]
17
}

添加 location 块

1
location /docs {
2
    proxy_pass https://app.buildwithfern.com;
3
    proxy_set_header Host app.buildwithfern.com;
4
    proxy_set_header x-fern-host mydomain.com;
5
    proxy_set_header X-Real-IP $remote_addr;
6
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
7
    proxy_set_header X-Forwarded-Proto $scheme;
8
    proxy_ssl_server_name on;
9
10
    # 防止 Brotli 响应的编码问题
11
    proxy_set_header Accept-Encoding "gzip, deflate";
12
13
    # 不缓存 HTML
14
    proxy_no_cache 1;
15
    proxy_cache_bypass 1;
16
    add_header Cache-Control "public, max-age=0, must-revalidate" always;
17
}

添加路由规则

在 Site Delivery 或 Ion 属性中，添加匹配路径 /docs* 的规则：

• Origin Server：app.buildwithfern.com
• Forward Host Header：Origin Hostname

添加 Modify Outgoing Request Header 行为：

在规则上禁用缓存

在同一规则中添加 Caching 行为：

或者，将 Honor Origin Cache-Control 设置为 Yes，让 Akamai 遵守 Fern 的 Cache-Control: public, max-age=0, must-revalidate 头。

添加到 Caddyfile

mydomain.com {
    handle /docs* {
        reverse_proxy https://app.buildwithfern.com {
            header_up Host app.buildwithfern.com
            header_up x-fern-host mydomain.com
        }
    }
}