跳转到主要内容
将你的文档托管在自己的域名（例如 docs.example.com）上，或托管在你域名的某个子路径下（例如 example.com/docs）。 要在自定义域名上托管你的文档：
  1. 在控制台中添加你的域名。
  2. 在你的域名提供商处配置 DNS 设置。
  3. 等待 DNS 传播完成，并自动签发 TLS 证书。

​
选择托管文档的位置

你可以将文档托管在域名的根路径、子域名或子路径下。 域名或子域名：将文档托管在类似 example.com 的域名或类似 docs.example.com 的子域名上。Mintlify 会处理该域名或子域名的所有流量。若要在不带子域名的域名上托管，你的 DNS 提供商必须支持 CNAME flattening 或 ALIAS 记录。请参见 顶级域名。 子路径：将文档托管在你域名的某个路径下，例如 example.com/docs。添加域名时启用 Host at 开关并输入你的基础路径。流量到达 Mintlify 的方式取决于你的 DNS：
  • 如果你域名的 DNS 指向 Mintlify，Mintlify 会在你的子路径下提供文档服务。仅在该域名不承载其他内容、且 Mintlify 可以接收该域名上的所有路径时，才将域名指向 Mintlify。
  • 如果你的域名上还运行着其他站点，你的应用或 CDN 会继续接收域名的流量，并只将你的子路径代理到 Mintlify。
已启用身份验证的文档不支持子路径托管。

​
添加自定义域名

  1. 在控制台中前往 Custom domain setup 页面。
  2. 若要在子路径下托管，启用 Host at 开关并输入你的基础路径，例如 /docs。
  3. 输入你的域名。例如 docs.example.com 或 example.com。
  4. 选择 Add domain。
如果你的域名流量指向 Mintlify，控制台将显示需要在你的域名提供商处添加的 DNS 记录。 如果你只是将子路径代理到 Mintlify，控制台会改为显示反向代理的设置指南。请按照适用于你提供商的指南操作，并参阅 在子路径下托管文档 获取更多信息。

​
基础路径要求

只要满足以下要求，你的基础路径可以是任意路径：
  • 以 / 开头，不包含空格、query 字符串或哈希。
  • 长度最多 128 个字符。
  • 不是 Mintlify 保留的路径：/_next、/_mintlify、/_sites、/_live-preview、/api、/login、/logout、/mcp、/feedback、/openapi-specs.download、/llms.txt、/llms-full.txt、/sitemap.xml、/robots.txt、/skill.md 和 /.well-known。

​
修改你的基础路径

当你修改基础路径或子路径时，Mintlify 会重新构建并重新部署你的站点。在部署完成之前，站点仍会在当前路径下保持可用，然后流量会切换到新路径。如果部署失败，站点会继续从当前路径提供服务，你可以在控制台中重试变更。

​
配置你的 DNS

不同的域名提供商添加 DNS 记录的方式各不相同。请参阅你的域名提供商文档以获取具体说明。
  1. 在你的域名提供商网站上，前往该域名的 DNS 设置。
  2. 创建控制台中显示的 DNS 记录。
控制台会显示用于验证的 TXT 记录以及一条 CNAME 记录： 
TXT | _acme-challenge.<你的域名> | <控制台中显示的值>
TXT | _cf-custom-hostname.<你的域名> | <控制台中显示的值>
CNAME | <你的域名> | cname.mintlify.builders
_acme-challenge 记录用于授权 Let’s Encrypt 为你的域名签发 TLS 证书，_cf-custom-hostname 记录用于验证你对该域名的控制权。
请先添加 TXT 记录。在两条验证 TXT 记录都在控制台中显示为已验证之前，请勿添加或更改 CNAME。当 DNS 正确时，每条记录都会显示绿色对勾。控制台会先验证 TXT 记录，证书才能完成签发。过早切换 CNAME 通常会导致 HTTPS 中断，直到签发完成。如果你在迁移现有域名并希望零停机切换，请先发布验证 TXT 记录，等到它们显示为已验证且 TLS 完成预签发后，再将 CNAME 指向 Mintlify。此预验证流程不适用于通过 Cloudflare 代理的域名。请参见 通过 Cloudflare 代理的域名。
控制台会在后台轮询 DNS，一旦验证到预期值就会用绿色对勾标记每条记录。在 DNS 提供商处保存记录后，请等待短暂的传播时间，状态才会更新。

​
顶级域名

