> 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/docs-as-code/git-sync/troubleshooting.md).

# 故障排除

解决常见的 Git Sync、仓库、重定向和登录问题

使用这些解决方案来解决常见的 Git Sync 和仓库问题。展开某个主题即可查看相关检查项和后续步骤。

### 同步错误和访问权限

<details>

<summary>向受保护分支推送到仓库时出错</summary>

当你的 Git 分支受保护时会出现此错误：

```
错误：缺少向 refs/heads/main 受保护分支推送的权限。请检查你在 Git 提供商中的分支配置。
```

Git Sync 需要 GitBook 应用程序在不受限制的情况下向你的仓库推送更改，包括在设置期间。请允许 GitBook 应用程序绕过分支保护，以便同步正常工作。

只要允许应用程序绕过这些分支保护，GitBook 就支持这些保护：

* 在合并前要求发起拉取请求
* 限制谁可以向匹配分支推送

在 GitHub 中，打开仓库的分支保护设置，并允许 `gitbook-com` 绕过这些限制。

</details>

<details>

<summary>Git Sync 状态显示意外错误</summary>

**如果在 GitBook 中合并变更请求时出现此错误：** 创建一个仅包含少量改动（例如添加一个词）的新变更请求，然后将其合并。这会重新触发同步，GitBook 会再次导出所有内容，包括上次同步失败时的改动。

**如果在合并来自 GitHub 或 GitLab 的提交时出现此错误：** 在仓库中创建一个仅包含少量改动的新提交。合并后，GitBook 会再次从仓库导入所有内容，包括上次同步失败时的改动。

**如果在首次设置时出现此错误：** 移除 GitHub 或 GitLab 集成，在相应版块中重新启用，然后再次完成设置流程。

