用 Facebook 登录

要为你的项目启用 Facebook 认证，你需要设置一个 Facebook OAuth 应用，并把应用的凭证添加到你的 Supabase 控制面板。

🌐 To enable Facebook Auth for your project, you need to set up a Facebook OAuth application and add the application credentials to your Supabase Dashboard.

概览 #

🌐 Overview

为你的应用设置 Facebook 登录包括四个部分：

🌐 Setting up Facebook logins for your application consists of 4 parts:

• 在 Facebook 开发者网站 上创建并配置一个 Facebook 应用
• 在你的 Facebook 应用中配置邮件权限（Supabase Auth 所必需）
• 将你的 Facebook 密钥添加到你的 Supabase 项目
• 将登录代码添加到你的 Supabase JS 客户端应用

访问你的 Facebook 开发者账号 #

🌐 Access your Facebook Developer account

• 去 developers.facebook.com 。
• 点击右上角的 Log In 登录。

创建一个 Facebook 应用 #

🌐 Create a Facebook app

• 点击右上角的 My Apps。
• 点击右上角附近的 Create App。
• 选择你的应用类型，然后点击 Continue。
• 填写你的应用信息，然后点击 Create App。
• 这应该会带你到屏幕：Add Products to Your App。（或者你也可以点击左侧边栏的Add Product来进入这个屏幕。）

下一步需要一个回调 URL，看起来像这样：https://<project-ref>.supabase.co/auth/v1/callback

• 前往你的 Supabase 项目仪表板
• 点击左侧边栏的 Authentication 图标
• 在配置部分点击Sign In / Providers
• 点击手风琴列表中的 Facebook 展开，你就会找到你的 回调 URL，你可以点击 Copy 将其复制到剪贴板

本地开发 #

🌐 Local development

在本地使用 Supabase CLI 测试 OAuth 时，确保你的 OAuth 提供商已配置本地 Supabase Auth 回调 URL：

🌐 When testing OAuth locally with the Supabase CLI, ensure your OAuth provider is configured with the local Supabase Auth callback URL:

http://localhost:54321/auth/v1/callback

如果这个回调 URL 缺失或配置错误，OAuth 登录可能会失败，或者在本地开发时无法正确跳转。

🌐 If this callback URL is missing or misconfigured, OAuth sign-in may fail or not redirect correctly during local development.

有关更多详情，请查看本地开发文档。

🌐 See the local development docs for more details.

要在本地使用 Supabase CLI 测试 OAuth，请参阅本地开发文档。

🌐 For testing OAuth locally with the Supabase CLI see the local development docs.

为你的 Facebook 应用设置 Facebook 登录 #

🌐 Set up Facebook login for your Facebook app

从 Add Products to your App 屏幕开始：

🌐 From the Add Products to your App screen:

• 在 Facebook 登录 下点击 设置
• 跳过快速入门界面。在左侧边栏中，点击 Facebook 登录 下的 设置
• 在 Facebook 登录设置 页面下的 有效 OAuth 重定向 URI 中输入你的回调 URI
• 点击右下角的保存更改

配置电子邮件权限（必需） #

🌐 Configure email permissions (required)

你必须在你的 Facebook 应用的使用案例中配置邮箱权限：

🌐 You must configure the email permission in your Facebook app's Use Cases:

1. 在你的 Facebook 应用仪表板中，点击 Build Your App 下的 使用案例
2. 找到身份验证和账户创建，然后点击右侧的编辑按钮
3. 确认 public_profile 和 email 都显示状态 准备测试
4. 如果没有列出 email，点击它旁边的 添加 按钮

复制你的 Facebook 应用 ID 和密钥 #

🌐 Copy your Facebook app ID and secret

• 在左侧边栏点击 Settings / Basic
• 从 Basic Settings 页面顶部复制你的应用 ID
• 在 App Secret 下点击 Show，然后复制你的密钥
• 确保这个屏幕上的所有必填字段都已填写。

在你的 Supabase 项目中输入你的 Facebook 应用 ID 和密钥 #

