自定义域名

通过 DNS 配置、自动 TLS 证书以及子域名或子路径路由选项，将文档托管在自定义域名上。

要在自定义域名上托管你的文档：

1. 在控制台中添加你的 domain。
2. 在你的域名服务商处配置 DNS 设置。
3. 等待 DNS 生效并自动签发 TLS 证书。

想要配置类似 example.com/docs 这样的子路径？请参见 /docs 子路径。

​

添加自定义域名

1. 在控制台前往 Custom domain setup 页面。
2. 输入你的域名，例如 docs.example.com 或 www.example.com。
3. 点击 Add domain。

​

配置你的 DNS（域名系统）

1. 在你的域名提供商网站，前往该域名的 DNS 设置。
2. 新建一条 DNS 记录，并按以下值进行设置：

CNAME | docs | cname.mintlify.builders

不同域名提供商添加 DNS（域名系统）记录的方式各不相同。请查阅你的域名提供商文档获取具体操作指南。

在两条验证 TXT 记录都在你的 dashboard 中显示为已验证之前，请勿添加或更改 CNAME。当 DNS 配置正确时，每条记录都会显示绿色对勾。dashboard 会先验证 TXT 记录，证书才能完成签发。过早切换 CNAME 通常会导致 HTTPS 中断，直到签发完成。

如果你正在迁移现有域名并希望实现零停机，请先发布验证 TXT 记录，待其显示为已验证且 TLS 完成预签发后，再将 CNAME 指向 Mintlify。

​

验证 TXT 记录

添加自定义域名后，dashboard 会显示两条 TXT 记录，你必须在你的 DNS 提供商处添加：

TXT | _acme-challenge.<你的域名> | <dashboard 中显示的值>
TXT | _cf-custom-hostname.<你的域名> | <dashboard 中显示的值>

_acme-challenge 记录授权 Let’s Encrypt 为你的域名签发 TLS 证书，_cf-custom-hostname 记录用于验证你确实拥有该域名的控制权。

dashboard 会在后台轮询 DNS，并在验证到预期值后用绿色对勾标记每条记录。在 DNS 提供商处保存记录后，请等待短暂的传播时间，状态才会更新。

​

DNS 传播

DNS 变更通常需要 1–24 小时在全球范围内生效，某些情况下可能长达 48 小时。你可以使用 DNSChecker 验证 DNS 是否配置正确。

DNS 记录生效后，你的文档最初将通过 HTTP 提供访问。TLS 证书签发完成后，HTTPS 将可用。

​

自动配置 TLS

在你添加 TXT 记录后，当 DNS（域名系统）记录能够正确解析时，系统会使用 Let’s Encrypt 为你的站点自动签发免费的 SSL/TLS 证书。

通常在 DNS 传播后的数小时内即可完成，极少数情况下可能需要长达 24 小时。证书会在到期前自动续期。

​

CAA 记录

如果你的 domain 使用 CAA（Certification Authority Authorization）记录，你需要授权 Let’s Encrypt 为该 domain 签发证书。将以下 CAA 记录添加到你的 DNS（域名系统）设置中：

0 问题 "letsencrypt.org"

​

保留路径

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

​

特定服务商设置

Cloudflare 加密模式

如果 Cloudflare 是你的 DNS（域名系统）服务商，你需要在 SSL/TLS 加密设置中启用“Full (strict)”模式。此外，请在 Edge Certificates 设置中禁用“Always Use HTTPS”。Cloudflare 的 HTTPS 重定向会在证书配置期间阻止 Let’s Encrypt 验证你的域名。

​

重新触发验证

在你添加用于验证的 TXT 记录后，域名验证可能进入退避等待期，下一次重试最长可能需要数小时。如果你已添加正确的 DNS 记录，但域名仍处于待验证状态，可在控制台中手动重新触发验证以跳过等待。

1. 进入控制台中的自定义域名设置页面。
2. 找到处于待验证状态的自定义域名。
3. 点击 Retry validation。

请仅在确认 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 替换为你的实际自定义 domain。举例来说，如果你的自定义 domain 是 docs.mintlify.com，你应使用：

"seo": {
    "metatags": {
        "canonical": "https://docs.mintlify.com"
    }
}