mintlify__docs/zh/customize/custom-domain.mdx

---
title: "自定义域名"
description: "使用 DNS 记录、自动 TLS 证书以及 Mintlify 托管或代理流量路由，将你的站点托管在自己的域名、子域名或子路径下。"
keywords: ["自定义域名配置", "DNS 配置", "CNAME 记录", "TLS 证书", "子路径", "托管", "基础路径", "顶级域名", "CNAME flattening", "ALIAS 记录"]
---

将你的文档托管在自己的域名（例如 `docs.example.com`）上，或托管在你域名的某个子路径下（例如 `example.com/docs`）。

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

1. 在控制台中添加你的域名。
2. 在你的域名提供商处配置 DNS 设置。
3. 等待 DNS 传播完成，并自动签发 TLS 证书。

<div id="choose-where-to-host-your-documentation">
  ## 选择托管文档的位置
</div>

你可以将文档托管在域名的根路径、子域名或子路径下。

**域名或子域名**：将文档托管在类似 `example.com` 的域名或类似 `docs.example.com` 的子域名上。Mintlify 会处理该域名或子域名的所有流量。若要在不带子域名的域名上托管，你的 DNS 提供商必须支持 CNAME flattening 或 `ALIAS` 记录。请参见 [顶级域名](#apex-domains)。

**子路径**：将文档托管在你域名的某个路径下，例如 `example.com/docs`。添加域名时启用 **Host at** 开关并输入你的基础路径。流量到达 Mintlify 的方式取决于你的 DNS：
- 如果你域名的 DNS 指向 Mintlify，Mintlify 会在你的子路径下提供文档服务。仅在该域名不承载其他内容、且 Mintlify 可以接收该域名上的所有路径时，才将域名指向 Mintlify。
- 如果你的域名上还运行着其他站点，你的应用或 CDN 会继续接收域名的流量，并只将你的子路径代理到 Mintlify。

<Note>
  已启用[身份验证](/zh/deploy/authentication-setup)的文档不支持子路径托管。
</Note>

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

1. 在控制台中前往 [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) 页面。
2. 若要在子路径下托管，启用 **Host at** 开关并输入你的基础路径，例如 `/docs`。
3. 输入你的域名。例如 `docs.example.com` 或 `example.com`。
4. 选择 **Add domain**。

如果你的域名流量指向 Mintlify，控制台将显示需要在你的域名提供商处添加的 DNS 记录。

如果你只是将子路径代理到 Mintlify，控制台会改为显示反向代理的设置指南。请按照适用于你提供商的指南操作，并参阅 [在子路径下托管文档](/zh/deploy/docs-subpath) 获取更多信息。

<Tip>
  你也可以从终端使用 [`mint add-domain <domain>`](/zh/cli/commands#mint-add-domain) 添加域名。该命令会在你的部署上注册该域名，并打印需要配置的 DNS 记录。
</Tip>

<div id="base-path-requirements">
  ### 基础路径要求
</div>

只要满足以下要求，你的基础路径可以是任意路径：

- 以 `/` 开头，不包含空格、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`。

<div id="change-your-base-path">
  ### 修改你的基础路径
</div>

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

<div id="configure-your-dns">
  ## 配置你的 DNS
</div>

<Tip>
  不同的域名提供商添加 DNS 记录的方式各不相同。请参阅你的域名提供商文档以获取具体说明。
</Tip>

1. 在你的域名提供商网站上，前往该域名的 DNS 设置。
2. 创建控制台中显示的 DNS 记录。

控制台会显示用于验证的 `TXT` 记录以及一条 `CNAME` 记录：

```text
TXT | _acme-challenge.<你的域名> | <控制台中显示的值>
TXT | _cf-custom-hostname.<你的域名> | <控制台中显示的值>
CNAME | <你的域名> | cname.mintlify.builders
```

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

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

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

  此预验证流程不适用于通过 Cloudflare 代理的域名。请参见 [通过 Cloudflare 代理的域名](#cloudflare-proxied-domains)。
</Warning>

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

<div id="apex-domains">
  ### 顶级域名
</div>

如果你将文档托管在没有子域名的顶级域名（如 `example.com`）上，你的 DNS 提供商必须支持 CNAME flattening，或类似 `ALIAS` 或 `ANAME` 的虚拟记录类型。标准 DNS 不允许在域名的顶级设置 `CNAME` 记录，因此不支持这些功能的提供商无法创建控制台中显示的记录。

支持顶级 `CNAME` 记录的提供商包括 Cloudflare（CNAME flattening）、Amazon Route 53（alias 记录）、DNSimple（`ALIAS` 记录）和 Porkbun（`ALIAS` 记录）。如果你的提供商都不支持这些功能，请改为将文档托管在类似 `docs.example.com` 的子域名下。

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

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

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

<div id="automatic-tls-provisioning">
  ### 自动 TLS 签发
</div>

在你添加 `TXT` 记录并且 DNS 记录能正确解析之后，Mintlify 会使用 Let's Encrypt 为你的站点自动签发免费的 SSL/TLS 证书。

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

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

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

```text
0 issue "letsencrypt.org"
```

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

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

<div id="cloudflare-proxied-domains">
  ### 通过 Cloudflare 代理的域名
</div>

如果你的域名已经通过 Cloudflare 进行代理（代理状态显示为橙色云图标），在你更新 `CNAME` 之前，验证 `TXT` 记录无法显示为已验证。即使使用 `dig` 或 DNSChecker 等工具能正确解析这些记录，也是如此。Cloudflare 的代理会阻止验证完成，直到该主机名的流量路由到 Mintlify。

对于通过 Cloudflare 代理的域名，请按以下步骤操作：

1. 在你的 DNS 提供商处添加验证 `TXT` 记录。
2. 无需等待 `TXT` 记录显示为已验证，直接将 `CNAME` 记录更新为指向 `cname.mintlify.builders`。
3. 等待验证和 TLS 签发完成。在签发期间，你的站点可能会短暂地提供无效证书。

如果你在迁移期间需要零停机，请将 `CNAME` 记录的代理状态改为 **DNS only**（灰色云图标）。这样可以在流量切换前完成标准的预验证流程。

<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` 记录通常会在五分钟内完成验证。如果在添加验证 `TXT` 记录后你的域名仍处于待验证状态，可以在控制台中手动重新触发验证。

1. 在控制台中前往 [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) 页面。
2. 找到处于待验证状态的自定义域名。
3. 选择 **Retry validation**。

请仅在确认 DNS 记录正确后再重新触发验证。使用错误的记录反复重试并不会加快验证。

<div id="remove-a-custom-domain">
  ## 移除自定义域名
</div>

要移除自定义域名，请在 [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) 页面上，点击你的域名旁的 <Icon name="trash-2" /> 移除图标并确认移除。指向该域名的现有链接可能会失效，重新添加该域名也可能需要重新配置 DNS 记录。

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

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

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

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

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

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