🌐 Enter your Facebook app ID and secret into your Supabase project

• 前往你的 Supabase 项目仪表板
• 在左侧边栏，点击Authentication图标（靠近顶部）
• 在配置部分点击Providers
• 从手风琴列表中点击 Facebook 来展开，然后将 Facebook 启用 切换为开启
• 输入你在上一步保存的 Facebook 客户端 ID 和 Facebook 客户端密钥
• 点击 Save

你也可以使用管理 API 配置 Facebook 身份验证提供者：

🌐 You can also configure the Facebook auth provider using the Management API:

1
# Get your access token from https://supabase.com/dashboard/account/tokens
2
export SUPABASE_ACCESS_TOKEN="your-access-token"
3
export PROJECT_REF="your-project-ref"
4
5
# Configure Facebook auth provider
6
curl -X PATCH "https://api.supabase.com/v1/projects/$PROJECT_REF/config/auth" \
7
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
8
  -H "Content-Type: application/json" \
9
  -d '{
10
    "external_facebook_enabled": true,
11
    "external_facebook_client_id": "your-facebook-app-id",
12
    "external_facebook_secret": "your-facebook-app-secret"
13
  }'

在你的客户端应用中添加登录代码 #

🌐 Add login code to your client app

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient('https://your-project-id.supabase.co', 'sb_publishable_...')
4
5
// ---cut---
6
async function signInWithFacebook() {
7
  const { data, error } = await supabase.auth.signInWithOAuth({
8
    provider: 'facebook',
9
  })
10
11
  if (error) {
12
    console.error('Error signing in with Facebook:', error.message)
13
    return
14
  }
15
16
  // The user will be redirected to Facebook for authentication
17
}

以 PKCE 流程为例，比如在服务端认证中，你需要一个额外的步骤来处理代码交换。在调用 signInWithOAuth 时，提供一个指向回调路由的 redirectTo URL。这个重定向 URL 应该添加到你的 重定向允许列表 中。

🌐 For a PKCE flow, for example in Server-Side Auth, you need an extra step to handle the code exchange. When calling signInWithOAuth, provide a redirectTo URL which points to a callback route. This redirect URL should be added to your redirect allow list.

1
import { createClient, type Provider } from '@supabase/supabase-js';
2
const supabase = createClient('https://your-project-id.supabase.co', 'sb_publishable_...')
3
const provider = 'provider' as Provider
4
5
// ---cut---
6
await supabase.auth.signInWithOAuth({
7
  provider,
8
  options: {
9
    redirectTo: `http://example.com/auth/callback`,
10
  },
11
})

在回调端点，处理代码交换以保存用户会话。

🌐 At the callback endpoint, handle the code exchange to save the user session.

1
import { NextResponse } from 'next/server'
2
3
// The client you created from the Server-Side Auth instructions
4
import { createClient } from '@/utils/supabase/server'
5
6
export async function GET(request: Request) {
7
  const { searchParams, origin } = new URL(request.url)
8
  const code = searchParams.get('code')
9
  // if "next" is in param, use it as the redirect URL
10
  let next = searchParams.get('next') ?? '/'
11
  if (!next.startsWith('/')) {
12
    // if "next" is not a relative URL, use the default
13
    next = '/'
14
  }
15
16
  if (code) {
17
    const supabase = await createClient()
18
    const { error } = await supabase.auth.exchangeCodeForSession(code)
19
    if (!error) {
20
      const forwardedHost = request.headers.get('x-forwarded-host') // original origin before load balancer
21
      const isLocalEnv = process.env.NODE_ENV === 'development'
22
      if (isLocalEnv) {
23
        // we can be sure that there is no load balancer in between, so no need to watch for X-Forwarded-Host
24
        return NextResponse.redirect(`${origin}${next}`)
25
      } else if (forwardedHost) {
26
        return NextResponse.redirect(`https://${forwardedHost}${next}`)
27
      } else {
28
        return NextResponse.redirect(`${origin}${next}`)
29
      }
30
    }
31
  }
32
33
  // return the user to an error page with instructions
34
  return NextResponse.redirect(`${origin}/auth/auth-code-error`)
35
}

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient('https://your-project-id.supabase.co', 'sb_publishable_...')
4
5
// ---cut---
6
async function signOut() {
7
  const { error } = await supabase.auth.signOut()
8
9
  if (error) {
10
    console.error('Error signing out:', error.message)
11
    return
12
  }
13
14
  // User has been signed out
15
}

