保护边缘功能

通过声明它接受哪些凭据来保护 Edge 函数。GitHub 上 @supabase/server 包 的 withSupabase 封装器会根据你设置的 auth 模式检查每个调用者。你的处理器会在 ctx 上收到一个预配置的 Supabase 客户端。

🌐 Secure an Edge Function by declaring which credentials it accepts. The withSupabase wrapper from the @supabase/server package on GitHub checks each caller against the auth mode you set. Your handler receives a preconfigured Supabase client on ctx.

• 选择一种认证模式 对比了四种模式。如果你不确定你的函数需要哪一种，可以从这里开始。
• 保护你的函数 对每种模式都有示例，还说明了如何组合模式并自定义错误响应。
• 环境变量 列出了 @supabase/server 从环境中读取的内容。

选择一种认证模式 #

🌐 Choose an auth mode

每种模式都会命名调用者必须提供的凭证。withSupabase 接受四种：

🌐 Each mode names the credential a caller must present. withSupabase accepts four:

有关授权头和 verify_jwt 平台检查的工作原理，请参见 Authorization headers。

🌐 For how authorization headers and the verify_jwt platform check work, see Authorization headers.

保护你的功能 #

🌐 Secure your function

下面的每个部分都会讲一个模式，然后讲如何组合模式并塑造你自己的错误响应。每个示例都会把处理器包在 withSupabase 中，并从 ctx 获取它的 Supabase 客户端。

🌐 Each of the following sections covers one mode, then how to combine modes and shape your own error response. Every example wraps the handler in withSupabase and reads its Supabase client from ctx.

已认证用户调用 #

🌐 Authenticated user calls

当已登录的用户调用一个函数时，请求会在 Authorization 头中携带用户的会话 JWT。你的应用通常通过 supabase.functions.invoke 发起这个调用。使用 auth: 'user' 来获取一个根据调用者的行级安全（RLS）策略范围的 ctx.supabase。

🌐 When a signed-in user calls a function, the request carries the user's session JWT on the Authorization header. Your app usually makes that call through supabase.functions.invoke. Use auth: 'user' to get a ctx.supabase scoped to the caller's Row Level Security (RLS) policies.

默认是 verify_jwt = true，所以平台会在你的处理程序运行之前验证 JWT。对面向用户的功能保持开启。在开发期间为了消除 401 而关闭它，会移除平台的检查，只剩下 withSupabase 来验证调用者。

🌐 The default is verify_jwt = true, so the platform validates the JWT before your handler runs. Leave it on for user-facing functions. Turning it off to clear a 401 during development removes the platform's check, leaving withSupabase as the only thing that verifies the caller.

1
import { withSupabase } from 'npm:@supabase/server@1'
2
3
export default {
4
  fetch: withSupabase({ auth: 'user' }, async (_req, ctx) => {
5
    const { supabase, supabaseAdmin, userClaims, jwtClaims, authMode } = ctx
6
    // supabase       — RLS-scoped to the authenticated user
7
    // supabaseAdmin  — bypasses RLS (service role)
8
    // userClaims     — user identity from JWT (id, email, role)
9
    // jwtClaims      — full JWT claims
10
    // authMode       — which auth mode matched
11
12
    // your business logic goes here
13
    return Response.json({ email: ctx.userClaims?.email })
14
  }),
15
}

在处理已登录的调用者时，使用 ctx.supabase。它会将他们的 RLS 策略应用到每个查询。仅在工作必须跨越这些策略时才使用 ctx.supabaseAdmin。

🌐 Reach for ctx.supabase when the handler serves the signed-in caller. It applies their RLS policies to every query. Use ctx.supabaseAdmin only for work that has to cross those policies.

服务间调用 #

🌐 Service-to-service calls

Cron 作业、workers、pg_net 和其他 Edge Functions 都是通过 apikey 头部的密钥来调用，而不是使用用户 JWT。禁用 verify_jwt 并使用 auth: 'secret'。这个封装会将密钥与你项目的 API 密钥中名为 default 的密钥进行验证，并为你的处理程序 ctx.supabaseAdmin 提供特权操作。

🌐 Cron jobs, workers, pg_net, and other Edge Functions make calls with a secret key on the apikey header rather than a user JWT. Disable verify_jwt and use auth: 'secret'. The wrapper validates the key against the secret key named default in your project's API keys, and gives your handler ctx.supabaseAdmin for privileged work.

1
import { withSupabase } from 'npm:@supabase/server@1'
2
3
export default {
4
  fetch: withSupabase({ auth: 'secret' }, async (_req, ctx) => {
5
    // your business logic. ctx.supabaseAdmin bypasses RLS
6
    return Response.json({ ok: true })
7
  }),
8
}

公共函数 #

🌐 Public functions

