> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/publish/custom-domain.md).

# 设置自定义域名

为你的文档站点设置自定义域名

{% hint style="warning" %}
本页介绍如何配置自定义域名和子域名。如果你想配置自定义子目录（例如 `example.com/docs`），请参阅 [设置自定义子目录](https://gitbook.com/docs/documentation/zh/publish/custom-domain/setting-a-custom-subdirectory.md) 页面。
{% endhint %}

默认情况下，你的网站可通过 `[subdomain].gitbook.io` 域名访问。

你可以通过设置自定义域名来进行个性化配置，这意味着你的受众可以通过你选择的域名访问你的文档。

{% stepper %}
{% step %}

#### 选择子域名

选择子域名时，你可以使用 `www` 或自定义子域名。常用子域名包括：

* `docs.example.com`
* `help.example.com`
* `developers.example.com`
  {% endstep %}

{% step %}

#### 开始设置自定义域名

前往要设置自定义域名的网站。点击 **设置**，然后选择 **设置自定义域名**.

此时会出现一个窗口，你可以在其中输入第一步中选择的自定义域名。输入域名，然后点击 **下一步**.
{% endstep %}

{% step %}

#### 配置 DNS

此时会出现一个包含三个字段的窗口： **类型、名称、目标。**

你需要使用这些信息，在 DNS 服务商处设置自定义域名。这项操作需要在 *GitBook* 之外完成，也就是在你使用的域名服务商处进行。

复制 **名称** 和 **目标** 字段中的内容，以便在 DNS 服务商处使用。每家服务商的操作方式都不同；如有疑问，请直接向服务商咨询如何添加此记录。你应该可以从服务商提供的列表中选择记录 **类型** 。

添加记录后，更改可能需要一段时间才能生效。我们建议 **至少等待 1 小时** 再进行下一步。准备就绪后，点击 **下一步** 。
{% endstep %}

{% step %}

#### 完成设置

在添加记录并完成传播后，就可以正式上线了！GitBook 将验证该域名和您添加的记录，并会自动为您的域名配置 SSL 证书。

完成后，你会收到通知，并可以点击 **完成**。你也可以关闭此窗口；我们会在这边完成处理后向你发送通知。
{% endstep %}
{% endstepper %}

### 更改或更新你的自定义域名

若要更改网站的自定义域名，请打开网站侧边栏中的 **设置** ，然后点击 **域名和 URL**。你可以移除当前域名并添加新域名，也可以编辑现有配置。

请记得在你的域名提供商处更新 DNS 设置，使其指向新的 GitBook 配置——这个过程与初始设置相同，使用指向 GitBook 提供值的 CNAME 记录。

### 故障排除

设置自定义域名有时可能会遇到障碍。下面，我们概述在此过程中常见的问题，并为每个问题提供详细解决方案。

<details>

<summary>我的自定义子域名无法正常工作。</summary>

自定义域名问题通常与 DNS 有关。请检查你的 DNS 配置：

1. 请确认你创建的是 **CNAME 记录** （而不是 A 记录），并将其指向 GitBook 提供的值。
2. 请确保使用子域名格式（`docs.yoursite.com` 或 `www.yoursite.com`).
3. 如果你使用 Cloudflare，请关闭代理（橙色云朵）——该记录必须设置为“仅 DNS”。

常见的 DNS 问题：

* **记录冲突** — 删除同一子域名下所有现有的 A、AAAA 或其他记录。
* **TTL 延迟** — DNS 更改可能需要最多 48 小时才能在全球范围内生效。
* **CAA 记录** — 如果您有 CAA 记录，请添加 `0 issue "pki.goog"` 以允许 GitBook 使用 SSL 证书。

要测试设置，请使用 DNS 查询工具，例如 [WhatsMyDNS](https://www.whatsmydns.net/#CNAME) ，验证您的 CNAME 记录是否指向正确的 GitBook 地址。如果 48 小时后问题仍未解决，请联系支持团队，并提供您的域名以及 GitBook 提供的 CNAME 值。

</details>

<details>

<summary>SSL 错误：配置 SSL 证书时发生错误。</summary>

当为你的组织、组或部分设置自定义域名时，我们会在后台为你配置 SSL 证书，以便你的文档通过 HTTPS 安全加载。\n\n当你设置自定义域名时，这一过程会自动完成——你无需购买或配置 SSL 证书。

在此阶段偶尔会发生错误，通常是因为自定义域名的 CNAME 记录尚未传播生效。

在这些情况下，我们建议如下：

1. 请检查您的 CNAME 记录是否已正确设置。\
   请查看我们关于配置 DNS 的页面，以便获取帮助。\
   如果 CNAME 记录不正确，我们将无法配置 SSL 证书并完成自定义域名设置。
2. 请预留 ***至少一小时*** ，在配置 CNAME 记录后再完成自定义域名设置。
3. 请验证 CNAME 是否已生效。您可以尝试使用第三方 DNS 查询工具，例如 [WhatsMyDNS](https://www.whatsmydns.net/)，了解各服务器认为正确的 CNAME 记录应是什么。
4. 如果您使用 Cloudflare，请确认该记录未启用代理 [，如这里所述](https://developers.cloudflare.com/fundamentals/setup/manage-domains/pause-cloudflare/#disable-proxy-on-dns-records).

</details>

<details>

<summary>域名已连接错误：你的子域名已配置为其他内容。</summary>

分配给网站的自定义域名必须是唯一的。在多个位置尝试使用相同的自定义域名会导致错误。

如果发生这种情况，你可以点击错误消息中的链接，查看该自定义域名已连接到的内容。这可能有助于你决定下一步怎么做。

不过，也有可能你无法访问该内容——如果是这样，请联系支持团队，他们可以帮助你了解下一步该怎么做。

不过，这个错误的解决方案通常只有两种：

1. 选择不同的自定义域名；或
2. 将自定义域名从当前连接的内容中断开，然后将其重新连接到新内容。

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/zh/publish/custom-domain.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
