> ## Documentation Index
> Fetch the complete documentation index at: https://smartac-mintlify-8d29b8e9.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 自定义域名

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

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

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

<Info>
  想要配置类似 `example.com/docs` 这样的子路径？请参见 [/docs 子路径](/zh/deploy/docs-subpath)。
</Info>

<div id="add-your-custom-domain">
  ## 添加自定义域名
</div>

1. 在控制台前往 [Custom domain setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) 页面。
2. 输入你的域名，例如 `docs.example.com` 或 `www.example.com`。
3. 点击 **Add domain**。

<Frame>
  <img alt="“Custom domain setup” 页面，显示用于输入自定义域名 URL 的字段。" className="block dark:hidden" src="https://mintcdn.com/smartac-mintlify-8d29b8e9/I27Jxl5et7Ho5QoW/images/domain/add-custom-domain-light.png?fit=max&auto=format&n=I27Jxl5et7Ho5QoW&q=85&s=b5af87b2c8c6afa807830d8eecdb1e34" width="2236" height="608" data-path="images/domain/add-custom-domain-light.png" />

  <img alt="“Custom domain setup” 页面，显示用于输入自定义域名 URL 的字段。" className="hidden dark:block" src="https://mintcdn.com/smartac-mintlify-8d29b8e9/I27Jxl5et7Ho5QoW/images/domain/add-custom-domain-dark.png?fit=max&auto=format&n=I27Jxl5et7Ho5QoW&q=85&s=f17be97480e58ac4471e22fc7bb7e673" width="2236" height="608" data-path="images/domain/add-custom-domain-dark.png" />
</Frame>

<div id="configure-your-dns">
  ## 配置你的 DNS（域名系统）
</div>

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

```text theme={null}
CNAME | docs | cname.mintlify.builders
```

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

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

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

<div id="verification-txt-records">
  ### 验证 TXT 记录
</div>

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

```text theme={null}
TXT | _acme-challenge.<你的域名> | <dashboard 中显示的值>
TXT | _cf-custom-hostname.<你的域名> | <dashboard 中显示的值>
```

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

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

<div id="dns-propagation">
  ### DNS 传播
</div>

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

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

<div id="automatic-tls-provisioning">
  ### 自动配置 TLS
</div>

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

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

<div id="caa-records">
  ### CAA 记录
</div>

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

```text theme={null}
0 问题 "letsencrypt.org"
```

<div id="reserved-paths">
  ### 保留路径
</div>

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

<div id="provider-specific-settings">
  ### 特定服务商设置
</div>

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

<div id="retry-validation">
  ### 重新触发验证
</div>

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

1. 进入控制台中的[自定义域名设置](https://dashboard.mintlify.com/settings/deployment/custom-domain)页面。
2. 找到处于待验证状态的自定义域名。
3. 点击 **Retry validation**。

请仅在确认 DNS 记录正确后再使用该选项。使用错误的记录反复重试不会加快验证。

<div id="set-a-canonical-url">
  ## 设置规范 URL
</div>

在配置好 DNS 后，设置一个规范 URL，以确保搜索引擎索引你首选的域名。规范 URL 会告诉搜索引擎哪一个版本的文档是主版本。当文档可通过多个 URL 访问时，这有助于提升 SEO（搜索引擎优化），并避免重复内容问题。

在 `docs.json` 中添加 `canonical` 元标签：

```json theme={null}
"seo": {
    "metatags": {
        "canonical": "https://www.your-custom-domain-here.com"
    }
}
```

将 `https://www.your-custom-domain-here.com` 替换为你的实际自定义 domain。举例来说，如果你的自定义 domain 是 `docs.mintlify.com`，你应使用：

```json theme={null}
"seo": {
    "metatags": {
        "canonical": "https://docs.mintlify.com"
    }
}
```