故障排除
我遇到了 GitHub 同步错误
请确保只在你的仓库中创建 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 仓库中创建的。此文件是必需的，并将用作你的文档首页。有关更多详情，请参阅我们的 内容配置.如果你的 Markdown 文件中有 YAML frontmatter，请使用 代码检查器来确保它们是有效的。
GitBook 没有使用我的 docs 文件夹
docs 文件夹默认情况下，GitBook 会使用仓库根目录作为起点。可以指定一个特定目录来限定 markdown 文件的范围。有关更多详细信息，请查看我们关于 内容配置 的文档。
GitBook 正在创建新的 markdown 文件
在与 GitBook 同步并编辑时 当与现有的 Git 仓库同步并在 GitBook 中编辑时，GitBook 可能会创建新的 markdown 文件，而不是使用已有的文件。这样做是为了确保 GitBook 不会覆盖在你仓库中先前已存在的文件。
重定向无法正常工作
YAML 文件需要正确格式化，重定向才能生效。缩进或空白等错误可能会导致重定向无法工作。 验证你的 YAML 文件 可以确保重定向顺利工作。
设置重定向时，不要添加任何前导斜杠。例如，尝试重定向到 ./misc/support.md 将不起作用。
同样重要的是，只要某个路径存在页面，GitBook 就不会去查找可能的重定向。因此，如果你要将旧页面重定向到新页面，就需要删除旧页面，重定向才能生效。
我的仓库未列出
适用于 GitHub 仓库
请确保你已将 GitBook GitHub 应用安装到正确的位置（安装应用时，你可以选择安装到你的个人 GitHub，或你有权限的任何组织），并且已授予该应用正确的仓库权限。
适用于 GitLab 仓库
请确保你的访问令牌已配置以下访问权限：
apiread_repositorywrite_repository
在我的仓库中添加新文件后，GitBook 上没有任何反应
此部分专门处理以下情况的问题： SUMMARY.md 文件已存在
如果你的仓库不包含一个 SUMMARY.md 文件，GitBook 会在第一次同步时自动创建一个。这意味着，如果你在设置 Git 同步后至少在 GitBook 中编辑过一次内容，GitBook 应该已经自动创建了此文件。
如果在通过添加或修改 markdown 文件更新仓库后，你没有在 GitBook 上看到更新，且侧边栏在同步期间也没有显示错误，那么你修改的文件很可能没有列在 你的 SUMMARY.md 文件。
这可能是因为你手动创建了该文件，或者因为你在 GitBook 中进行了编辑，而同步中的 GitBook 到 Git 导出阶段为你创建了该文件。
此文件的内容反映了你在 目录 GitBook 上的内容，并在 Git 到 GitBook 的导入阶段用于重建你的目录，并将仓库中的后续更新与你在 GitBook 上的现有内容重新协调。
如果在确认所有文件都已包含在 SUMMARY.md 文件中后，GitBook 仍然没有任何反应，请随时 联系支持团队 寻求帮助。
GitHub 预览未显示
如果你的 GitHub 预览没有显示，可能是因为你的 GitSync 集成是在 2022 年 1 月之前配置的。在此日期之前配置的 GitSync 版本不包含 GitHub 预览。
你应该已经收到一条通知，要求你接受更新后的权限请求，以启用对 PR 的只读访问。
如果你没有收到该通知，排查时需要更新到新版本：
从你的组织中卸载 GitSync 集成。
使用更新后的权限重新安装新版本。
请注意，卸载 GitSync 集成后，需要在之前连接过的任何空间中重新配置该集成。
登录时可能出现重复账户
此错误通常发生在你用于设置同步的 GitHub 账户已经与另一个 GitBook 用户账户关联时。
要识别 GitHub 账户已关联到哪个 GitBook 账户，一个好方法是：
最后更新于
这有帮助吗？