@byted-supabase/supabase-js

English

面向 Web、微信、支付宝和 Doubao 的 Supabase JavaScript SDK runtime wrapper。业务代码继续使用官方 @supabase/supabase-js 的 createClient(url, key, options) 形态；本包只处理小程序运行时里的 request、storage、socket、本地文件上传和必要的 Web 标准兼容。

安装

pnpm add @byted-supabase/supabase-js @supabase/supabase-js
# 仅 Doubao 需要：
pnpm add @doubao-dev/framework@^0.6.0

@supabase/supabase-js 是 peer dependency。@doubao-dev/framework 是 Doubao 专用 optional peer dependency，当前按 0.6.x 验证。

初始化前准备

在客户端初始化 SDK 之前，请先准备好：

• SUPABASE_URL
• SUPABASE_ANON_KEY
• 目标 Supabase 分支里已经存在你要访问的表、RLS、Auth provider、Storage bucket、Edge Functions 等后端资源
• 小程序宿主里已配置好 request、upload、download、socket 域名白名单

这个包只初始化客户端和 runtime seam，不会替你创建数据库、函数、bucket 或 Auth 配置。

初始化

普通 Web、微信、支付宝场景直接使用默认入口即可：

import { createClient, getRuntimeInfo } from '@byted-supabase/supabase-js'

const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  auth: { detectSessionInUrl: false },
})

const runtimeInfo = getRuntimeInfo(supabase)

不传 runtime 时，默认入口会在识别到宿主 marker/能力时自动选择微信、支付宝或 Doubao runtime；没有识别到小程序宿主时，保持官方 Supabase runtime 行为。Doubao 新代码仍建议显式注入宿主 API，而不是依赖 legacy/global marker。不要传 runtime: 'auto'。

Doubao 建议显式注入宿主 API：

import * as doubaoApi from '@doubao-dev/framework/api'
import { createClient } from '@byted-supabase/supabase-js/core'
import { doubaoAdapter } from '@byted-supabase/supabase-js/mini/adapters/doubao'

const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  runtime: doubaoAdapter(doubaoApi),
  auth: { detectSessionInUrl: false },
})

入口边界：

• 默认业务入口：@byted-supabase/supabase-js
• 需要显式注入 adapter 或做单端最小引入时：@byted-supabase/supabase-js/core
• @byted-supabase/supabase-js/mini-client 仅用于 demo、install-smoke 或诊断场景，不是业务默认 client

常用方式

数据库、RPC、Functions、Storage、Realtime 继续使用官方 Supabase API。例如：

const { data, error } = await supabase
  .from('todos')
  .select('id,title,status')
  .limit(10)

if (error) throw error

小程序专属能力只放在 helper 边界。

平台登录

import { login } from '@byted-supabase/supabase-js/mini/auth'

const { data, error } = await login(supabase, {
  rawOptions: {
    timeout: 10000,
  },
})

if (error) throw error

login() 会先向宿主拿一次性登录 code，再按当前 runtime 走默认的 Supabase Auth 链路：

• 微信：wx.login -> supabase.auth.signInWithIdToken()
• 支付宝：my.getAuthCode -> supabase.auth.signInWithIdToken()
• Doubao：官方 login() -> /auth/v1/integrations/doubao/mcp/login -> /fetch-token -> 官方 supabase.auth.setSession()

默认链路对照：

| Runtime | 宿主 code | SDK 默认行为 | Supabase 终点 | | --- | --- | --- | --- | | wechat | wx.login | supabase.auth.signInWithIdToken() | 对应 mini-app provider | | alipay | my.getAuthCode | supabase.auth.signInWithIdToken() | 对应 mini-app provider | | doubao | login() -> login_code | /auth/v1/integrations/doubao/mcp/login -> /fetch-token -> auth.setSession() | Doubao Auth integration |

这表示 SDK 默认链路，不表示你的 Auth 后端已经接通全部 provider：

• 微信、支付宝：只有后端已接通对应 provider 时，默认链路才会直登成功。
• Doubao：需要已开启 Doubao Intelligent Service，且 runtime 能解析到宿主 appId。

后端暂未接通 provider，或你要自定义验签、账号绑定、session 签发时，改用 getMiniAppAuthCode() + Edge Function / 可信后端 exchange。

小程序本地文件上传

import { uploadFile } from '@byted-supabase/supabase-js/mini'

const { data, error } = await uploadFile(supabase, {
  bucket: 'avatars',
  path: `users/${userId}/avatar.png`,
  filePath: pickedFile.filePath,
  contentType: pickedFile.type || 'image/png',
  upsert: true,
})

if (error) throw error

小程序本地 filePath 不要直接传给官方 storage.upload()。

