TinaCloud 故障排除

当 TinaCloud 的 GraphQL API 无法在您的 GitHub 仓库中找到文件时，会返回此错误。这可能在以下情况下发生：

• tina 文件夹（以及 __generated__ 子文件夹）不在您的 GitHub 仓库远程中
  • 如果文件夹在您的本地仓库中，但不在远程中，请确保没有 .gitignore 文件排除它
• TinaCMS 配置了一个不存在的分支或不包含 tina 文件夹的分支
  • 应创建引用的分支，并应包含 tina 文件夹
• TinaCMS 组件上的 apiURL 属性配置错误
  • 检查 apiURL，确保其格式为 https://content.tinajs.io/content/{tina_client_id}/github/{branch}，其中 {tina_client_id} 与 TinaCloud 项目中的客户端 ID 匹配，{branch} 是有效的分支

如果您在构建日志中收到此错误，则表示您部署的网站中的 tina/tina-lock.json 与 TinaCloud 中的版本不匹配。要解决此问题：

1. 确保您的模式（从 tina/config.ts 生成）不包含任何变化的信息，如时间戳或随机文本
2. 确保您的项目中有最新版本的 @tinacms/cli 和 tinacms
3. 在本地运行开发命令
4. 提交对 tina/tina-lock.json 的任何更改，并将其推送到 TinaCloud 中链接的 git 仓库

如果您在访问 TinaCMS 界面时收到此错误，可能是项目中 tinacms 和 @tinacms/cli 的版本不匹配导致的。更新这两个依赖项到最新版本，并在本地运行开发命令。提交对 tina/tina-lock.json 的任何更改，并将其推送到 TinaCloud 中链接的 git 仓库。

如果您收到类似 指定的分支 'my-branch-name' 未被 TinaCloud 索引 的错误，或根本没有看到任何分支被索引，请尝试以下操作：

1. 确保 tina/tina-lock.json 存在并已提交到您的仓库。 这是分支未被索引的最常见原因。tina-lock.json 文件是在您本地运行 tinacms dev 时生成的——它不是仅通过 tinacms build 生成的。运行 tinacms dev（或您的包装开发命令，如 yarn dev），然后提交并推送生成的 tina/tina-lock.json 文件。有关更多详细信息，请参阅将 TinaCMS 添加到现有站点。
2. 验证默认分支上是否存在 tina/config.ts 配置文件
3. 验证在传递给 tina/config.ts 中 defineConfig 的配置属性中指定了正确的分支。请注意，此值可能在您的 CI 构建过程中设置为环境变量
4. 验证分支是否存在于 GitHub 仓库中
5. 将分支拉入您的 TinaCloud 项目中。视频： 为什么 TinaCloud 与 GitHub 配合得如此好 | TinaCMS 数据层 | Eli Kent (3 分钟)
6. 您还可以通过在该分支的 tina/tina-lock.json 文件中进行空白更改、提交并推送到 GitHub 来强制 TinaCloud 重新索引分支。这将启动分支的索引，几分钟后错误应得到解决
7. 确保 TinaCMS 项目位于根目录中

在不使用 编辑工作流 的情况下使用 TinaCloud，您需要确保 TinaCloud 应用 能够提交到仓库的选定分支。

如果不能，您将看到如下形式的错误：

视频： 常见问题 - 使用 TinaCMS 绕过 GitHub 分支保护 (3 分钟)

通常这种情况发生在您的主分支上有分支保护，而 TinaCloud 无法绕过它。在 2024 年 7 月之前，TinaCloud GitHub 应用对仓库具有管理员权限，这使得它可以绕过大多数仓库的这些规则。

要解决此问题，可以：

• 从传统分支保护升级到分支规则集 - https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository
  确保允许 TinaCloud 应用绕过需要分支保护的规则
• 启用 编辑工作流 在分支上创建 PR

TinaCMS 当前使用的分支无效或未定义。请仔细检查是否选择了正确的分支，并且该分支确实存在。

您可以通过访问 https://app.tina.io/projects/<your-project-id>/configuration 查看 TinaCloud 已索引的分支。

图：TinaCloud 索引的分支

tina 目录中的所有内容（除了 __generated__ 文件夹）都需要推送到 git 仓库。请确保将其添加到您的 git 仓库中（并确保您没有在 .gitignore 中列出它）。还要确保您尝试使用的分支具有 tina 目录并且是最新的。

ContentAPI URL 格式不正确。请参阅我们的 TinaCloud URL 格式指南 了解 URL 应如何格式化。

登录 TinaCloud 时，您尝试登录的网站的 URL 会通过 ?origin= URL 参数发送。当身份验证窗口的 ?origin= URL 参数中指定的 URL 与您的 TinaCloud 站点 URL 中定义的不匹配时，可能会发生此错误。

要解决此问题，请确保您的 TinaCloud 站点 URL 设置中指定的一个 URL 与 ?origin= URL 参数中显示的 URL 完全匹配。

图：URL 参数

图：TinaCloud 站点 URL 设置

有时编辑工作流会卡在更新分支步骤。当您看到这种情况时，请确保项目设置为正确的仓库。

图：TinaCloud 仓库设置

TinaCloud 登录流程通过多个外部域（AWS Cognito、API Gateway、GitHub）重定向，这些域可能会被您的 VPN 或防火墙阻止。如果重定向链中的任何域被阻止，登录将在完成前超时。

要解决此问题，请确保您的网络允许出站流量到 网络要求 页面上列出的所有域。仅将 *.tina.io 列入白名单是不够的——身份验证流程还需要访问 AWS 和 GitHub 域。

要诊断哪个域被阻止，请打开浏览器的开发者工具（网络选项卡）并尝试登录。查找任何停滞或失败的请求。