跳转到主要内容
做开发者向的产品，“用 GitHub 登录”的转化通常比邮箱注册高一截。vibestrap 用 Better Auth 的社交 provider 接 GitHub——配好两个环境变量，按钮就会出现在 /login 和 /register。

​
前置条件

  • 一个 GitHub 账号。
  • 决定好生产域名。
  • 5 分钟——三大平台里 GitHub 的 OAuth 流程最简单。

​
一步步配置

  1. 打开 Developer settings。github.com/settings/developers → OAuth Apps → New OAuth App。（如果挂在组织下，去 github.com/organizations/<org>/settings/applications。）
  2. 填表：
    字段值
    Application name产品名（用户在授权页会看到）。
    Homepage URLhttps://your-domain.com
    Authorization callback URLhttps://your-domain.com/api/auth/callback/github
    回调 URL 末尾不要带斜杠。本地开发再注册一个指向 http://localhost:3000/api/auth/callback/github 的 OAuth App，dev 和 prod 用两个独立的 App。
  3. 生成 client secret。在 OAuth App 页点 Generate a new client secret。 立刻复制——GitHub 只显示一次。
  4. 写到 .env.local： 
    GITHUB_CLIENT_ID=Iv1.abc123...
GITHUB_CLIENT_SECRET=...
  5. 打开按钮开关。src/config/site.ts： 
    features: { enableGithubLogin: true, /* ... */ }
  6. 重启 pnpm dev。环境变量是启动时读的。

​
Scope

Better Auth 默认请求 read:user 和 user:email ——够用来填 user.name、 user.email、user.image。除非你真要在用户身份下调 GitHub API，不要再要 repo 之类的 scope。要的越多，注册转化掉得越凶。 以后真要更宽的 scope（比如读用户的 repo），在 src/lib/auth.ts 里加 scopes： 
socialProviders.github = {
  clientId: env.GITHUB_CLIENT_ID,
  clientSecret: env.GITHUB_CLIENT_SECRET,
  scopes: ['read:user', 'user:email', 'repo'],
};
已存在的用户得重新授权，新 scope 才会生效。

​
验证是否生效

  1. 访问 /login——“用 GitHub 登录”按钮应该出现。
  2. 点一下，跳到 GitHub 授权页，点 Authorize，落回 /dashboard。
  3. 看 account 表——应该有一行 providerId = 'github'，挂在你的 user 行下。
  4. 先用邮箱注册，再用同邮箱的 GitHub 登一次——会合并成一个 user（账号合并对受信任 provider 是开的）。
  5. 看 user.image 字段，应该是用户的 GitHub 头像 URL。

​
常见坑

  • 回调 URL 带了末尾斜杠。GitHub 是字符级精确匹配。…/callback/github/（带斜杠） 和 …/callback/github（不带）不是一个东西。用不带斜杠的那个。
  • dev 和 prod 共用一个 OAuth App。GitHub 免费 OAuth App 只允许一个回调 URL。 建两个 App——MyProduct (dev) 和 MyProduct (prod)，各用各的 client ID。 顺手把 dev 的 App 名字加 “(dev)” 后缀，授权页用户能一眼看出来这是开发环境。
  • 没拿到邮箱权限。有些用户把 GitHub 上所有邮箱都设成 private。Better Auth 能跑——会回退到 noreply 邮箱。如果你必须发到他主信箱，第一次登录时弹个 “请补全资料”的流程。
  • 被组织限制的账号。如果用户的 GitHub 组织强制 SSO，你的 OAuth App 要先被 组织管理员批准，用户才能授权。
  • client secret 只显示一次。GitHub 不会再显示第二次。丢了就重新生成——旧的立刻失效。
  • 用户在 GitHub 上改了主邮箱。Better Auth 不会自动同步——user.email 留的是 注册那次的值。要追新可以加个 cron job 定期调 GitHub API 刷新。
  • GitHub Enterprise 实例。默认走 github.com。如果接 GitHub Enterprise Server， 得自定义 OAuth endpoint URL，开箱不支持。

​
官方文档