重定向 URL

Set up redirect urls with Supabase Auth.

概览 #

🌐 Overview

Supabase Auth 让你可以控制你的应用如何处理用户会话。

🌐 Supabase Auth allows you to control how the user sessions are handled by your application.

在找 OAuth 客户端重定向 URI 吗？

本指南介绍了用户登录你的应用时的重定向 URL（使用像 Google、GitHub 等社交提供者）。如果你要把你的 Supabase 项目设置为第三方应用的 OAuth 2.1 提供者，请改看 OAuth 服务器重定向 URI 配置。

🌐 This guide covers redirect URLs for users signing into your application (using social providers like Google, GitHub, etc.). If you're setting up your Supabase project as an OAuth 2.1 provider for third-party applications, see the OAuth Server Redirect URI configuration instead.

在使用无密码登录或第三方提供商时，Supabase 客户端库提供了一个 redirectTo 参数，用于指定用户认证后的重定向位置。redirectTo 中的 URL 应该与重定向 URL 列表配置相匹配。

🌐 When using passwordless sign-ins or third-party providers, the Supabase client library provides a redirectTo parameter to specify where to redirect the user after authentication. The URL in redirectTo should match the Redirect URLs list configuration.

要配置允许的重定向 URL，请前往 URL 配置页面。添加所需的 URL 后，你可以在 redirectTo 参数中使用希望用户被重定向到的 URL。

🌐 To configure allowed redirect URLs, go to the URL Configuration page. Once you've added necessary URLs, you can use the URL you want the user to be redirected to in the redirectTo parameter.

URL 配置中的网站 URL 定义了当代码中未指定 redirectTo 时的默认重定向 URL。将其从 http://localhost:3000 改为你的生产环境 URL（例如：https://example.com）。这个设置对邮件确认和密码重置非常重要。

🌐 The Site URL in URL Configuration defines the default redirect URL when no redirectTo is specified in the code. Change this from http://localhost:3000 to your production URL (e.g., https://example.com). This setting is critical for email confirmations and password resets.

使用 Web3 登录时，用户在 Web3 钱包应用中签署的消息会显示签名发生的 URL。Supabase Auth 会拒绝那些为未列入允许列表的 URL 签署的消息。

🌐 When using Sign in with Web3, the message signed by the user in the Web3 wallet application will indicate the URL on which the signature took place. Supabase Auth will reject messages that are signed for URLs that are not on the allowed list.

在本地开发或自托管项目中，请使用配置文件。有关在部署到 Vercel 或 Netlify 时配置 SITE_URL 的更多信息，请参见下文。

🌐 In local development or self-hosted projects, use the configuration file. See below for more information on configuring SITE_URL when deploying to Vercel or Netlify.

在重定向 URL 中使用通配符 #

🌐 Use wildcards in redirect URLs

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

🌐 Supabase allows you to specify wildcards when adding redirect URLs to the allow list. You can use wildcard match patterns to support preview URLs from providers like Netlify and Vercel.