测试你的整合 #

🌐 Testing your integration

Facebook 应用启动时处于 开发 模式，具有以下限制：

🌐 Facebook apps start in Development mode, which has the following limitations:

• 只有在应用中有角色的用户（管理员、开发者、测试人员）才能进行认证
• 其他用户在尝试登录时会看到“应用未设置”错误

添加测试用户：

🌐 To add test users:

1. 去 developers.facebook.com 然后选择你的应用
2. 导航到 应用角色 > 角色
3. 把用户添加为测试者、开发者或管理员
4. 用户必须接受他们在 Facebook 通知设置中的邀请

开始进行应用审核 #

🌐 Going live with app review

在你的应用可以被大众使用之前，你需要完成 Facebook 的应用审核流程：

🌐 Before your app can be used by the general public, you need to complete Facebook's App Review process:

1. 完整的应用设置：在你的 Facebook 应用的 设置 > 基本信息 中，填写所有必填字段，包括：
   • 应用图标
   • 隐私政策网址
   • 服务条款链接（如适用）
   • 应用域
2. 请求权限：前往 应用审核 > 权限和功能 并请求你需要的权限：
   • public_profile - 通常已预先批准
   • email - 需要验证你的应用是否需要访问电子邮件
3. 提交审核：点击 提交审核 并提供：
   • 关于 Facebook 审核人员如何测试你的登录流程的详细说明
   • 一个演示Facebook登录功能的屏幕录制视频
   • 解释用户数据将如何被使用
4. 等待审批：Facebook 通常会在 1-5 个工作日内审核应用

欲了解更多详情，请参阅 Facebook 应用审核文档。

🌐 For more details, see the Facebook App Review documentation.

故障排除 #

🌐 Troubleshooting

“应用未设置”错误 #

🌐 "App not setup" error

当应用处于开发模式时，如果没有角色的用户尝试登录，就会发生这个错误。

🌐 This error occurs when a user without a role on your app tries to log in while the app is in Development mode.

解决方案：要么在你的 Facebook 应用设置中将用户添加为测试者，要么完成应用审核流程，让你的应用对所有用户可用。

用户的邮箱没有回信 #

🌐 User's email not returned

只有在以下情况下，Facebook 才会返回电子邮件地址：

🌐 Facebook only returns the email address if:

• 用户的 Facebook 账户有一个已确认的邮箱
• 你的应用已被授予 email 权限
• email 权限在 用例 > 认证和账户创建 中被标记为“准备测试”

解决方案：检查你的 Facebook 应用的使用场景设置中 email 权限是否配置正确。

"重定向 URI 不匹配" 错误 #

🌐 "Redirect URI mismatch" error

这个错误表示在 Facebook 配置的回调 URL 与认证时使用的不匹配。

🌐 This error indicates the callback URL configured in Facebook doesn't match the one used during authentication.

解决方案：确认你在 Facebook 应用设置中的 有效 OAuth 重定向 URI 完全匹配 https://<project-ref>.supabase.co/auth/v1/callback。确保没有多余的斜杠或拼写错误。

登录在开发环境中可以用，但在生产环境中不行 #

🌐 Login works in development but not production

如果本地登录正常但生产环境失败，请检查：

🌐 If login works locally but fails in production, check:

• 你的生产环境 URL 已添加到 Facebook 的 有效 OAuth 重定向 URI 中
• 你 Supabase 仪表板里的 App ID 和 Secret 与你的 Facebook 应用匹配
• 你的 Facebook 应用现在是上线模式（不是开发模式）

资源 #

🌐 Resources

• Supabase - 免费开始
• Supabase JS 客户端
• Facebook 开发者仪表板