在Supabase GitHub认证中遇code challenge与code verifier不匹配错误

这个错误的核心原因是Supabase发起OAuth请求时生成的code_verifier未被正确保存到Cookie，或回调时无法读取该值，导致授权码交换时验证失败。以下是针对性修复步骤：

1. 前端登录必须用Supabase官方方法 #

禁止手动构造GitHub OAuth跳转URL，必须使用Supabase Auth Helper提供的signInWithOAuth方法——它会自动生成并存储code_verifier到Cookie：

// 前端组件登录逻辑示例
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs'

async function handleGitHubLogin() {
  const supabase = createClientComponentClient()
  await supabase.auth.signInWithOAuth({
    provider: 'github',
    options: {
      redirectTo: `${window.location.origin}/auth/callback`, // 必须与回调路由完全一致
    },
  })
}

2. 强化回调路由的动态性配置 #

确保回调路由不会被Next.js静态优化导致Cookie上下文丢失，除了dynamic: 'force-dynamic'，额外添加revalidate: 0强制禁用缓存：

// 回调路由文件（如app/auth/callback/route.ts）
export const dynamic = 'force-dynamic'
export const revalidate = 0 // 新增：强制不缓存

export async function GET(request: NextRequest) {
  const requestUrl = new URL(request.url)
  const code = requestUrl.searchParams.get('code')

  if (code) {
    const supabase = createRouteHandlerClient({ cookies })
    await supabase.auth.exchangeCodeForSession(code)
  }

  return NextResponse.redirect(requestUrl.origin)
}

3. 检查Supabase OAuth控制台配置 #

登录Supabase控制台，确认GitHub OAuth应用的以下配置：

• Client ID/Secret：与GitHub开发者平台创建的应用信息完全一致
• 授权回调URL：必须和前端redirectTo指定的地址完全匹配（生产环境需填写实际域名，如https://your-app.com/auth/callback）

4. 适配子域名场景的Cookie配置 #

如果部署在子域名环境，需显式配置Cookie的domain，确保跨子域名能读取到code_verifier：

// 回调路由中修改Supabase客户端初始化
const supabase = createRouteHandlerClient({
  cookies,
  options: {
    auth: {
      cookieOptions: {
        domain: '.your-domain.com', // 按需设置为根域名
        sameSite: 'lax',
        secure: process.env.NODE_ENV === 'production', // 生产环境启用secure
      },
    },
  },
})

5. 本地开发环境排查 #

若本地开发时出现问题：

• 启用https协议（Next.js可通过next dev --experimental-https开启）
• 清除浏览器缓存和Cookie，避免旧的code_verifier残留
• 检查本地hosts配置，确保域名解析正确

内容的提问来源于stack exchange，提问作者Harsh Agrawal