> 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/wen-dang-ji-dai-ma/git-sync/troubleshooting.md).
# 故障排查
使用这些解决方案来解决常见的 Git Sync 和仓库问题。展开某个主题以查看相关检查项和后续步骤。
### 同步错误和访问权限
向带有受保护分支的仓库推送时出错
当你的 Git 分支受到保护时，会出现此错误：
```
错误：缺少向 refs/heads/main 受保护分支推送的权限。请检查你在 Git 提供商中的分支配置。
```
Git Sync 需要 GitBook 应用在设置期间以及之后都能不受限制地向你的仓库推送更改。请允许 GitBook 应用绕过分支保护，以便同步正常工作。
只要允许应用绕过这些分支保护，GitBook 就支持以下保护规则：
* 在合并前要求拉取请求
* 限制哪些人可以向匹配的分支推送
在 GitHub 中，打开你的仓库分支保护设置，并允许 `gitbook-com` 绕过这些限制。
Git Sync 状态显示意外错误
**如果错误出现在你在 GitBook 中合并变更请求时：** 创建一个包含小改动的新变更请求——例如添加一个词——并将其合并。这会重新触发同步，GitBook 会再次导出所有内容，包括上次同步失败时的更改。
**如果错误出现在你从 GitHub 或 GitLab 合并提交时：** 在你的仓库中创建一个带有小改动的新提交。合并后，GitBook 会再次从仓库导入所有内容，包括上次同步失败时的更改。
**如果错误出现在首次设置期间：** 移除 GitHub 或 GitLab 集成，在你的空间中重新启用它，并再次完成设置流程。
如果这些步骤都无济于事， [请联系支持团队](/docs/documentation/zh/bang-zhu/contact-support.md).
Git 身份验证失败
当你尝试向尚未授予 GitBook 访问权限的仓库推送时，会出现此消息。在这种情况下，从你的仓库同步到 GitBook 可以正常工作，但反向则不行——并且你的仓库可能不会正确列出。
对于 GitHub，请在 GitHub 设置中授予访问权限：打开 **管理组织 → 集成 → 应用**，点击 **配置** ，在 GitBook 旁边，选择 GitBook 应用可以访问的仓库。
对于 GitLab，请确保你的访问令牌已配置以下权限： `api`, `read_repository`，以及 `write_repository` 访问。
GitHub 预览未显示
如果你的 GitHub 预览没有显示，可能是因为你的 GitSync 集成是在 2022 年 1 月之前配置的。在此日期之前配置的 GitSync 版本不包含 GitHub 预览。
你应该已经收到一条通知，请你接受更新后的权限请求，以启用对 PR 的只读访问。
如果你没有收到该通知，要排查问题，你需要更新到新版本：
1. 从你的组织中卸载 GitSync 集成。
2. 使用更新后的权限重新安装新版本。
请注意，卸载 GitSync 集成后，之前连接到它的任何空间都需要重新配置该集成。
### 仓库内容和结构
Git Sync 文件大小限制
Git Sync 将单个文件大小限制为最大 100MB。为提高性能和同步速度，请优化仓库中文件和资源的大小。
我的目录结构不正确
你的 `SUMMARY.md` 文件会在 GitBook 中镜像你的目录结构——其结构方式会反映在你的内容中。请确保该文件反映出你希望在文档中看到的结构。请参阅 [内容配置](/docs/documentation/zh/wen-dang-ji-dai-ma/git-sync/content-configuration.md#summary) 了解预期格式。
Git Sync 也会同步拉取请求吗？
不会。在 GitHub 或 GitLab 中创建拉取请求不会在 GitBook 中创建变更请求，在 GitBook 中创建变更请求也不会在你的仓库中创建拉取请求。
### 常见的 Git Sync 问题
我有一个 GitHub 同步错误
#### 在你的仓库中创建 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 仓库中创建的。此文件是必需的，并用作你文档的主页。有关更多详细信息，请参阅我们的 [内容配置](/docs/documentation/zh/wen-dang-ji-dai-ma/git-sync/content-configuration.md).
* 如果你的 Markdown 文件中包含 YAML front matter，请使用 [linter](http://www.yamllint.com)。
GitBook 没有使用我的 docs 文件夹
默认情况下，GitBook 以仓库根目录作为起点。你可以指定特定目录来限定 Markdown 文件的范围。请查看我们关于 [内容配置](/docs/documentation/zh/wen-dang-ji-dai-ma/git-sync/content-configuration.md) 的文档以了解更多详情。
GitBook 正在创建新的 Markdown 文件
**在从 GitBook 进行同步和编辑时** 在已有 Git 仓库的情况下，GitBook 可能会创建新的 markdown 文件，而不是使用现有文件。这么做是为了确保 GitBook 不会覆盖在你开始之前就已经存在于仓库中的文件。
重定向无法正常工作
YAML 文件需要正确格式化，重定向才能生效。诸如缩进或空白不正确之类的错误都可能导致重定向无法工作。 [验证你的 YAML 文件](https://www.yamllint.com/) 可以确保重定向顺利工作。
设置重定向时，不要添加任何前导斜杠。例如，尝试重定向到 `./misc/support.md` 不会起作用。
还需要考虑的是，只要某个路径存在页面，GitBook 就不会去寻找可能的重定向。因此，如果你为旧页面设置重定向到新页面，你需要先删除旧页面，重定向才会生效。
我的仓库未列出
#### GitHub 仓库
请确保你已将 GitBook GitHub 应用安装到正确的位置（安装应用时，你可以选择将其安装到你的个人 GitHub，或任何你有权限的组织）并且你已授予该应用正确的仓库权限。
#### GitLab 仓库
请确保你的访问令牌已配置以下访问权限：
* `api`
* `read_repository`
* `write_repository`
在我向仓库添加文件后什么也没有发生
{% hint style="warning" %}
**此部分专门解决当一个 `SUMMARY.md` 文件已存在**
如果你的仓库不包含一个 `SUMMARY.md` 文件，GitBook 会在首次同步时自动创建一个。这意味着，如果你在设置 Git 同步后至少曾在 GitBook 中编辑过一次内容，GitBook 应该会自动创建此文件。
{% endhint %}
如果在通过添加或修改 markdown 文件更新仓库后，你没有在 GitBook 中看到更新反映出来，而且侧边栏也没有在同步期间显示错误，那么你修改的文件很可能没有列在 [你的 `SUMMARY.md` 文件](/docs/documentation/zh/wen-dang-ji-dai-ma/git-sync/content-configuration.md#summary)。
这可能是因为你手动创建了该文件，或者因为你在 GitBook 中进行了编辑，而同步中的 GitBook 到 Git 导出阶段为你创建了它。
此文件的内容会镜像你在 [目录](/docs/documentation/zh/can-kao/gitbook-ui.md#table-of-contents) GitBook 上的目录，并在 Git 到 GitBook 导入阶段用于重建你的目录结构，并重新协调来自仓库的后续更新与你在 GitBook 上的现有内容。
如果在确保你的所有文件都已包含在 `SUMMARY.md` 文件中后，GitBook 上仍然没有任何变化，请不要犹豫， [请联系支持团队](/docs/documentation/zh/bang-zhu/contact-support.md) 寻求帮助。
登录时我有重复的帐户
通常当你用于设置同步的 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。
不安全的文件正在阻止 Git Sync
如果你的空间包含 GitBook 认为无法安全导出的文件，Git Sync 可能会失败（例如 `.js`).
你可能会看到类似这样的错误：
> `文件“”无法导出，因为它被视为不安全`
必须从 GitBook 空间中移除不安全的文件，而不仅仅是从 Git 仓库中删除。
1. 在受影响的空间中创建一个变更请求
2. 打开 **文件** 标签页
3. 删除不安全的文件
4. 合并变更请求
一旦不安全的文件从空间中移除，Git Sync 应该会正常恢复。
---
# 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/wen-dang-ji-dai-ma/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.