> 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 同步错误
### 请确保只在你的仓库中创建 readme 文件
启用 Git 同步后，请注意不要通过 GitBook 界面创建 readme 文件。通过 GitBook 界面创建 readme 文件：
* 会在你的仓库中创建重复的 README 文件
* 会导致 GitBook 与 GitHub 之间的渲染冲突
* 可能会破坏构建和部署流程
* 会导致文件优先级不可预测
这包括名为 README.md、readme.md、Readme.md 和 README（无扩展名）的文件。相反，请记得直接在你的 git 仓库中管理你的 README 文件。
### 仍然遇到错误？
请确保：
* 你的仓库 **有一个** `README.md` **文件** 位于其根目录（或位于 `根目录` 文件夹中，由你的 `.gitbook.yaml`指定）且该文件是直接在你的 git 仓库中创建的。此文件是必需的，并用作你文档的首页。更多详情，请参阅我们的 [内容配置](/docs/documentation/zh/getting-started/git-sync/content-configuration.md).
* 如果你的 Markdown 文件中包含 YAML frontmatter，请确保它们使用 [linter](http://www.yamllint.com)进行验证后是有效的。
## GitBook 没有使用我的 `docs` 文件夹
默认情况下，GitBook 使用仓库根目录作为起点。可以指定一个特定目录来限定 markdown 文件的范围。有关更多详情，请查看我们关于 [内容配置](/docs/documentation/zh/getting-started/git-sync/content-configuration.md) 的文档。
## GitBook 正在创建新的 markdown 文件
**当从 GitBook 进行同步和编辑时，** 在已有 git 仓库的情况下，GitBook 可能会创建新的 markdown 文件，而不是使用现有文件。这样做是为了确保 GitBook 不会覆盖在你设置 Git 同步之前就已存在于仓库中的文件。
## 重定向无法正常工作
YAML 文件需要正确格式化，重定向才能生效。缩进或空格不正确等错误都可能导致重定向失效。 [验证你的 YAML 文件](https://www.yamllint.com/) 可以确保重定向顺利工作。
设置重定向时，不要添加任何前导斜杠。例如，尝试重定向到 `./misc/support.md` 将不会起作用。
同样重要的是要注意，只要某个路径下存在页面，GitBook 就不会去查找可能的重定向。因此，如果你要将旧页面重定向到新页面，你需要先移除旧页面，重定向才能生效。
## 我的仓库没有列出
### 对于 GitHub 仓库
请确保你已将 GitBook GitHub 应用安装到正确的位置（安装应用时，你可以选择安装到个人 GitHub，或你有权限的任何组织），并且已授予该应用正确的仓库权限。
### 对于 GitLab 仓库
请确保你的访问令牌已配置以下访问权限：
* `api`
* `read_repository`
* `write_repository`
## 在我的仓库中添加新文件后，GitBook 上没有任何反应
{% 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 上仍然没有任何变化，请随时 [联系支持](/docs/documentation/zh/zi-yuan/support.md) 以获得帮助。
## 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 同步。
## 向受保护分支的仓库推送时出错
当你的 Git 分支受保护时，会出现此错误：
```
错误：缺少向 refs/heads/main 受保护分支推送的权限。请检查你在 git 提供商上的分支配置。
```
Git 同步需要 GitBook 应用能够不受限制地向你的仓库推送更改，包括在设置期间。请允许 GitBook 应用绕过分支保护，以便同步正常工作。
只要允许该应用绕过这些保护，GitBook 就支持以下分支保护：
* 在合并前要求拉取请求
* 限制谁可以向匹配的分支推送
在 GitHub 中，打开你仓库的分支保护设置并允许 `gitbook-com` 绕过这些限制。
## Git 同步文件大小限制
Git 同步将单个文件大小限制为最大 100MB。为了提升性能和同步速度，请优化仓库中文件和资源的大小。
## Git 同步状态显示意外错误
**如果错误是在 GitBook 中合并变更请求时出现的：** 创建一个包含小改动的新变更请求——例如添加一个词——然后将其合并。这会重新触发同步，并且 GitBook 会再次导出所有内容，包括上次失败同步中的更改。
**如果错误是在从 GitHub 或 GitLab 合并提交时出现的：** 在你的仓库中创建一个包含小改动的新提交。当它合并后，GitBook 会再次从仓库导入所有内容，包括上次失败同步中的更改。
**如果错误是在首次设置期间出现的：** 移除 GitHub 或 GitLab 集成，重新在你的章节中启用它，然后再次完成设置流程。
如果这些步骤都没有帮助， [联系支持](/docs/documentation/zh/zi-yuan/support.md).
## 我的目录结构不正确
你的 `SUMMARY.md` 文件会映射到你在 GitBook 中的目录——其结构方式会反映在你的内容中。请确保该文件反映了你希望在文档中看到的结构。请参阅 [内容配置](/docs/documentation/zh/getting-started/git-sync/content-configuration.md#summary) 以了解预期格式。
## 为什么我会看到“Git 认证失败”消息？
当你尝试向一个尚未授予 GitBook 访问权限的仓库推送时，会出现此消息。在这种情况下，从你的仓库同步到 GitBook 可以正常工作，但反向同步则不行——并且你的仓库可能不会被正确列出。
对于 GitHub，请在你的 GitHub 设置中授予访问权限：打开 **管理组织 → 集成 → 应用**，点击 **配置** 旁边的 GitBook，并选择 GitBook 应用可访问的仓库。
对于 GitLab，请确保你的访问令牌已配置 `api`, `read_repository`和 `write_repository` 访问权限。
## Git 同步也会同步拉取请求吗？
不会。在 GitHub 或 GitLab 中创建拉取请求不会在 GitBook 中创建变更请求，而在 GitBook 中创建变更请求也不会在你的仓库中创建拉取请求。
---
# 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=&goal=
```
`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.