studio-error-handling

Studio 错误处理模式

完整文档和代码示例：apps/studio/components/interfaces/ErrorHandling/README.md

工作原理

分类在数据层进行：data/fetchers.ts 中的 handleError 会将错误消息与 ERROR_PATTERNS 匹配，并抛出匹配的错误子类（例如 ConnectionTimeoutError extends ResponseError）。组件（ErrorMatcher）从实例中读取 errorType 并进行 O(1) 查找，不会进行正则匹配。

handleError() → throws ConnectionTimeoutError → React Query catches → ErrorMatcher reads errorType → renders troubleshooting

关键文件

文件	用途
data/error-patterns.ts	{ pattern, ErrorClass } 数组——正则表达式位于此处
types/api-errors.ts	错误类、KnownErrorType 联合类型、ClassifiedError 类型
ErrorMatcher.tsx	组件——读取 errorType、查找映射并进行渲染
error-mappings.tsx	Record<KnownErrorType, { id, Troubleshooting: ComponentType }>
errorMappings/ConnectionTimeout.tsx	疑难排解组件示例
TroubleshootingSections.tsx	可复用的手风琴分区组件
TroubleshootingAccordion.tsx	带遥测功能的手风琴包装组件

使用哪个组件

情况	使用
查询失败，页面或分区无法渲染其数据（默认情况——Studio 中的大多数场景）	components/ui/AlertError 中的 AlertError
错误可能属于带有专属疑难排解步骤的已分类类型（例如连接超时）	components/interfaces/ErrorHandling/ErrorMatcher 中的 ErrorMatcher——为未分类情况传入 fallback
修改操作失败	修改操作 Hook 默认的 onError Toast（来自 sonner 的 toast.error）——不要渲染警告框（参见 studio-queries）

AlertError（默认）

渲染一个警告 Admonition，显示错误消息和通用的“尝试刷新／联系支持”说明，以及一个预先填入 projectRef、subject 和错误消息的联系支持按钮。

if (isError) return <AlertError error={error} subject="Failed to retrieve invoices" />

• subject 是便于用户理解的标题，格式为 Failed to <verb> <thing>。在项目上下文中传入 projectRef，以便预先填入支持表单。
• error 是 React Query 错误对象（任何带有 message 的对象）；503 响应会自动改写措辞。
• 使用 additionalActions 添加重试或导航按钮；只有在支持确实无法提供帮助时（例如用户输入错误）才使用 hideContactSupport。
• 对页面或分区的主要数据，优先使用提前返回的形式；对于不应阻断页面其他内容的次要面板，使用内联的 {isError && <AlertError … />}。

ErrorMatcher（已分类错误）

当数据层可能已将错误归类为带有专用疑难排解 UI 的 KnownErrorType 时使用。它会从错误实例中读取 errorType 并渲染映射的 Troubleshooting 组件；如果没有映射，则渲染 fallback。目前，此组件已用于表格编辑器侧边栏；为新的错误类型添加疑难排解功能时应使用它，而不是将其作为 AlertError 的通用替代品。

ErrorMatcher 的用法

传入 React Query 中的完整错误对象，而不是 error.message：

{
  isError && (
    <ErrorMatcher title="Failed to load tables" error={error} supportFormParams={{ projectRef }} />
  )
}

不要这样做

• 不要将 error.message 传给 ErrorMatcher，而要传入完整的 error 对象，以保留类信息。
• 不要将正则表达式模式放在 error-mappings.tsx 中，它们应放在 data/error-patterns.ts 中。
• 不要使用 Object.assign 设置 errorType，而应抛出正确的子类。
• 不要为支持表单传入原始 URL 字符串，而要使用 supportFormParams={{ projectRef }}。
• 不要将页面标题放在错误映射中，它应由 <ErrorMatcher> 的调用方提供。
• 不要向故障排除组件添加回调属性（onDebugWithAI、onRestartProject），而应在组件内部使用钩子。