如何提交一个好的错误报告

一个好的错误报告是我们能多快修复你问题的最大因素——无论是我们团队中的人还是我们用来分类的AI工具。多花五分钟写作可以将“无法工作”变成我们可以在一个会话中处理的内容。

此页面是规范的检查清单。相同的列表在我们的Discord #ask-for-help频道中作为帖子指南强制执行，并作为我们GitHub错误报告模板中的字段。

检查清单

当你提交一个TinaCMS错误时，包含以下所有相关内容：

1. 精确的错误信息

复制粘贴它，不要意译。我们搜索的是精确的字符串，AI代理也是基于模式匹配。一个报告说“React错误”比一个说“React错误#31：对象不能作为React子元素”要难处理得多。

2. 重现步骤

你点击的顺序。即使是一个编号的文本列表也足够了——你不需要视频。

图像插入损坏了，它只是崩溃。

❌ 图示：不好的例子 - 模糊的描述我们无法处理

1. 打开TinaCMS管理
2. 导航到任何有图像字段的页面（例如，英雄横幅块）
3. 点击图像字段 → “媒体库”标签
4. 从媒体库中选择任何图像
5. 点击“插入”

✅ 图示：好的例子 - 编号的逐步点击序列

3. 预期与实际行为

每个用一句话即可。告诉我们你是遇到了错误还是误解。

预期： 选定的图像被插入到字段中并且src字符串被保存。

实际： TinaCMS管理变为空白/白屏。控制台显示React错误#31。

4. 你的环境 - 包括任何非默认设置

这是大多数人忘记的，也是最常直接指向根本原因的。包括：

• tinacms和@tinacms/cli的版本
• 框架（Next.js, Astro, Remix等）
• TinaCloud或自托管
• 任何非默认设置 - 自定义MediaStore，自定义认证，自定义适配器，自托管设置等。

5. 我们可以重现的方法

一个我们可以克隆和运行的最小重现仓库是黄金标准。如果你需要一个骨架，npx create-tina-app@latest是一个好的起点。

针对Tina特定问题

如果你的问题涉及到schema或TinaCloud，还包括：

• schema文件的相关部分（你不必粘贴整个文件）
• 客户端ID - 针对任何TinaCloud相关问题

一个真实世界的例子

Issue #6679 - 从媒体库插入图像时使用自定义MediaStore出现React错误#31是一个好的报告在实践中的样子。它包括：

• 精确的错误字符串（“React错误#31：对象不能作为React子元素”）
• 重现步骤的编号列表
• 被传递的数据的形状（对象的键为{id, src, filename, directory, type, thumbnails}）
• 环境，包括自定义的GitHub支持的MediaStore适配器
• 对根本原因的猜测

该报告在一个会话中被调查、修复、测试并合并，因为检查清单的每一部分都在其中。对于一个模糊的“图像损坏”报告，它可能会被搁置。

提交地点

• Discord - TinaCMS Discord服务器中的#ask-for-help。最适合“这是一个错误还是我做错了什么？”的问题，以及社区帮助。
• GitHub Issues - tinacms/tinacms/issues用于确认的错误。我们的GitHub问题模板会提示你使用与此页面相同的检查清单。

为什么这有效

格式不是随意的。每个项目都对应于人类或AI代理在调查时所做的事情：

你写作的五分钟节省了数小时的来回，并让我们使用的代理分类你的报告，而不是等待它。