supabase-auth-storage-realtime-core

Supabase Auth + Storage + Realtime Core

概览

实现将 Supabase 数据库转变为完整应用后端的三大支柱：用户身份验证（邮箱/密码、OAuth、魔法链接、会话生命周期）、文件存储（上传、下载、签名 URL、存储桶级 RLS 策略）以及实时订阅（Postgres 变更事件、客户端间广播、在线状态跟踪）。每项操作都通过 auth.uid() 与行级安全（RLS）集成。

本文件为以下各支柱提供精简的骨架；完整的复制粘贴式操作指南位于 references/ 中，让本文件保持简洁易读。

前提条件

• 已在 supabase.com/dashboard 创建 Supabase 项目
• 已安装 @supabase/supabase-js v2（npm install @supabase/supabase-js）
• 可从项目 Settings > API 获取 SUPABASE_URL 和 SUPABASE_ANON_KEY
• 对于 Python：pip install supabase（封装了 postgrest-py、gotrue-py、storage3、realtime-py）

操作说明

读取文件（Read），编辑或创建客户端和路由/组件代码（Write、Edit），并使用 grep 搜索项目（Grep），在创建新客户端之前复用已有的 Supabase 客户端。使用 Bash(npm:*) 安装 SDK，使用 Bash(supabase:*) 运行迁移/策略。

步骤 1：Auth — 注册、登录、OAuth

只初始化一次客户端，然后接入应用所需的流程。骨架如下：

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_ANON_KEY!)

// Email/password
await supabase.auth.signUp({ email, password })
await supabase.auth.signInWithPassword({ email, password })

// OAuth — redirect the user to data.url
const { data } = await supabase.auth.signInWithOAuth({ provider: 'google' })

// React to session changes (SIGNED_IN / SIGNED_OUT / TOKEN_REFRESHED)
supabase.auth.onAuthStateChange((event, session) => { /* update UI */ })

完整的 Auth 操作指南 — OAuth 回调、魔法链接、会话生命周期、密码重置：references/auth.md。Python：references/python-examples.md。

步骤 2：Storage — 上传、下载，通过存储桶策略确保安全

公共存储桶通过 CDN URL 提供服务；私有存储桶需要使用签名 URL。骨架如下：

// Upload to the signed-in user's own folder (RLS enforces ownership)
await supabase.storage.from('avatars').upload(`${userId}/avatar.png`, file, { upsert: true })

// Public URL (public bucket) vs. time-limited signed URL (private bucket)
supabase.storage.from('avatars').getPublicUrl(`${userId}/avatar.png`)
await supabase.storage.from('documents').createSignedUrl('reports/q4.pdf', 3600)

完整的 Storage 操作指南 — 下载、列出、删除，以及用于执行按用户访问控制的存储桶 RLS 策略：references/storage.md。Python：references/python-examples.md。

步骤 3：Realtime — Postgres 变更、广播、在线状态

有三种频道类型：数据库变更监听器、客户端间广播和在线状态。骨架如下：

const channel = supabase
  .channel('chat-room')
  .on('postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'messages' },
    (payload) => console.log('New:', payload.new))
  .subscribe()
// One-time table setup: ALTER PUBLICATION supabase_realtime ADD TABLE messages;
supabase.removeChannel(channel)  // clean up

完整的 Realtime 操作指南 — UPDATE/DELETE 过滤器、受 RLS 限定的订阅、广播和在线状态跟踪：references/realtime.md。Python：references/python-examples.md。

输出

• Auth：用户注册、密码登录、OAuth 流程（Google/GitHub）、魔法链接、通过 onAuthStateChange 管理会话生命周期、密码重置
• Storage：文件上传/下载、用于通过 CDN 提供资源的公共 URL、用于私有文件的限时签名 URL、使用 auth.uid() 和 storage.foldername() 的存储桶级 RLS 策略
• Realtime：带服务端过滤器的 Postgres 变更订阅、用于客户端间消息传递的广播频道、用于跟踪在线状态的在线状态功能

错误处理

错误	原因	解决方案
AuthApiError: User already registered	使用重复的邮箱注册	使用 signInWithPassword，或先检查用户是否已存在
AuthApiError: Invalid login credentials	邮箱或密码错误	验证凭据；检查邮箱确认状态
AuthApiError: Email not confirmed	用户尚未点击确认链接	使用 resend({ type: 'signup', email }) 重新发送
StorageApiError: Bucket not found	存储桶不存在	通过控制面板或 INSERT INTO storage.buckets 创建
StorageApiError: new row violates row-level security	RLS 策略阻止了此操作	确认 storage.objects 策略与用户和存储桶匹配
StorageApiError: The resource already exists	文件已存在且 upsert: false	设置 upsert: true 以覆盖文件，或使用唯一路径
Realtime: channel error 或 TIMED_OUT	网络问题或未启用 Realtime	检查是否针对目标表执行了 ALTER PUBLICATION supabase_realtime ADD TABLE
Realtime: too many channels	超出并发频道数限制	使用 removeChannel() 取消订阅未使用的频道

示例

端到端流程——登录、将头像上传到受用户 RLS 保护的文件夹、获取其公开 URL，以及订阅实时个人资料更新——请参阅 references/examples.md。每个步骤都组合了上述三个骨架，不涉及新的 API。

资源

• 身份验证指南
• 身份验证 API 参考
• 存储指南
• 存储访问控制
• Realtime 指南
• Realtime Postgres 更改
• Realtime 广播
• Realtime 在线状态

后续步骤

常见的 Supabase 错误及其调试方法，请参阅 supabase-common-errors。 数据库查询和 CRUD 操作，请参阅 supabase-crud-core。