Skip to content
Auth

用哪个包

When to use supabase-js, @supabase/ssr, or @supabase/server on the server.

当你在服务器上使用 JavaScript 调用 Supabase 时，有三个可选的包。它们不是互相替代的——@supabase/ssr 和 @supabase/server 都是建立在 supabase-js 之上，并解决不同的问题。本指南将帮助你选择合适的那个。

🌐 When you use Supabase from JavaScript on the server, there are three packages to choose from. They are not alternatives to each other — @supabase/ssr and @supabase/server both build on top of supabase-js and solve different problems. This guide helps you pick the right one.

用哪个包 #

🌐 Which package to use

最快的决策方式是看用户的身份是怎么到达你的代码的：

🌐 The quickest way to decide is by how the user's identity reaches your code:

  • 会话保存在 cookies 中（像 Next.js 或 SvelteKit 这样的 SSR 框架）→ 使用 @supabase/ssr。
  • 认证根据请求头 (Authorization: Bearer <jwt>) 到达 → 使用 @supabase/server。
  • 你想用基础客户端，还是自己处理认证 → 直接用 @supabase/supabase-js 就行。
软件包使用场景运行环境认证模式
@supabase/supabase-js当你只需要基础客户端，或者你自己管理认证浏览器和服务器你自己接入认证
@supabase/ssr用户会话存储在 cookies 中SSR 框架（Next.js、SvelteKit、TanStack Start）基于 Cookie 的会话，支持刷新令牌轮换
@supabase/server认证信息 每次请求都通过 headers 传递Edge Functions、Workers、Vercel、Bun，以及框架 API（Hono、H3、Elysia、NestJS）无状态 Bearer JWT + apikey

@supabase/supabase-js#

同构基础客户端。@supabase/ssr 和 @supabase/server 都封装了它——当你不需要任何一个封装的认证处理时，直接使用 supabase-js 就行。

🌐 The isomorphic base client. @supabase/ssr and @supabase/server both wrap it — reach for supabase-js directly when you don't need either wrapper's auth handling.

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_PUBLISHABLE_KEY!)

@supabase/ssr#

对于将用户会话存储在 Cookie 中的 SSR 框架。它可以读取和写入会话 Cookie，并处理刷新令牌的轮换，因此同一个用户和会话在客户端和服务器端都可以使用。

🌐 For SSR frameworks that store the user's session in cookies. It reads and writes session cookies and handles refresh-token rotation, so the same user and session are available on both the client and the server.

1
import { createServerClient } from '@supabase/ssr'
2
3
const supabase = createServerClient(
4
  process.env.SUPABASE_URL!,
5
  process.env.SUPABASE_PUBLISHABLE_KEY!,
6
  {
7
    cookies: {
8
      getAll() {
9
        // return the request's cookies
10
      },
11
      setAll(cookiesToSet) {
12
        // write cookies back on the response
13
      },
14
    },
15
  }
16
)

查看服务器端渲染指南了解特定框架的设置。

🌐 See the server-side rendering guide for framework-specific setup.

@supabase/server#

对于无状态、基于请求头的后端认证——适用于 Edge Functions、Workers 和框架 API。你可以声明谁可以调用某个接口，并获得可直接使用的上下文（一个遵循 RLS 的调用者范围客户端，以及一个管理员客户端）。它会帮你验证 JWT 并为你解析新的 API 密钥（SUPABASE_PUBLISHABLE_KEYS / SUPABASE_SECRET_KEYS）。

🌐 For stateless, header-based auth in backend runtimes — Edge Functions, Workers, and framework APIs. You declare who may call an endpoint and receive a ready-to-use context (a caller-scoped client that respects RLS, plus an admin client). It verifies JWTs and resolves the new API keys (SUPABASE_PUBLISHABLE_KEYS / SUPABASE_SECRET_KEYS) for you.

1
import { withSupabase } from '@supabase/server'
2
3
export default {
4
  fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
5
    // ctx.supabase is scoped to the caller and respects RLS
6
    const { data } = await ctx.supabase.from('todos').select()
7
    return Response.json(data)
8
  }),
9
}

查看 @supabase/server 参考 了解完整的 API。

🌐 See the @supabase/server reference for the full API.

高级：结合 @supabase/server 和 @supabase/ssr#

🌐 Advanced: Combining @supabase/server and @supabase/ssr

在基于 cookie 的框架中，你可以把两者结合起来——让 @supabase/ssr 管理 cookie 会话生命周期，并将解析后的 token 提供给 @supabase/server 的基础功能。这需要更多的设置，而且对第一方的更深入集成也在计划中。查看 @supabase/server SSR 框架指南。

🌐 In a cookie-based framework you can compose the two — let @supabase/ssr own the cookie session lifecycle and hand the resolved token to @supabase/server's primitives. This requires more setup, and deeper first-party integration is on the roadmap. See the @supabase/server SSR frameworks guide.

下一步 #

🌐 Next steps