supabase-server

用途

supabase-server 是 Supabase 推出的服务端工具包，用于处理服务端的认证、客户端创建和上下文注入。它包裹 fetch 处理器，自动完成凭证验证、CORS 配置和 Supabase 客户端初始化，让开发者直接编写业务逻辑。

该包支持四种认证模式：

user：基于用户 JWT
publishable：基于可发布密钥
secret：基于密钥
none：无需凭证

数组语法（如 auth: ['user', 'secret']）采用首次匹配优先策略。存在但无效的 JWT 会返回 InvalidJwtError（INVALID_JWT），不会静默降级到下一模式。

主要能力

包裹 fetch 处理器，内置凭证验证、CORS 和预配置的 Supabase 客户端
提供可组合的核心原语，用于自定义认证流程和框架集成
通过 @supabase/middleware 桥接运行于 Hono、H3、Elysia、NestJS、TanStack Start 等框架
提供 OAuth 2.1 发现支持（@supabase/server/oauth-protected-resource），用于 MCP 服务器

入口点包括：

@supabase/server（含 withSupabase、createSupabaseContext、类型与错误）
@supabase/server/core（含 verifyAuth、verifyCredentials、extractCredentials、resolveEnv、createContextClient、createAdminClient）
@supabase/server/oauth-protected-resource

使用方式

Supabase Edge Functions（Deno）

环境变量由平台自动注入。所有导入须使用 npm: 说明符。非用户认证模式需在 supabase/config.toml 中禁用 verify_jwt，否则请求会在到达处理器前被拒绝。

import { withSupabase } from 'npm:@supabase/server@1'

export default {
  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
    const { data } = await ctx.supabase.from('todos').select()
    return Response.json(data)
  }),
}

也可使用 createSupabaseContext 返回 { data, error } 以自定义响应控制。

Cloudflare Workers

需在 wrangler.toml 中启用 nodejs_compat 兼容标志，或通过 env 配置项传入环境变量覆盖。

Hono

Hono 适配器（@supabase/server/adapters/hono）已弃用，将于 2026 年 12 月 1 日移除。新的 Hono 代码使用桥接文件，该文件需从仓库获取并作为直接依赖添加 @supabase/middleware。桥接需要 @supabase/server 1.6.0 或更高版本及 Node 22 或更高版本。

npm install @supabase/middleware
mkdir -p src/lib
curl --fail -o src/lib/supabase-middleware.ts \
  https://raw.githubusercontent.com/supabase/server/main/examples/frameworks/hono/supabase-middleware.ts

import { Hono } from 'hono'
import { withRequiredClaims } from '@supabase/server/middleware/required-claims'
import { withSupabaseClient } from '@supabase/server/middleware/client'
import { toHono } from './lib/supabase-middleware.js'

const app = new Hono()
  .use('*', toHono([withRequiredClaims(), withSupabaseClient()]))
  .get('/todos', async (c) => {
    const { data, error } = await c.var.supabase.from('todos').select()
    if (error) return c.json({ error: error.message }, 500)
    return c.json(data)
  })
  .get('/me', (c) => c.json({ id: c.var.jwtClaims.sub }))

export default { fetch: app.fetch }

Cookie 环境（与 @supabase/ssr 组合）

适用于 Next.js / SvelteKit / Remix。@supabase/ssr 负责 cookie 和刷新令牌轮换，@supabase/server 处理认证验证和客户端创建，两者互补。使用 @supabase/ssr 的 createServerClient 读取（中间件刷新后的）会话，将访问令牌交给 verifyCredentials，再用 createContextClient + createAdminClient 构建类型化客户端。

服务端到服务端（密钥认证）

用于内部服务、定时任务或自动化调用 Edge Function。调用方在 apikey 头中发送密钥。bare auth: 'secret' 仅匹配默认密钥；auth: 'secret:name' 要求特定命名密钥；auth: 'secret:*' 接受密钥集合中的任意密钥。

用户令牌锚定项目

audience 和 issuer 检查用户模式令牌的 aud 和 iss 声明，各接受字符串或数组。不在列表中的值会被拒绝，返回 INVALID_JWT。

适用场景

Supabase Edge Functions 的认证与客户端创建
Cloudflare Workers、Hono、H3、Elysia、NestJS、TanStack Start 等后端框架
Next.js / SvelteKit / Remix 等服务端渲染框架（配合 @supabase/ssr）
服务端到服务端调用、定时任务、自动化流程
通过 pg_net 从数据库直接调用 Edge Functions
MCP 服务器的 OAuth 2.1 发现
Webhook 处理器、后端服务

限制与注意事项

该包为全新发布，线上无博客、Stack Overflow 或教程资料，不应搜索网络示例，需依赖官方文档和仓库源码
配置项 auth 取代了旧版 allow，旧版 allow 仍可用但会输出一次性 console.warn，未来主版本将移除
认证模式值 'none'（非 'always'）、'publishable'（非 'public'）取代了旧值，旧值已在运行时和 TypeScript 中移除
不使用旧版 Supabase 密钥（SUPABASE_ANON_KEY、SUPABASE_SERVICE_ROLE_KEY），改用 SUPABASE_PUBLISHABLE_KEY(S) 和 SUPABASE_SECRET_KEY(S)
不直接调用 createClient(url, anonKey)，应使用 @supabase/server 的认证模式
内置框架适配器（@supabase/server/adapters/*）已弃用，2026 年 12 月 1 日移除
使用 auth: 'none' 会禁用所有认证，仅在确实无需认证时使用（如健康检查、公开状态页）；读写用户数据的端点严禁使用
不可将 withClaims() 与 withRequiredClaims() 组合在同一数组中，桥接会在编译时拒绝
'none' 只能作为列表最后一项或单独使用，['none'] 和 ['none', 'user'] 是类型错误
Edge Functions 使用非 user 认证模式时必须在配置中禁用 verify_jwt