一次搞定第三方登录Convex Better Auth 接入 GitHub、Google、Discord 完整指南【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth第三方登录Social Login几乎是现代 Web 应用的标配功能而 Better Auth 正是为开发者准备的免费开源认证库它把 GitHub、Google、Discord 等 OAuth 登录统一封装成一套简单 API。当 Better Auth 与 Convex 后端深度集成后你甚至不需要自己写会话管理、JWT 校验和数据库表就能在几分钟内上线完整的第三方登录能力。本指南将带你从零配置一次搞定 GitHub、Google、Discord 三个平台的接入附完整代码与排错技巧适合新手快速上手。为什么选择 Better Auth 搭建第三方登录在动手之前先了解 Better Auth 能为你省下哪些工作统一 OAuth 抽象GitHub、Google、Discord 只需要在socialProviders里各写一段配置剩下的跳转、回调、换取令牌全部由 Better Auth 处理与 Convex 深度集成通过 convex-plugin.mdx 文档描述的 Convex 插件自动完成 JWT 生成、Cookie 写入、JWKS 令牌校验登录态直接可在 Convex 查询中读取开箱即用的能力邮箱密码登录、magic link、验证码、2FA、匿名登录、账号绑定accountLinking等都是可选插件按需开启类型安全前端调用有完整的 TypeScript 类型提示几乎不会写错方法名底层实现细节可以参考 src/plugins/convex/index.ts它展示了插件如何通过convex_jwtCookie 与 JWKS 端点完成整个认证闭环。环境准备快速跑通示例项目 ⚙️最好的学习方式是直接运行项目自带的 Next.js 示例。克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/con/better-auth cd better-auth npm install cd examples/next npm install npx convex dev --once # 首次运行初始化本地数据库 npm run dev启动后访问http://localhost:3000你会看到一个功能齐全的登录页面其中已经包含 GitHub 和 Google 的登录按钮。后续的配置都以这个示例为基础讲解。第一步注册第三方平台的 OAuth 应用 ️要在应用里接入第三方登录必须先在各平台创建 OAuth 应用并拿到密钥。三个平台的注册流程基本一致核心是填对回调地址Callback / Redirect URI。GitHub OAuth 应用注册方法登录 GitHub进入Settings → Developer settings → OAuth Apps → New OAuth App填写应用名称、主页 URL如http://localhost:3000回调地址填入http://localhost:3000/api/auth/callback/github创建完成后记录Client ID和Client SecretGoogle OAuth 凭据配置方法打开 Google Cloud Console创建一个新项目进入APIs Services → Credentials → Create Credentials → OAuth client ID应用类型选择Web application授权回调地址填入http://localhost:3000/api/auth/callback/google保存后下载凭据 JSON里面包含 Client ID 和 Client SecretDiscord 应用创建方法登录 Discord Developer Portal点击New Application创建应用进入OAuth2页面找到 Redirects 区域回调地址填入http://localhost:3000/api/auth/callback/discord在OAuth2 → General页面记录 Client ID 和 Client Secret 提示/api/auth/callback/{provider}是 Better Auth 的默认回调路径。如果改动了basePath回调地址也要同步修改。第二步在 Better Auth 中配置 GitHub、Google、Discord 登录 拿到三个平台的密钥后打开示例中的 auth.ts在socialProviders中依次添加配置socialProviders: { github: { clientId: process.env.GITHUB_CLIENT_ID as string, clientSecret: process.env.GITHUB_CLIENT_SECRET as string, }, google: { clientId: process.env.GOOGLE_CLIENT_ID as string, clientSecret: process.env.GOOGLE_CLIENT_SECRET as string, accessType: offline, prompt: select_account consent, }, discord: { clientId: process.env.DISCORD_CLIENT_ID as string, clientSecret: process.env.DISCORD_CLIENT_SECRET as string, }, },随后把密钥写入环境变量文件.env.localGITHUB_CLIENT_IDxxx GITHUB_CLIENT_SECRETxxx GOOGLE_CLIENT_IDxxx GOOGLE_CLIENT_SECRETxxx DISCORD_CLIENT_IDxxx DISCORD_CLIENT_SECRETxxx SITE_URLhttp://localhost:3000同时需要在 auth.config.ts 中引入 Better Auth 的认证提供者让 Convex 认识你的认证配置import { getAuthConfigProvider } from convex-dev/better-auth/auth-config; export default { providers: [getAuthConfigProvider()], };最后把认证路由挂载到 HTTP 路由上参考 http.tsimport { httpRouter } from convex/server; import { authComponent, createAuth } from ./auth; const http httpRouter(); authComponent.registerRoutes(http, createAuth); export default http;第三步前端一键登录按钮实现 配置完成后前端只需调用signIn.social即可发起第三方登录。示例中的 SignIn.tsx/sign-in/SignIn.tsx) 提供了完整的参考实现核心代码如下const handleGithubSignIn async () { await authClient.signIn.social( { provider: github }, { onSuccess: () router.push(/), onError: (ctx) alert(ctx.error.message), }, ); };Google、Discord 的按钮写法完全一致只需把provider换成google或discord。客户端实例的创建与插件注册可以参考 auth-client.tsx其中convexClient()插件负责让前端客户端与 Convex 后端正确联动。第四步在 Convex 中读取当前登录用户 ‍第三方登录成功后登录态会自动通过 JWT 与 Cookie 与 Convex 同步。在服务端查询当前用户非常简单export const getCurrentUser query({ args: {}, handler: async (ctx) { return authComponent.safeGetAuthUser(ctx); }, });前端即可安全地在 Convex 查询中使用用户身份比如展示个人资料、控制页面访问权限而无需关心 Token 的刷新与校验细节。常见问题排查 ⚠️问题原因解决办法redirect_uri不匹配平台后台填写的回调地址与代码不一致检查平台上的回调 URL 是否为http://localhost:3000/api/auth/callback/{provider}登录后无法获取用户环境变量缺失或拼写错误核对GITHUB_CLIENT_ID等变量名是否与代码一致线上环境登录失败未设置SITE_URL或回调地址用了 localhost部署后更新平台回调地址与SITE_URL同邮箱多账号冲突用户在多个平台注册了不同账号开启account.accountLinking实现账号自动绑定总结 通过本文你已经完成了 GitHub、Google、Discord 三大平台的第三方登录接入注册 OAuth 应用、配置socialProviders、挂载路由、前端一键登录、Convex 读取用户全流程不到半小时。Better Auth 还支持 Magic Link、邮箱验证、2FA、匿名登录等更多能力后续可以按需在plugins数组中扩展让你的认证体系一次搭建、长期受益。如果遇到更复杂的需求官方文档 docs 与示例代码 examples 都是很好的参考资源。【免费下载链接】better-authConvex Better Auth 项目地址: https://gitcode.com/gh_mirrors/con/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考