> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-add-hello-world-quickstart-48843.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare

> 使用 Cloudflare Workers 在自定义子路径下托管文档

要在 Cloudflare 上将文档托管到自定义子路径（如 `yoursite.com/docs`），你需要创建并配置一个 Cloudflare Worker。

<Info>
  开始前，你需要一个 Cloudflare 账户和一个域名（可由 Cloudflare 托管或在其他服务商托管）。
</Info>

<div id="repository-structure">
  ## 仓库结构
</div>

必须在仓库中按所选子路径结构组织文档文件。比如，如果希望文档位于 `yoursite.com/docs`，则需创建一个 `docs/` 目录，并将所有文档文件置于其中。

<div id="set-up-a-cloudflare-worker">
  ## 设置 Cloudflare Worker
</div>

如果你还没有创建，请按照[Cloudflare Workers 入门指南](https://developers.cloudflare.com/workers/get-started/dashboard/)创建一个 Cloudflare Worker。

<Warning>
  如果你的 DNS 提供商是 Cloudflare，请不要为该 CNAME 记录启用代理。
</Warning>

<div id="proxies-with-vercel-deployments">
  ### 在 Vercel 部署中使用代理
</div>

如果你在 Vercel 部署中使用 Cloudflare 作为代理，务必正确配置，以避免与 Vercel 的域名验证和 SSL 证书签发发生冲突。

错误的代理配置可能会导致 Vercel 无法为 Let's Encrypt 签发 SSL 证书，并引发域名验证失败。

<div id="required-path-allowlist">
  #### 必需的路径白名单
</div>

你的 Cloudflare Worker 必须允许以下特定路径的流量通过，且不得拦截或重定向：

* `/.well-known/acme-challenge/*` - Let's Encrypt 证书验证所必需
* `/.well-known/vercel/*` - Vercel 域名验证所必需

尽管 Cloudflare 会自动处理许多验证规则，但新增自定义规则可能会无意间阻止这些关键流量。

<div id="header-forwarding-requirements">
  #### 头部转发要求
</div>

请确保在 Worker 配置中正确转发 `HOST` 头部。若未正确转发头部，验证请求将会失败。

<div id="configure-routing">
  ### 配置路由
</div>

在 Cloudflare 控制台中，选择 **Edit Code**，将以下脚本添加到你的 Worker 代码中。有关编辑 Worker 的更多信息，请参阅 [Cloudflare 文档](https://developers.cloudflare.com/workers-ai/get-started/dashboard/#development)。

<Tip>
  请将 `[SUBDOMAIN]` 替换为你的唯一子域名，将 `[YOUR_DOMAIN]` 替换为你网站的基础 URL；如有需要，将 `/docs` 替换为你期望的子路径。
</Tip>

```javascript
addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  try {
    const urlObject = new URL(request.url);
    
    // 如果请求路径是用于 Vercel 验证的地址，则放行
    if (urlObject.pathname.startsWith('/.well-known/')) {
      return await fetch(request);
    }
    
    // 如果请求指向 docs 子目录
    if (/^\/docs/.test(urlObject.pathname)) {
      // 则代理到 Mintlify
      const DOCS_URL = "[SUBDOMAIN].mintlify.dev";
      const CUSTOM_URL = "[YOUR_DOMAIN]";

      let url = new URL(request.url);
      url.hostname = DOCS_URL;

      let proxyRequest = new Request(url, request);

      proxyRequest.headers.set("Host", DOCS_URL);
      proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
      proxyRequest.headers.set("X-Forwarded-Proto", "https");
      // 如果部署在 Vercel 上，保留客户端 IP
      proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));

      return await fetch(proxyRequest);
    }
  } catch (error) {
    // 如果未命中任何规则，则按常规方式处理请求
    return await fetch(request);
  }
}
```

选择**Deploy**，然后等待更改生效。

<Note>
  配置 DNS 后，自定义子域名通常会在几分钟内生效。DNS 传播有时可能需要 1–4 小时，极少数情况下最多可达 48 小时。如果你的子域名未能立即生效，请先耐心等待，再进行排查。
</Note>

<div id="test-your-worker">
  ### 测试你的 Worker
</div>

部署代码后，测试你的 Worker 以确保它能够正确路由到你的 Mintlify 文档。

1. 使用 Worker 的预览 URL 进行测试：`your-worker.your-subdomain.workers.dev/docs`
2. 确认 Worker 能正确路由到你的 Mintlify 文档和你的网站。

<div id="add-custom-domain">
  ### 添加自定义域名
</div>

1. 在你的 [Cloudflare 控制台](https://dash.cloudflare.com/)中，进入你的 Worker。
2. 依次前往 **Settings > Domains & Routes > Add > Custom Domain**。
3. 添加你的域名。

<Tip>
  建议同时添加带有 `www.` 和不带 `www.` 的域名。
</Tip>

更多信息请参阅 Cloudflare 文档：[添加自定义域名](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#add-a-custom-domain)。

<div id="resolve-dns-conflicts">
  ### 解决 DNS 冲突
</div>

如果你的域名已指向其他服务，你必须删除现有的 DNS 记录。你的 Cloudflare Worker 必须配置为接管该域名的全部流量。

1. 删除你域名的现有 DNS 记录。更多信息请参阅 Cloudflare 文档：[删除 DNS 记录](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records)。
2. 返回到你的 Worker，并添加你的自定义域名。

<div id="webflow-custom-routing">
  ## Webflow 自定义路由
</div>

如果你使用 Webflow 托管主站，并希望在同一域名下的 `/docs` 提供 Mintlify 文档，你需要通过 Cloudflare Workers 配置自定义路由，将所有非文档流量代理到主站。

<Warning>
  在部署该 Worker 之前，请确保你的主站已设置为着陆页，否则访问主站的访客将会遇到错误。
</Warning>

1. 在 Webflow 中，为主站设置一个着陆页，例如 `landing.yoursite.com`。当访客访问你的网站时，会看到此页面。
2. 将主站部署到该着陆页。这样可确保在配置 Worker 的同时，主站仍可访问。
3. 为避免冲突，将主站中的任何绝对 URL 改为相对路径。
4. 在 Cloudflare 中，选择 **Edit Code**，并将以下脚本添加到你的 Worker 代码中。

<Tip> 将 `[SUBDOMAIN]` 替换为你的唯一子域名，将 `[YOUR_DOMAIN]` 替换为你网站的基础 URL，将 `[LANDING_DOMAIN]` 替换为你的着陆页 URL；如有需要，可将 `/docs` 替换为你期望的子路径。 </Tip>

```javascript
  addEventListener("fetch", (event) => {
  event.respondWith(handleRequest(event.request));
  });
  async function handleRequest(request) {
  try {
    const urlObject = new URL(request.url);
    
    // 若请求指向 Vercel 的验证路径，则直接放行
    if (urlObject.pathname.startsWith('/.well-known/')) {
      return await fetch(request);
    }
    
    // 若请求指向 docs 子目录
    if (/^\/docs/.test(urlObject.pathname)) {
      // 代理到 Mintlify
      const DOCS_URL = "[SUBDOMAIN].mintlify.dev";
      const CUSTOM_URL = "[YOUR_DOMAIN]";
      let url = new URL(request.url);
      url.hostname = DOCS_URL;
      let proxyRequest = new Request(url, request);
      proxyRequest.headers.set("Host", DOCS_URL);
      proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
      proxyRequest.headers.set("X-Forwarded-Proto", "https");
      // 若部署在 Vercel，上保留客户端 IP
      proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
      return await fetch(proxyRequest);
    }
    // 其余请求全部路由到主站
    const MAIN_SITE_URL = "[LANDING_DOMAIN]";
    if (MAIN_SITE_URL && MAIN_SITE_URL !== "[LANDING_DOMAIN]") {
      let mainSiteUrl = new URL(request.url);
      mainSiteUrl.hostname = MAIN_SITE_URL;
      return await fetch(mainSiteUrl, {
        method: request.method,
        headers: request.headers,
        body: request.body
      });
    }
  } catch (error) {
    // 若无匹配逻辑，按常规方式处理请求
    return await fetch(request);
  }
  }
```

5. 选择 **Deploy**，并等待更改生效。

<Note>
  配置 DNS 后，自定义子域名通常会在几分钟内生效。DNS 传播有时可能需要 1–4 小时，极少数情况下最多可达 48 小时。如果你的子域名未能立即生效，请先耐心等待，再进行排查。
</Note>