通配符	描述
`*`	匹配任何非分隔符字符的序列
`**`	匹配任何字符序列
`?`	匹配任何单个非分隔符字符
`c`	匹配字符 c（c != ``，`*`，`?`，`\`，`[`，`{`，`}`）
`\c`	匹配字符 c
`[!{ character-range }]`	匹配不在 `{ character-range }` 中的任何字符序列。例如，`[!a-z]` 不会匹配从 a 到 z 的任何字符。

URL 中的分隔符字符定义为 . 和 /。使用这个工具来测试你的模式。

🌐 The separator characters in a URL are defined as . and /. Use this tool to test your patterns.

带通配符的重定向 URL 示例 #

🌐 Redirect URL examples with wildcards

重定向 URL	描述
`http://localhost:3000/*`	匹配 `http://localhost:3000/foo`、`http://localhost:3000/bar`，但不匹配 `http://localhost:3000/foo/bar` 或 `http://localhost:3000/foo/`（注意末尾的斜杠）
`http://localhost:3000/**`	匹配 `http://localhost:3000/foo`、`http://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 预览网址 #

🌐 Netlify preview URLs

对于使用 Netlify 的部署，请将 SITE_URL 设置为你的网站官方 URL。为本地开发和部署预览添加以下额外的重定向 URL：

🌐 For deployments with Netlify, set the SITE_URL to your official site URL. Add the following additional redirect URLs for local development and deployment previews:

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

Vercel 预览网址 #

🌐 Vercel preview URLs

对于使用 Vercel 的部署，将 SITE_URL 设置为你的官方网站 URL。为本地开发和部署预览添加以下额外的重定向 URL：

🌐 For deployments with Vercel, set the SITE_URL to your official site URL. Add the following additional redirect URLs for local development and deployment previews:

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

Vercel 提供了一个名为 NEXT_PUBLIC_VERCEL_URL 的环境变量，用来存放部署的 URL。更多详情可以查看 Vercel 文档。你可以使用这个变量根据环境动态进行重定向。你还应该设置一个名为 NEXT_PUBLIC_SITE_URL 的环境变量，这个变量在生产环境中应该设置为你的网站 URL，以确保重定向能够正常工作。

🌐 Vercel provides an environment variable for the URL of the deployment called NEXT_PUBLIC_VERCEL_URL. See the Vercel docs for more details. You can use this variable to dynamically redirect depending on the environment. You should also set the value of the environment variable called NEXT_PUBLIC_SITE_URL, this should be set to your site URL in production environment to ensure that redirects function correctly.

1
const getURL = () => {
2
  let url =
3
    process?.env?.NEXT_PUBLIC_SITE_URL ?? // Set this to your site URL in production env.
4
    process?.env?.NEXT_PUBLIC_VERCEL_URL ?? // Automatically set by Vercel.
5
    'http://localhost:3000/'
6
  // Make sure to include `https://` when not localhost.
7
  url = url.startsWith('http') ? url : `https://${url}`
8
  // Make sure to include a trailing `/`.
9
  url = url.endsWith('/') ? url : `${url}/`
10
  return url
11
}
12
13
const { data, error } = await supabase.auth.signInWithOAuth({
14
  provider: 'github',
15
  options: {
16
    redirectTo: getURL(),
17
  },
18
})

使用 `redirectTo`#

🌐 Email templates when using redirectTo

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

🌐 When using a redirectTo option, you may need to replace the {{ .SiteURL }} with {{ .RedirectTo }} in your email templates. See the Email Templates guide for more information.

例如，修改以下内容：

🌐 For example, change the following:

1
<!-- Old -->
2
<a href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email"
3
  >Confirm email address</a
4
>
5
6
<!-- New -->
7
<a href="{{ .RedirectTo }}/auth/confirm?token_hash={{ .TokenHash }}&type=email"
8
  >Confirm email address</a
9
>

移动深度链接URI #

🌐 Mobile deep linking URIs

对于移动应用，你可以使用深度链接 URI。例如，对于你的 SITE_URL，你可以指定类似 com.supabase://login-callback/ 的内容，如果需要，还可以为额外的重定向 URL 指定类似 com.supabase.staging://login-callback/ 的内容。

🌐 For mobile applications you can use deep linking URIs. For example, for your SITE_URL you can specify something like com.supabase://login-callback/ and for additional redirect URLs something like com.supabase.staging://login-callback/ if needed.

点击这里了解更多关于深度链接的内容，并查看不同框架的代码示例 here。

🌐 Read more about deep linking and find code examples for different frameworks here.

错误处理 #

🌐 Error handling

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

🌐 When authentication fails, the user will still be redirected to the redirect URL provided. However, the error details will be returned as query fragments in the URL. You can parse these query fragments and show a custom error message to the user. For example:

1
const params = new URLSearchParams(window.location.hash.slice())
2
3
if (params.get('error_code').startsWith('4')) {
4
  // show error message if error is a 4xx error
5
  window.alert(params.get('error_description'))
6
}