认证

重定向URL配置

使用Supabase Auth设置重定向URL。


概述

Supabase Auth 允许您的应用程序在您授权的网页或移动应用中接收用户会话

当使用无密码登录第三方提供商时,Supabase 客户端库方法提供了 redirectTo 参数来指定用户认证后的重定向位置。默认情况下,用户将被重定向到 SITE_URL,但您可以修改 SITE_URL 或向允许列表添加额外的重定向 URL。将必要 URL 添加到允许列表后,您就可以在 redirectTo 参数中指定希望用户重定向到的 URL。

当使用Web3 登录时,用户在 Web3 钱包应用中签名的消息将显示签名发生的 URL。Supabase Auth 会拒绝针对未允许 URL 签名的消息。

要编辑允许列表,请前往URL 配置页面。在本地开发或自托管项目中,请使用配置文件

在重定向URL中使用通配符

Supabase允许您在将重定向URL添加到允许列表时使用通配符。您可以使用通配符匹配模式来支持来自Netlify和Vercel等提供商的预览URL。

通配符描述
*匹配任何非分隔符字符序列
**匹配任何字符序列
?匹配任何单个非分隔符字符
c匹配字符c(c不等于***?\[{}
\c匹配字符c
[!{ character-range }]匹配不在{ character-range }范围内的任何字符序列。例如,[!a-z]将不匹配从a到z的任何字符。

URL中的分隔符定义为./。使用此工具来测试您的匹配模式。

使用通配符的重定向URL示例

重定向URL描述
http://localhost:3000/*匹配 http://localhost:3000/foohttp://localhost:3000/bar,但不匹配 http://localhost:3000/foo/barhttp://localhost:3000/foo/(注意末尾斜杠)
http://localhost:3000/**匹配 http://localhost:3000/foohttp://localhost:3000/bar 以及 http://localhost:3000/foo/bar
http://localhost:3000/?匹配 http://localhost:3000/a 但不匹配 http://localhost:3000/foo
http://localhost:3000/[!a-z]匹配 http://localhost:3000/1 但不匹配 http://localhost:3000/a

Netlify预览URL

对于Netlify部署,将SITE_URL设置为您正式站点的URL。为本地开发和部署预览添加以下额外的重定向URL:

  • http://localhost:3000/**
  • https://**--my_org.netlify.app/**

Vercel 预览 URL

对于使用 Vercel 的部署,请将 SITE_URL 设置为您正式网站的 URL。同时为本地开发和部署预览添加以下额外的重定向 URL:

  • http://localhost:3000/**
  • https://*-<team-or-account-slug>.vercel.app/**

Vercel 提供了一个名为 NEXT_PUBLIC_VERCEL_URL 的环境变量来获取部署的 URL。更多详情请参阅 Vercel 文档。您可以使用此变量根据环境动态重定向。同时还应设置名为 NEXT_PUBLIC_SITE_URL 的环境变量,在生产环境中应将其设置为您的站点 URL,以确保重定向功能正常工作。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const getURL = () => { let url = process?.env?.NEXT_PUBLIC_SITE_URL ?? // 在生产环境中设置为您的站点 URL process?.env?.NEXT_PUBLIC_VERCEL_URL ?? // 由 Vercel 自动设置 'http://localhost:3000/' // 确保非本地环境包含 `https://` url = url.startsWith('http') ? url : `https://${url}` // 确保包含结尾的 `/` url = url.endsWith('/') ? url : `${url}/` return url}const { data, error } = await supabase.auth.signInWithOAuth({ provider: 'github', options: { redirectTo: getURL(), },})

使用 redirectTo 时的邮件模板

当使用 redirectTo 选项时,您可能需要在邮件模板中将 {{ .SiteURL }} 替换为 {{ .RedirectTo }}。更多信息请参阅邮件模板指南

例如,进行如下更改:

1
2
3
4
5
6
7
<!-- 旧版 --><a href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email">确认邮件</a><!-- 新版 --><a href="{{ .RedirectTo }}/auth/confirm?token_hash={{ .TokenHash }}&type=email" >确认邮件</a>

移动端深度链接URI

对于移动应用程序,您可以使用深度链接URI。例如,对于SITE_URL,您可以指定类似com.supabase://login-callback/的URI;如果需要额外的重定向URL,可以指定类似com.supabase.staging://login-callback/的URI。

了解更多关于深度链接的信息并查看不同框架的代码示例,请参阅此处

错误处理

当认证失败时,用户仍会被重定向到提供的重定向URL。不过,错误详情会以URL中的查询片段形式返回。您可以解析这些查询片段并向用户显示自定义错误信息。例如:

1
2
3
4
5
6
const params = new URLSearchParams(window.location.hash.slice())if (params.get('error_code').startsWith('4')) { // 如果是4xx错误则显示错误信息 window.alert(params.get('error_description'))}