要使用 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/* - 用于域名验证
  • /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 发行版页面，突出显示 “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”选项卡。
一个突出显示“Origins”选项卡的 CloudFront 发行版。
  1. 找到与你主域名相对应的预发布（staging）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”输入框被高亮显示。
此时，你应当有两个 Origins：一个为 [SUBDOMAIN].mintlify.app，另一个为你的预发布 URL。
CloudFront 的“Origins”页面，包含两个 origins：一个用于 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 证书验证必需

​
你的自定义子路径

使用你选择的子路径创建一个行为，并在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. 点击 Save changes。

​
检查行为是否正确配置

如果你按照上述步骤操作，行为应如下所示：
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 官方指南：将 Amazon Route 53 配置为将流量路由到 CloudFront 分配
  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 小时。如果你的子域名未能立即生效，请先耐心等待再进行排查。