# 故障排除

## 我遇到了 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` 中指定的文件夹）直接在你的 git 仓库中创建。该文件是必需的，并用作文档的首页。更多细节请参阅我们的 `.gitbook.yaml`内容配置 [如果你的 Markdown 文件中有 YAML frontmatter，请使用](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/getting-started/git-sync/content-configuration).
* 检查器 [以确保它们有效。](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 文件。有关更多信息，请查看我们的 [如果你的 Markdown 文件中有 YAML frontmatter，请使用](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/getting-started/git-sync/content-configuration) 文档。

## 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` 文件](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/getting-started/content-configuration#summary)查找文件。

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

该文件的内容镜像你在 GitBook 上的 [目录（Table of Contents）](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/zi-yuan/gitbook-ui#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 同步。