> 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/getting-started/git-sync/troubleshooting.md).

# 故障排查

## 我遇到了 GitHub 同步错误 <a href="#i-have-a-github-sync-error" id="i-have-a-github-sync-error"></a>

### 请务必只在你的仓库中创建 README 文件

启用 Git 同步后，请注意不要通过 GitBook UI 创建 README 文件。通过 GitBook UI 创建 README 文件：

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

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

### 仍然遇到错误？

请确保：

* 你的仓库 **有一个** `README.md` **文件** 位于其根目录（或位于 `root` 你在 `.gitbook.yaml`中指定的文件夹）下，并且是直接在你的 git 仓库中创建的。此文件是必需的，并用作你的文档主页。更多详情请参阅我们的 [内容配置](/docs/documentation/zh/getting-started/git-sync/content-configuration.md).
* 如果你的 Markdown 文件中有 YAML frontmatter，请使用 [linter](http://www.yamllint.com)进行检查，确保它们是有效的。

## GitBook 没有使用我的 `docs` 文件夹 <a href="#gitbook-is-not-using-my-docs-folder" id="gitbook-is-not-using-my-docs-folder"></a>

默认情况下，GitBook 会使用仓库根目录作为起点。可以指定特定目录来限定 markdown 文件的范围。有关更多详情，请查看我们关于 [内容配置](/docs/documentation/zh/getting-started/git-sync/content-configuration.md) 的文档。

## GitBook 正在创建新的 markdown 文件 <a href="#gitbook-is-creating-new-markdown-files" id="gitbook-is-creating-new-markdown-files"></a>

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

## 重定向无法正常工作

YAML 文件需要正确格式化，重定向才能生效。缩进错误或空白字符错误等问题都可能导致重定向失效。 [验证你的 YAML 文件](https://www.yamllint.com/) 可以确保重定向顺利工作。

设置重定向时，不要添加任何前导斜杠。例如，尝试重定向到 `./misc/support.md` 将不会生效。

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

## 我的仓库未列出 <a href="#my-repository-is-not-listed" id="my-repository-is-not-listed"></a>

### 对于 GitHub 仓库

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

### 对于 GitLab 仓库

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

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

## 在我的仓库中添加新文件后，GitBook 上没有任何反应 <a href="#nothing-happens-on-gitbook-after-adding-a-new-file-to-my-repository" id="nothing-happens-on-gitbook-after-adding-a-new-file-to-my-repository"></a>

{% hint style="warning" %}
**本节专门处理以下问题：当 `SUMMARY.md` 文件已存在**

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

如果你在通过添加或修改 markdown 文件更新仓库后，没有在 GitBook 上看到更新生效，而且侧边栏在同步期间也没有提示错误，那么你修改的文件很可能未列在 [你的 `SUMMARY.md` 文件](/docs/documentation/zh/getting-started/git-sync/content-configuration.md#summary).‌

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

此文件的内容与你在 GitBook 上的 [目录](/docs/documentation/zh/zi-yuan/gitbook-ui.md#table-of-contents) 相对应，并在 Git 到 GitBook 导入阶段用于重新创建你的目录，并将仓库中的后续更新与你在 GitBook 上的现有内容重新协调。

如果在确认所有文件都已包含在 `SUMMARY.md` 文件中后，GitBook 上仍然没有任何反应，请随时 [联系支持](https://gitbook.com/docs/help-center/further-help/how-do-i-contact-support) 寻求帮助。

## GitHub 预览未显示

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

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

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

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

请注意，卸载 GitSync 集成后，需要在之前连接过的任何区段中重新配置该集成。

## 登录时可能出现重复账户

当你用于设置同步的 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 同步。


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/getting-started/git-sync/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.