FAQ

这个包会帮我初始化 Supabase 后端资源吗？

不会。它只负责客户端初始化和 runtime 适配。表结构、函数、bucket、RLS、Auth provider 和宿主白名单都需要你自己先准备好。

我需要手动传 runtime 吗？

大多数情况下不需要。Web、微信、支付宝通常直接省略 runtime；Doubao 在宿主 marker 可见时也可能被默认入口识别，但新代码仍建议显式传 doubaoAdapter(doubaoApi)。如果你使用 @byted-supabase/supabase-js/core，请传 adapter 对象，不要传内置 runtime 字符串。

我该用默认入口、/core，还是 mini-client？

默认先用 @byted-supabase/supabase-js。只有你想显式注入 adapter、固定单一宿主或做最小引入时，才切到 @byted-supabase/supabase-js/core；/core 保持官方 Web/Node/SSR 行为，本身不内置 runtime 字符串分发。mini-client 只用于 demo、install-smoke 或诊断，不是业务默认入口。

我可以继续用官方 supabase-js API 吗？

可以。默认应该优先使用官方 SupabaseClient、Auth、Storage、Functions 和 Realtime API。本包只补 runtime seam，并额外提供 mini/auth 和 uploadFile 这类宿主专属 helper。

为什么平台登录失败？

常见原因是：

• 目标 provider 没有在 Supabase Auth 后端开启
• 你的后端版本还不支持这个 provider
• 宿主拿到的 code 已过期或无效
• Doubao runtime 无法解析宿主 appId
• 小程序宿主拦截了 request 域名，导致 Auth 请求根本没到后端

如果当前 provider 还没接通，或者你就是要做自定义验签、账号绑定和 session 签发流程，先用 getMiniAppAuthCode() 获取 code，再交给你自己的 Edge Function 或可信后端处理。

什么时候该回退到 getMiniAppAuthCode() + 后端 exchange？

这些场景直接回退，不要硬走默认直登：

• 微信、支付宝对应 provider 还没在目标 Supabase/Auth 后端接通
• 你要做自定义验签、账号绑定、session 签发或风控
• Doubao provider 还没接通，或 runtime 拿不到宿主 appId

推荐步骤：

• 先用 getMiniAppAuthCode() 获取宿主 code
• 再通过 supabase.functions.invoke(...) 或可信后端完成 exchange
• 最后调用官方 supabase.auth.setSession()

为什么请求、上传或 Realtime 只在小程序里失败？

先检查宿主平台的域名白名单和平台限制，不要先假设是 SDK bug。通常要分别核对：

• request 域名
• upload 域名
• download 域名
• socket 域名

官方文档：

• Doubao JS API: https://developer.doubao.com/docs/js-api/
• 支付宝 Mini API: https://opendocs.alipay.com/mini/api
• 微信小程序 API: https://developers.weixin.qq.com/miniprogram/dev/api/

为什么支付宝里 request-methods 看起来通过，但 PostgREST PATCH 或 Storage remove 仍可能失败？

这两类结论不是一回事。request-methods 或 functions-methods 只能证明宿主大致能把请求发出去并拿到 HTTP 响应，不代表所有 Supabase 业务语义都稳定等价。

我们在支付宝小程序实测里见过两类现象：

• PATCH /rest/v1/... 返回 200，但后续 select 读到的数据仍是旧值
• DELETE /storage/v1/object/<bucket> 携带 { prefixes: [...] } 这类 JSON body 时，Storage 服务返回 body must be object

如果同一条 Supabase 路径在 curl、Node 或其他宿主里正常，而支付宝 runtime trace 也已经显示 SDK 传给宿主的是对象 body，就应优先把它归类为宿主 request 语义边界，而不是默认判定为 Supabase 后端没初始化或 SDK 仍在发错 body。

推荐做法：

• 支付宝里的关键写操作不要依赖直连 PostgREST PATCH
• 支付宝里的 Storage 批量删除不要依赖 DELETE + JSON body
• 优先改成 POST 形态的 supabase.rpc(...) 或 supabase.functions.invoke(..., { method: 'POST' })，由服务端再执行真正的 update/remove

客户端能放 service_role 或平台密钥吗？

不能。客户端只应使用 anon key。平台密钥、service_role、签名逻辑、证书和回调验签必须放在可信后端。

Contribution

贡献说明见 CONTRIBUTING.md。

Code Of Conduct

社区协作约定见 CODE_OF_CONDUCT.md。

Security

如果你发现潜在安全问题，请通过 ByteDance Security 的 security center 或 vulnerability reporting email 联系我们。

请不要公开提交安全漏洞 issue。

License

MIT