跳转到主要内容
要使用 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 分配（Distribution）

  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)” 中启用安全防护（Enable security protections）。
Web Application Firewall (WAF) 选项，已选择 “Enable security protections”。
  1. 其余设置保持默认。
  2. 点击 Create distribution。

​
添加默认 Origin

  1. 创建发行版后，前往“Origins”选项卡。
突出显示“Origins”选项卡的 CloudFront 发行版。
  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”输入框。
此时你应当有两个 Origins：一个为 [SUBDOMAIN].mintlify.app，另一个为你的预发布 URL。
CloudFront 的“Origins”页面，包含两个 origins：一个用于 mintlify，另一个用于 mintlify-landing-page。

​
设置行为

CloudFront 中的行为（Behaviors）用于控制子路径逻辑。总体上，我们希望实现以下逻辑：
  • 如果用户访问你的自定义子路径，跳转至 [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/* 过于宽泛，可以至少细分为 2 个行为以适配 Vercel：
  • /.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。

​
检查行为配置是否正确

如果你按上述步骤进行配置，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 分发的功能接入到你的主域名。
本节你也可以参考 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 小时。如果你的子域名未能立即生效，请先耐心等待，再进行排查。