如果你将文档托管在没有子域名的顶级域名（如 example.com）上，你的 DNS 提供商必须支持 CNAME flattening，或类似 ALIAS 或 ANAME 的虚拟记录类型。标准 DNS 不允许在域名的顶级设置 CNAME 记录，因此不支持这些功能的提供商无法创建控制台中显示的记录。 支持顶级 CNAME 记录的提供商包括 Cloudflare（CNAME flattening）、Amazon Route 53（alias 记录）、DNSimple（ALIAS 记录）和 Porkbun（ALIAS 记录）。如果你的提供商都不支持这些功能，请改为将文档托管在类似 docs.example.com 的子域名下。

​
DNS 传播

DNS 变更通常需要 1–24 小时在全球范围内传播完成，某些情况下可能需要长达 48 小时。你可以使用 DNSChecker 等工具来验证 DNS 配置是否正确。 DNS 记录生效后，你的文档最初将通过 HTTP 提供访问。TLS 证书由 Mintlify 签发完成后，HTTPS 将可用。

​
自动 TLS 签发

在你添加 TXT 记录并且 DNS 记录能正确解析之后，Mintlify 会使用 Let’s Encrypt 为你的站点自动签发免费的 SSL/TLS 证书。 通常在 DNS 传播完成后的几小时内即可完成，极少数情况下可能需要长达 24 小时。证书会在到期前自动续期。

​
CAA 记录

如果你的域名使用 CAA（Certification Authority Authorization）记录，你必须授权 Let’s Encrypt 为你的域名签发证书。将以下 CAA 记录添加到你的 DNS 设置： 
0 issue "letsencrypt.org"

​
保留路径

Mintlify 保留 /.well-known/acme-challenge 路径用于证书验证。你不能对该路径进行重定向或重写。如果你为该路径配置了重定向或重写，证书签发会失败。

​
通过 Cloudflare 代理的域名

如果你的域名已经通过 Cloudflare 进行代理（代理状态显示为橙色云图标），在你更新 CNAME 之前，验证 TXT 记录无法显示为已验证。即使使用 dig 或 DNSChecker 等工具能正确解析这些记录，也是如此。Cloudflare 的代理会阻止验证完成，直到该主机名的流量路由到 Mintlify。 对于通过 Cloudflare 代理的域名，请按以下步骤操作：
  1. 在你的 DNS 提供商处添加验证 TXT 记录。
  2. 无需等待 TXT 记录显示为已验证，直接将 CNAME 记录更新为指向 cname.mintlify.builders。
  3. 等待验证和 TLS 签发完成。在签发期间，你的站点可能会短暂地提供无效证书。
如果你在迁移期间需要零停机，请将 CNAME 记录的代理状态改为 DNS only（灰色云图标）。这样可以在流量切换前完成标准的预验证流程。

​
特定服务商设置

如果 Cloudflare 是你的 DNS 提供商，你必须在 SSL/TLS 加密设置中启用 “Full (strict)” 模式。此外，请在 Edge Certificates 设置中禁用 “Always Use HTTPS”。Cloudflare 的 HTTPS 重定向会阻止 Let’s Encrypt 在证书签发期间验证你的域名。

​
重新触发验证

TXT 记录通常会在五分钟内完成验证。如果在添加验证 TXT 记录后你的域名仍处于待验证状态，可以在控制台中手动重新触发验证。
  1. 在控制台中前往 Custom domain setup 页面。
  2. 找到处于待验证状态的自定义域名。
  3. 选择 Retry validation。
请仅在确认 DNS 记录正确后再重新触发验证。使用错误的记录反复重试并不会加快验证。

​
移除自定义域名

要移除自定义域名，请在 Custom domain setup 页面上，点击你的域名旁的 移除图标并确认移除。指向该域名的现有链接可能会失效，重新添加该域名也可能需要重新配置 DNS 记录。

​
设置规范 URL

在配置好 DNS 后，设置一个规范 URL，以确保搜索引擎索引你首选的域名。规范 URL 会告诉搜索引擎哪一个版本的文档是主版本。当文档可通过多个 URL 访问时，这有助于提升 SEO，并避免重复内容问题。 在 docs.json 中添加 canonical 元标签： 
"seo": {
    "metatags": {
        "canonical": "https://www.your-custom-domain-here.com"
    }
}
将 https://www.your-custom-domain-here.com 替换为你的实际自定义域名。例如，如果你的自定义域名是 docs.mintlify.com，你应使用： 
"seo": {
    "metatags": {
        "canonical": "https://docs.mintlify.com"
    }
}