TinaCloud 常见错误有哪些？

1. 如何解决 Unable to find record 'tina/__generated__/_graphql.json' 错误？

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

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

2. 如何解决 The local GraphQL schema doesn't match the remote GraphQL schema 错误？

如果在构建日志中出现此错误，则表示您部署的网站中的 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 仓库。

3. 如何解决由未索引的分支引起的错误？

如果收到类似 The specified branch, 'my-branch-name', has not been indexed by TinaCloud 的错误，或根本没有看到索引的分支，请尝试以下操作：

1. 验证默认分支上的 tina/config.ts 中是否存在配置文件
2. 验证在传递给 tina/config.ts 中 defineConfig 的配置属性中指定了正确的分支。注意，此值可能在您的 CI 构建过程中设置为环境变量
3. 验证分支是否存在于 GitHub 仓库中
4. 将分支拉入您的 TinaCloud 项目中。

   视频：TinaCloud - 如何索引缺失的分支（3 分钟）
5. 您还可以通过在该分支的 tina/tina-lock.json 文件中进行空白更改、提交并推送到 GitHub 来强制 TinaCloud 重新索引分支。这将启动分支的索引，几分钟后错误应得到解决
6. 确保 Tina 项目位于根目录中

4. 如何解决 There was a problem saving your document 错误？

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

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

Tina 在更新页面时捕获了一个错误：

错误：无法获取，错误：
    在 PUT 中出错，路径为 src/pages/some-page.md

视频：常见问题 - 使用 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

5. 如何解决 Invalid or undefined branch 错误？

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

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

图：TinaCloud 索引的分支

6. 如何解决 tina directory not pushed to git 错误？

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

7. 如何解决 API URL is misformatted 错误？

ContentAPI URL 格式不正确。有关 URL 应如何格式化的信息，请参见此处。

8. 如何解决 Invalid 错误？

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

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

图：URL 参数

图：TinaCloud 站点 URL 设置