跳转到主要内容
要使用 AWS Route 53 和 CloudFront 将文档托管在自定义子路径（例如 yoursite.com/docs），你需要在 DNS（域名系统）提供商处配置记录指向你的 CloudFront 分配（Distribution）。

​
存储库结构

为匹配所选的子路径结构，你需要在存储库中组织文档文件。比如，如果你希望文档位于 yoursite.com/docs，应创建一个包含所有文档文件的 docs/ 目录。

​
概览（高层）

将流量路由到以下路径，并将缓存策略设置为 CachingDisabled：
  • /.well-known/acme-challenge/* - 用于 Let’s Encrypt 证书验证（必需）
  • /.well-known/vercel/* - 用于 domain 验证（必需）
  • /docs/* - 用于子路径路由（必需）
  • /docs/ - 用于子路径路由（必需）
将流量路由到以下路径，并将缓存策略设置为 CachingEnabled：
  • /mintlify-assets/_next/static/*
  • Default (*) - 你的网站着陆页
所有 Behaviors 的 origin request policy 必须为 AllViewerExceptHostHeader。 CloudFront “Behaviors” 页面包含 4 个行为：/docs/*、/docs、Default 和 /.well-known/*。

​
创建 CloudFront 分配

  1. 在 AWS 控制台中进入 CloudFront。
  2. 选择 Create distribution。
CloudFront Distributions 页面，突出显示“Create distribution”按钮。
  1. 在 Origin domain 中输入 [SUBDOMAIN].mintlify.dev，其中 [SUBDOMAIN] 是你项目的唯一子域。
CloudFront “Create distribution” 页面，显示 “acme.mintlify.dev” 作为 origin domain。
  1. 在 “Web Application Firewall (WAF)” 中，启用安全防护。
Web Application Firewall (WAF) 选项，已选择 “Enable security protections”。
  1. 其余设置保持默认。
  2. 选择 Create distribution。

​
添加默认 Origin

  1. 创建分发后，前往 “Origins” 标签页。
一个 CloudFront 分发，已高亮显示 “Origins” 标签页。
  1. 找到与你主域名对应的预发布环境 URL。具体取决于落地页的托管方式，可能差异较大。例如，Mintlify 的预发布 URL 是 mintlify-landing-page.vercel.app。
如果你的落地页托管在 Webflow，请使用 Webflow 的预发布 URL，通常以 .webflow.io 结尾。如果你使用 Vercel，请使用每个项目都会提供的 .vercel.app 域名。
  1. 新建一个 Origin，并将你的预发布 URL 填入 “Origin domain”。
CloudFront 的 “Create origin” 页面，已高亮显示 “Origin domain” 输入框。
此时，你应当有两个 Origin：一个是 [SUBDOMAIN].mintlify.app，另一个是你的预发布 URL。
CloudFront 的 “Origins” 页面包含两个 Origin：一个用于 mintlify，另一个用于 mintlify-landing-page。

​
设置行为

CloudFront 的行为用于控制子路径逻辑。总体上，我们希望实现以下逻辑：
  • 如果用户访问你的自定义子路径，跳转到 [SUBDOMAIN].mintlify.dev。
  • 如果用户访问其他任意页面，跳转到当前着陆页。
  1. 前往 CloudFront 分配的 “Behaviors” 标签页。
CloudFront 的 "Behaviors" 标签页（已高亮）。
  1. 点击 Create behavior 按钮，并创建如下行为。

​
/.well-known/*

为 Vercel 域名验证路径创建一个 Path pattern 为 /.well-known/* 的行为，并将 Origin and origin groups 设置为你的文档 URL。 在 “Cache policy” 中选择 CachingDisabled，以确保这些验证请求不被缓存，能够直接通过。
CloudFront「Create behavior」页面，"Path pattern" 为 "/.well-known/*"，且 "Origin and origin groups" 指向预发布环境的 URL。
如果 .well-known/* 过于宽泛，至少可以为 Vercel 将其细分为 2 个行为：
  • /.well-known/vercel/* - Vercel 域名验证所必需
  • /.well-known/acme-challenge/* - Let’s Encrypt 证书验证所必需

​
自定义子路径

创建一个行为（Behavior），将你选择的子路径填入 Path pattern，例如 /docs，并将 Origin and origin groups 指向 .mintlify.dev 的 URL（此处为 acme.mintlify.dev）。
  • 将 “Cache policy” 设置为 CachingOptimized。
  • 将 “Origin request policy” 设置为 AllViewerExceptHostHeader。
  • 将 “Viewer Protocol Policy” 设置为 Redirect HTTP to HTTPS。
CloudFront “Create behavior” 页面，其中 “Path pattern”为 “/docs/*”，且 “Origin and origin groups” 指向 acme.mintlify.dev 的 URL。

​
你的自定义带通配符的子路径

创建一个行为，将你选择的子路径加上 /* 作为 Path pattern（例如 /docs/*），并将 Origin and origin groups 指向相同的 .mintlify.dev URL。 除 Path pattern 外，这些设置应与基础子路径的行为完全一致。
  • 将“Cache policy”设置为 CachingOptimized。
  • 将“Origin request policy”设置为 AllViewerExceptHostHeader。
  • 将“Viewer protocol policy”设置为 Redirect HTTP to HTTPS

​
/mintlify-assets/_next/static/*

  • 将“Cache policy”设置为 CachingOptimized
  • 将“Origin request policy”设置为 AllViewerExceptHostHeader
  • 将“Viewer protocol policy”设置为 Redirect HTTP to HTTPS

​
Default (*)

最后，我们将编辑 Default (*) 行为。
已选择 “Default (*)” 行为并突出显示 Edit 按钮的 CloudFront 分配。
  1. 将默认行为的 Origin and origin groups 更改为预发布环境的 URL（本例为 mintlify-landing-page.vercel.app）。
CloudFront 的 “Edit behavior” 页面，突出显示 “Origin and origin groups” 输入字段。
  1. 选择 保存更改。

​
确认已正确配置 Behaviors

如果你按照上述步骤操作，Behaviors 应如下所示：
CloudFront「Behaviors」页面，包含 4 个行为：/docs/*、/docs、Default 和 /.well-known/*。

​
预览分发

现在可以前往“General”标签页并访问 Distribution domain name 的 URL，测试分发是否已正确配置。
CloudFront “General” 标签页，已高亮显示 “Distribution domain name” 的 URL。
所有页面应指向你的主登录页；如果在该 URL 后追加你选择的子路径（例如 /docs），应会跳转到你的 Mintlify 文档实例。

​
连接 Route53

现在，我们将把 CloudFront 分配（Distribution）的功能接入你的主域名。
本节你也可以参考 AWS 官方指南：Configuring Amazon Route 53 to route traffic to a CloudFront distribution
  1. 在 AWS 控制台中进入 Route53。
  2. 进入主域名的 “Hosted zone”。
  3. 选择 Create record。
Route 53「Records」页面，突出显示「Create record」按钮。
  1. 打开 Alias，然后在 Route traffic to 中选择 Alias to CloudFront distribution 选项。
Route 53「Create record」页面，突出显示「Alias」开关与「Route traffic to」菜单。
  1. 选择 Create records。
如果当前存在 A 记录，可能需要先将其移除。
你的文档现已在主域名的所选子路径上线。
配置好 DNS（域名系统）后，自定义子域通常会在几分钟内生效。DNS 传播有时可能需要 1–4 小时，极少数情况下可达 48 小时。如果您的子域未能立即生效，请先耐心等待，再进行故障排查。
⌘I