对于一个真正的公共功能，比如健康检查，使用 auth: 'none' 和 verify_jwt = false，这样匿名调用者也能访问处理程序。

🌐 For a genuinely public function, such as a health check, use auth: 'none' with verify_jwt = false so anonymous callers can reach the handler.

1
[functions.health]
2
verify_jwt = false

1
import { withSupabase } from 'npm:@supabase/server@1'
2
3
export default {
4
  fetch: withSupabase({ auth: 'none' }, async () => {
5
    // your business logic
6
    return Response.json({ ok: true })
7
  }),
8
}

auth: 'none' 接受所有调用者。有关自行验证调用者的函数，请参见本页的 外部 Webhook 部分。

外部网络钩子 #

🌐 External webhooks

像 Stripe 或 GitHub 这样的外部提供商不会发送 Supabase 凭据。他们会用自己的共享密钥对请求体进行签名。使用 auth: 'none' 来跳过封装器的凭据检查，然后在处理器内验证提供商的签名。保留 verify_jwt = false。

🌐 External providers such as Stripe or GitHub don't send Supabase credentials. They sign the request body with their own shared secret. Use auth: 'none' to skip the wrapper's credential check, then verify the provider's signature inside the handler. Keep verify_jwt = false.

1
import { withSupabase } from 'npm:@supabase/server@1'
2
import Stripe from 'npm:stripe'
3
4
const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!)
5
6
// Deno has no synchronous Node crypto, so signature verification must go through
7
// Stripe's SubtleCryptoProvider. The synchronous `constructEvent()` throws
8
// "SubtleCryptoProvider cannot be used in a synchronous context" on this runtime.
9
const cryptoProvider = Stripe.createSubtleCryptoProvider()
10
11
export default {
12
  fetch: withSupabase({ auth: 'none' }, async (req, ctx) => {
13
    const signature = req.headers.get('stripe-signature') ?? ''
14
    const body = await req.text()
15
16
    try {
17
      await stripe.webhooks.constructEventAsync(
18
        body,
19
        signature,
20
        Deno.env.get('STRIPE_WEBHOOK_SECRET')!,
21
        undefined,
22
        cryptoProvider
23
      )
24
    } catch (err) {
25
      // Log the reason so a configuration error isn't mistaken for a forged payload.
26
      console.error('Stripe signature verification failed:', err)
27
      return new Response('bad signature', { status: 400 })
28
    }
29
30
    // your business logic. ctx.supabaseAdmin available for database work
31
    return Response.json({ received: true })
32
  }),
33
}

组合模式 #

🌐 Combining modes

既响应用户又响应内部调用的函数会在 auth 上接收一个数组。封装器会按顺序尝试每种模式，并使用第一个匹配的模式。ctx.authMode 会告诉你哪个模式匹配了。

🌐 Functions that answer both users and internal callers take an array on auth. The wrapper tries each mode in order and uses the first one that matches. ctx.authMode tells you which mode matched.

1
import { withSupabase } from 'npm:@supabase/server@1'
2
3
export default {
4
  fetch: withSupabase({ auth: ['user', 'secret'] }, async (req, ctx) => {
5
    if (ctx.authMode === 'user') {
6
      // your business logic for user calls. ctx.supabase is scoped to them
7
      return Response.json({ ok: true })
8
    }
9
10
    // your business logic for service calls. ctx.supabaseAdmin bypasses RLS
11
    return Response.json({ ok: true })
12
  }),
13
}

自定义错误响应 #

🌐 Custom error responses

要自己处理 401 响应，使用 createSupabaseContext 替代 withSupabase。它会返回一个 { data, error } 元组，而不是帮你拒绝请求。

🌐 To shape the 401 response yourself, use createSupabaseContext instead of withSupabase. It returns a { data, error } tuple instead of rejecting the request for you.

1
import { createSupabaseContext } from 'npm:@supabase/server@1'
2
3
export default {
4
  fetch: async (req: Request) => {
5
    const { data: ctx, error } = await createSupabaseContext(req, { auth: 'user' })
6
    if (error) {
7
      return Response.json({ message: error.message, code: error.code }, { status: error.status })
8
    }
9
    return Response.json({ message: `hello ${ctx.userClaims?.email}` })
10
  },
11
}

环境变量 #

🌐 Environment variables

@supabase/server 从一组标准的环境变量中读取其配置，这些变量由 Supabase 平台和 Supabase CLI 为你提供。

使用 CLI 进行本地开发时采用单键设置。@supabase/server 也可以接受 SUPABASE_PUBLISHABLE_KEY 和 SUPABASE_SECRET_KEY 作为备用。

🌐 Local development with the CLI uses a single-key setup. @supabase/server also accepts SUPABASE_PUBLISHABLE_KEY and SUPABASE_SECRET_KEY as a fallback.