使用 Cloudflare Workers 在子路径下部署
通过 Cloudflare Workers 将你的 Mintlify 文档部署到域名的子路径，包含分步设置和 DNS 配置说明。
要使用 Cloudflare 将文档托管在诸如 yoursite.com/docs 这样的子路径下，你必须创建并配置一个 Cloudflare Worker。
在开始之前，你需要一个 Cloudflare 账号和一个域名（可以在 Cloudflare 内或外进行管理）。
- 在控制台中前往 Custom domain setup 页面。
- 启用 Host at 开关并输入你的基础路径。例如
/docs或/help。 - 输入你的域名。
- 输入你的基础路径。
- 选择 Add domain。
控制台会显示一个已填入你的子域、域名和基础路径的 Cloudflare Worker 脚本。请在 配置路由 步骤中使用该脚本，而不必手动替换示例脚本中的占位值。
如果你尚未创建，请按照 Cloudflare Workers 入门指南创建一个 Cloudflare Worker。
如果你的 DNS 提供商是 Cloudflare，请为该 CNAME 记录关闭代理，以避免潜在的配置问题。
如果你在 Vercel 部署中使用 Cloudflare 作为代理，必须确保配置正确，以避免与 Vercel 的 domain 验证和 SSL 证书签发发生冲突。
错误的代理配置可能会阻止 Vercel 为 Let’s Encrypt SSL 证书进行签发，并导致 domain 验证失败。
你的 Cloudflare Worker 必须允许以下特定路径的流量通过，且不能阻止或重定向：
/.well-known/acme-challenge/*- 用于 Let’s Encrypt 证书验证，必需/.well-known/vercel/*- 用于 Vercel domain 验证，必需
虽然 Cloudflare 会自动处理许多验证规则，但创建额外的自定义规则可能会无意中拦截这些关键流量。
请确保你的 Worker 将 Host 头设置为你的 <subdomain>.mintlify.site 目标（如示例脚本所示），而不是直接透传原始请求的 Host 头。错误的 Host 头会导致验证请求失败。
在你的 Cloudflare 控制台中，选择 Edit Code，并添加 Custom domain setup 页面中已填入你自己值的脚本，或复制以下示例脚本。有关编辑 Worker 的更多信息，请参阅 Cloudflare 文档。
如果使用示例脚本，请将 [SUBDOMAIN] 替换为你唯一的子域，将 [YOUR_DOMAIN] 替换为你网站的基础 URL；如果希望使用不同的子路径，则将 /docs 替换为你想要的子路径。
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 子路径、Mintlify 静态资源或 API 路径
if (
/^\/docs/.test(urlObject.pathname) ||
/^\/mintlify-assets\//.test(urlObject.pathname) ||
/^\/_mintlify\//.test(urlObject.pathname)
) {
// 然后代理到 Mintlify
const DOCS_URL = "[SUBDOMAIN].mintlify.site";
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);
}
}除了你的子路径外，你的 Worker 还必须代理 /mintlify-assets/*（用于提供文档的 CSS、JavaScript 和 favicon）以及 /_mintlify/*（用于处理 API playground 请求）。
如果你使用路由模式而非自定义域将流量路由到 Worker，请在子路径路由的基础上，为 yoursite.com/mintlify-assets/* 和 yoursite.com/_mintlify/* 添加路由。这些路径必须源自你域名的根路径，而不是子路径。
点击 Deploy，然后等待更改生效。
部署完更改后，你的文档通常会在几分钟内在你的子路径下可用。如果你的设置涉及 DNS 变更，传播可能需要 1–4 小时，极少数情况下最长可达 48 小时。如果你的文档没有立即可用，请先耐心等待再进行故障排查。
在部署代码后，测试你的 Worker，确保它正确路由到你的 Mintlify 文档。
- 使用 Worker 的预览 URL 进行测试：
your-worker.your-subdomain.workers.dev/docs - 确认该 Worker 能正确路由到你的 Mintlify 文档和你的网站。
- 在你的 Cloudflare 控制台中，进入你的 Worker。
- 前往 Settings > Domains & Routes > Add > Custom Domain。
- 添加你的 domain。
我们建议同时添加带有 www. 和不带有 www. 的 domain。
有关更多信息，请参阅 Cloudflare 文档中的 Add a custom domain。
如果你的 domain 已经指向其他服务，你必须移除现有的 DNS 记录。你的 Cloudflare Worker 必须配置为接管该 domain 的全部流量。
- 删除该 domain 的现有 DNS 记录。更多信息请参阅 Cloudflare 文档：Delete DNS records。
- 返回你的 Worker，添加你的自定义 domain。
如果你使用 Webflow 托管主站点，并希望在同一 domain 的 /docs 路径下提供 Mintlify 文档，你需要通过 Cloudflare Workers 配置自定义路由，将所有非 docs 流量代理到你的主站点。
在部署此 Worker 之前，请确保你的主站点已配置为某个落地页，否则访问你主站点的访客可能会看到错误。
- 在 Webflow 中，为你的主站点设置一个落地页，例如
landing.yoursite.com。这是访客访问你的网站时首先看到的页面。 - 将你的主站点部署到该落地页。这样可以确保在你配置 Worker 的过程中，主站点依然可访问。
- 为避免冲突，将主站点中的任何绝对 URL 更新为相对路径。
- 在 Cloudflare 中选择 Edit Code，并将以下脚本添加到你的 Worker 代码中。
[SUBDOMAIN] 替换为你唯一的子域，将 [YOUR_DOMAIN] 替换为你网站的基础 URL，将 [LANDING_DOMAIN] 替换为你的落地页 URL，如有需要，将 /docs 替换为你想要的其他子路径。 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 子路径、Mintlify 静态资源或 API 路径
if (
/^\/docs/.test(urlObject.pathname) ||
/^\/mintlify-assets\//.test(urlObject.pathname) ||
/^\/_mintlify\//.test(urlObject.pathname)
) {
// 代理到 Mintlify
const DOCS_URL = "[SUBDOMAIN].mintlify.site";
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);
}
}- 选择 Deploy，等待更改完成传播。
部署完更改后，你的文档通常会在几分钟内在你的子路径下可用。如果你的设置涉及 DNS 变更，传播可能需要 1–4 小时，极少数情况下最长可达 48 小时。如果你的文档没有立即可用，请先耐心等待再进行故障排查。