如果这些步骤都没有帮助，请 [联系支持团队](https://gitbook.com/docs/documentation/zh/bang-zhu/contact-support.md).

</details>

<details>

<summary>Git 身份验证失败</summary>

当你尝试向未授予 GitBook 访问权限的仓库推送时，会出现此消息。在这种情况下，从你的仓库到 GitBook 的同步可以正常工作，但反向不行——而且你的仓库可能不会被正确列出。

对于 GitHub，请在 GitHub 设置中授予访问权限：打开 **Manage Organization → Integrations → Applications**，点击 GitBook 旁边的 **Configure** ，然后选择 GitBook 应用可以访问的仓库。

对于 GitLab，请确保访问令牌已配置 `api`, `read_repository`和 `write_repository` 权限。

</details>

<details>

<summary>GitHub 预览未显示</summary>

如果你的 GitHub 预览未显示，可能是因为你的 Git Sync 集成是在 2022 年 1 月之前配置的。早于此日期配置的 Git Sync 版本不包含 GitHub 预览。

你应该收到一条通知，要求你接受更新后的权限请求，以启用对 PR 的只读访问。

如果你没有收到该通知，要排查问题，你需要更新到新版本：

1. 从你的组织中卸载 Git Sync 集成。
2. 使用更新后的权限重新安装新版本。

请注意，卸载 Git Sync 集成后，之前连接到该集成的任何区段都需要重新配置。

</details>

### 仓库内容和结构

<details>

<summary>Git Sync 文件大小限制</summary>

Git Sync 将单个文件大小限制为最大 100MB。为提升性能和同步速度，请优化仓库中文件和资源的大小。

</details>

<details>

<summary>我的目录结构不正确</summary>

你的 `SUMMARY.md` 文件会在 GitBook 上映射目录结构——文件中的结构会反映在内容中。请确保该文件体现了你希望文档采用的结构。有关预期格式，请参阅 [内容配置](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/content-configuration.md#summary) 。

</details>

<details>

<summary>编辑 <code>gitbook-docs.yaml</code></summary>

后，指向其他空间的链接会返回 404 `跨空间链接通过空间 ID 解析。Git Sync 会根据空间在` 文件中的 `key`来识别每个空间，因此更改空间的 key 会替换该空间：GitBook 会创建一个新空间，从映射目录导入内容，并将原空间留在你的组织中，使其与站点脱离关联。

页面会恢复，但空间 ID 会发生变化。指向旧 ID 的链接、卡片和 `SUMMARY.md` 条目都会失效。

新的 ID 是永久的。恢复原来的 key 并不能找回旧空间——这会创建另一个具有新 ID 的空间。请将受影响的引用改为指向当前空间，并为发生变化的已发布 URL 添加 [站点重定向](https://gitbook.com/docs/documentation/zh/publish/site-redirects.md) 。

原空间仍保留在你的组织中；如果仓库里没有你需要的内容，可以从原空间获取。 [如果找不到原空间，请](https://gitbook.com/docs/documentation/zh/bang-zhu/contact-support.md) 联系支持团队并提供原空间 ID。

</details>

<details>

<summary>重新连接 Git Sync 后，内容被替换</summary>

重新连接 Git Sync 或重新创建连接时，GitBook 会按照你选择的方向执行新的初始同步。如果选择 GitHub → GitBook 或 GitLab → GitBook，GitBook 会将每个已同步章节替换为所选分支的内容。如果该分支落后于 GitBook，例如尚未导出最近的变更请求，那么这些变更就会从章节和已发布的网站中消失。

被替换的内容仍保留在各章节的版本历史记录中。若要恢复：

1. 打开该章节的 **版本历史记录**.
2. 找到替换了内容的 Git Sync 记录，然后选择它之前的版本。
3. [回滚](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/version-control.md#roll-back-to-a-previous-version) 到该版本。
4. 对同步操作替换过的每个章节重复此操作。

回滚后，请确认恢复的内容已作为新的提交出现在你的分支中。如果仓库仍然落后，之后从仓库进行的同步可能会再次替换这些内容。

</details>

<details>

<summary>Git Sync 也会同步拉取请求吗？</summary>

不会。在 GitHub 或 GitLab 中创建拉取请求不会在 GitBook 中创建变更请求，而在 GitBook 中创建变更请求也不会在你的仓库中创建拉取请求。

</details>

### 常见的 Git Sync 问题

<details>

<summary>我有一个 GitHub 同步错误</summary>

#### 在你的仓库中创建 README 文件

启用 Git Sync 时，请注意不要通过 GitBook 界面创建 readme 文件。通过 GitBook 界面创建 readme 文件：

* 会在你的仓库中创建重复的 README 文件
* 会导致 GitBook 和 GitHub 之间的渲染冲突
* 可能破坏构建和部署流程
* 会导致文件优先级不可预测

这包括名为 README.md、readme.md、Readme.md 和 README（无扩展名）的文件。相反，请记得直接在 Git 仓库中管理你的 README 文件。

#### 仍然遇到错误？

请确保：

* 你的代码仓库 **有一个** `README.md` **文件** 位于根目录（或你在 `root` 文件夹中指定的目录），该文件夹在你的 `.gitbook.yaml`）中。该文件是直接在 Git 代码仓库中创建的。此文件为必需文件，用作文档的主页。有关详情，请参阅我们的 [内容配置](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/content-configuration.md).
* 如果 Markdown 文件中包含 YAML frontmatter，请使用 [代码检查工具](http://www.yamllint.com)。

</details>

<details>

<summary>GitBook 没有使用我的 <code>docs</code> 文件夹</summary>

默认情况下，GitBook 会将代码仓库的根目录作为起始位置。你可以指定一个目录，以限定 Markdown 文件的范围。有关详情，请参阅我们的 [内容配置](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/content-configuration.md) 文档。

</details>

<details>

<summary>GitBook 正在创建新的 Markdown 文件</summary>

**在 GitBook 中编辑并与现有 Git 代码仓库同步时** ，GitBook 可能会新建 Markdown 文件，而不是使用已有文件。这样做是为了确保 GitBook 不会覆盖代码仓库中原本存在的文件。

</details>

<details>

<summary>重定向无法正常工作</summary>

YAML 文件必须采用正确的格式，重定向才能生效。缩进或空格不正确等错误可能导致重定向无法正常工作。 [验证 YAML 文件](https://www.yamllint.com/) 有助于确保重定向正常运行。

设置重定向时，请勿添加前导斜杠。例如，尝试重定向到 `./misc/support.md` 将无法生效。

还需要注意的是，只要某个路径存在页面，GitBook 就不会去寻找可能的重定向。因此，如果你要为旧页面设置到新页面的重定向，你需要先删除旧页面，重定向才能生效。

</details>

<details>

<summary>我的仓库没有列出</summary>

#### GitHub 仓库

请确保你已将 GitBook GitHub 应用安装到正确的位置（安装应用时，你可以选择将其安装到个人 GitHub，或安装到你有权限的任何组织），并且你已为该应用授予正确的仓库权限。

#### GitLab 仓库

请确保你的访问令牌已配置以下访问权限：

* `api`
* `read_repository`
* `write_repository`

</details>

<details>

<summary>在我向仓库添加文件后没有任何反应</summary>

{% hint style="warning" %}
**本节专门介绍以下情况的问题： `SUMMARY.md` 文件已存在**

如果你的代码仓库中没有 `SUMMARY.md` 文件，GitBook 会在首次同步时自动创建该文件。这意味着，如果你在设置 Git Sync 后至少通过 GitBook 编辑过一次内容，GitBook 应该已经自动创建了此文件。
{% endhint %}

如果你在代码仓库中添加或修改 Markdown 文件后，GitBook 上没有显示相应更新，并且同步期间侧边栏也没有提示错误，那么你修改的文件可能未列在 [你的 `SUMMARY.md` 文件中](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/content-configuration.md#summary)。

这可能是因为你手动创建了该文件，或者因为你在 GitBook 中进行了编辑，而同步的 GitBook 到 Git 导出阶段为你创建了它。

此文件的内容与 GitBook 上的 [目录](https://gitbook.com/docs/documentation/zh/can-kao/gitbook-ui.md#table-of-contents) 一致。在 Git 到 GitBook 的同步导入阶段，系统会使用此文件重新创建目录，并协调代码仓库后续更新与 GitBook 上现有内容之间的关系。

如果确认所有文件都已包含在 `SUMMARY.md` 文件中后，GitBook 上仍然没有任何变化，请随时 [联系支持团队](https://gitbook.com/docs/documentation/zh/bang-zhu/contact-support.md) 寻求帮助。

</details>

<details>

<summary>登录时我有重复账户</summary>

当你用于设置同步的 GitHub 账户已经关联到另一个 GitBook 用户账户时，通常会出现此错误。

识别 GitHub 账户已链接到哪个 GitBook 账户的一个好方法是：

1. 退出当前 GitBook 用户会话（即 `name@email.com`)
2. 从任何 GitHub 用户会话中登出。
3. 前往 [登录页面](https://app.gitbook.com/login).
4. 选择“使用 GitHub 登录”选项。
5. 输入你的 GitHub 凭据。
6. 登录后，前往 [账户设置](https://app.gitbook.com/account) 然后任选其一：
   1. 在个人设置中的“第三方登录 > GitHub”部分取消关联该账户
   2. 如果你不需要该账户，就将其彻底删除。
7. 从该会话中登出。
8. 重新使用你的 `name@email.com` GitBook 账户登录。
9. 再次尝试设置 Git Sync。

</details>

<details>

<summary>不安全文件正在阻止 Git Sync</summary>

如果你的空间中包含 GitBook 认为导出不安全的文件（例如 `.js`).

你可能会看到如下错误：

> `File "<filename>" cannot be exported as it is considered unsafe`

必须从 GitBook 空间中移除这些不安全文件，而不仅仅是从 Git 仓库中删除。

1. 在受影响的空间中创建一个变更请求
2. 打开 **文件** 标签页
3. 删除不安全文件
4. 合并变更请求

一旦不安全文件从空间中移除，Git Sync 应该会恢复正常。

</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/docs-as-code/git-sync/troubleshooting.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.
