用途
Supabase Troubleshooting 是一个用于调试和修复 Supabase 常见问题的技能。当开发者在 Supabase 项目中遇到认证错误、RLS 策略问题、连接故障或性能瓶颈时，可借助该技能进行排查与修复。
主要能力
快速诊断
提供症状与可能原因的对照表，例如：返回空数据通常由 RLS 策略阻止访问导致；"Not authorized" 表示缺少或无效的认证令牌；"JWT expired" 表示令牌需要刷新；查询缓慢通常源于缺少索引或 RLS 子查询；连接被拒绝可能是 URL 错误或服务宕机；"Duplicate key" 表示唯一约束冲突；函数超时可能是冷启动或计算量过大。
认证问题排查
覆盖 "Invalid login credentials"（检查邮箱格式、用户是否存在）、"Email not confirmed"（重发确认邮件或管理员确认）、"JWT expired"（强制刷新会话、监听令牌刷新事件）、会话不持久（检查存储配置、避免创建多个客户端实例）等场景。
RLS 问题排查
包括检查 RLS 是否启用、查看现有策略、以指定用户身份测试策略、调试 "violates row-level security policy" 错误，以及优化 RLS 性能（使用 (SELECT auth.uid()) 缓存结果、为 RLS 列添加索引）。
数据库问题排查
涵盖唯一约束冲突（改用 upsert）、外键冲突（确保父行存在）、查询返回陈旧数据（禁用缓存、强制获取新数据）等。
连接问题排查
包括 "Failed to fetch" 网络错误（检查 URL 与 API 密钥、测试连接）、本地开发连接（检查 Docker 与 Supabase 状态、重启服务）、CORS 问题（边缘函数需包含 CORS 头并处理 OPTIONS 预检请求）。
存储问题排查
包括上传失败（根据错误信息判断文件过大、类型无效或 RLS 阻止）、存储 RLS 调试（查看存储策略、允许认证用户上传到自己的文件夹）。
边缘函数问题排查
包括函数超时（504，检查阻塞操作、注意 CPU 与墙钟时间限制）、函数错误（500，使用 try-catch 包裹）、密钥不可用（检查并设置密钥，更改立即生效无需重新部署）。
实时问题排查
包括未收到事件（检查表是否启用实时、订阅状态、RLS 是否允许 SELECT）、重复订阅错误（避免对同一频道调用两次 subscribe、重新订阅前先清理）、连接过多（组件卸载时清理频道）。
性能优化
包括慢查询（使用 EXPLAIN ANALYZE、添加索引、检查顺序扫描）、高连接数（检查连接、无服务器场景使用连接池的事务模式）、优化 RLS 查询（避免热路径中的子查询、使用 security definer 函数）。
常见错误码参考
提供 PostgREST 错误（PGRST116、PGRST205、PGRST301）、PostgreSQL 错误（22P02、23503、23505、42501、42703、42P01、08P01）以及认证错误（Invalid API key、JWT expired、Invalid login credentials）的说明与解决方案。
使用方式
该技能以文档形式提供排查指南，包含可直接参考的代码片段、SQL 语句和命令行操作。开发者可根据具体症状查阅对应章节，按提供的步骤进行诊断和修复。
适用场景
适用于使用 Supabase 进行应用开发的开发者，在遇到认证、数据库、RLS、存储、边缘函数、实时订阅或性能相关问题时使用。
限制
该技能为故障排查参考文档，具体效果取决于实际项目配置与环境。部分操作（如管理员确认用户、查看 auth.users）需要相应权限。