> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 添加 GitHub 登录

为每个环境创建一个 GitHub OAuth App，并把“使用 GitHub 继续”接入应用。

## 初学者演练

前提条件：Web 应用在本地运行，以及一个已迁移、可存真实账户的数据库。你需要一个 GitHub 账户——用拥有该仓库的那个就行。免费，每个环境约 5 分钟。

快速术语：GitHub OAuth App 是让 GitHub 替你完成用户登录的注册项。与大多数服务商不同，一个 OAuth App 只允许一个 Authorization callback URL——所以本地（`http://localhost:3000/…`）和生产（`https://yourdomain.com/…`）各需要一个应用。复用同一个应用并来回修改回调地址，每次都会弄坏一边。

1. 在你账户的 Developer settings 下创建本地 OAuth App。2. 复制其 Client ID 并生成 Client Secret。3. 设置三个环境变量并重启。4. 上线前用你的真实域名再重复一次。

[5 分钟启动 Web 应用](https://supastack.dev/zh/docs/web/ship-in-5-minutes.md)

[设置数据库](https://supastack.dev/zh/docs/web/setup-database.md)


## 创建本地 OAuth App

1. 打开 [github.com](https://github.com) 并登录。点击右上角的头像 → Settings。

2. 滚动到左侧边栏底部，打开 Developer settings → OAuth Apps → New OAuth App。

3. Application name：类似 `supastack local` 的名字——用户会在 GitHub 授权页看到它。Homepage URL：`http://localhost:3000`。Authorization callback URL：`http://localhost:3000/api/auth/callback/github`。点击 Register application。

4. 在应用页面复制 Client ID，点击 Generate a new client secret 并立即复制该 Secret——GitHub 只显示一次，但你随时可以重新生成。


## 创建生产环境 OAuth App

用你的产品名重复同样的 New OAuth App 步骤，Homepage URL 填 `https://yourdomain.com`，Authorization callback URL 填 `https://yourdomain.com/api/auth/callback/github`。

让每个应用的凭据留在自己的环境中：本地应用的凭据对放在 `apps/web/.env.local`，生产应用的凭据对放在托管方的密钥存储中。本地密钥绝不能进入生产配置，反之亦然。


## 把值添加到应用中

用本地应用的凭据在 `apps/web/.env.local` 中设置下面三行。`AUTH_GITHUB_ENABLED=true` 打开按钮；凭据对用于标识该 OAuth App。

Client Secret 仅限服务端——绝不放进 `NEXT_PUBLIC_`/`EXPO_PUBLIC_` 变量，也绝不提交。编辑后重启开发服务器。

不要复用你在别处看到的任何 `GITHUB_APP_*` 值——它们属于另一个无关的 GitHub App 集成，而不是用户登录。如果想要第二份参考，套件的 `docs/github-auth-setup.md` 会端到端走完整个流程。

```
# apps/web/.env.local — from the LOCAL OAuth App
AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=your-oauth-app-client-id
GITHUB_CLIENT_SECRET=your-oauth-app-secret
```


## 验证与故障排除

打开 http://localhost:3000/auth，点击 GitHub 按钮。在 github.com 上授权该应用，确认返回时处于登录状态。

在设置 `AUTH_GITHUB_ENABLED=true` 之前，`/auth` 上的 GitHub 选项保持可见但禁用——检查 env 文件中的名称，然后重启。只设置开关而缺少 `GITHUB_CLIENT_ID` 和 `GITHUB_CLIENT_SECRET` 会导致启动失败并报出缺失的变量名。

回调不匹配是最常见的错误：应用的 Authorization callback URL 必须与 `{APP_URL}/api/auth/callback/github` 完全一致——协议、主机、端口和路径。部署后出现 `redirect_uri` 错误，通常意味着请求打到了本地应用的凭据，而 APP_URL 指向生产，或者反过来。

每次编辑 env 后都重启开发服务器；值只在启动时读取。

[接下来设置数据库](https://supastack.dev/zh/docs/web/setup-database.md)

[OAuth 提供商概览](https://supastack.dev/zh/docs/web/setup-oauth.md)


如果你想继续完成设置，可以阅读《[添加 Apple 登录](https://supastack.dev/zh/docs/web/apple-sign-in.md)》。


## 下一篇

[添加 Apple 登录](https://supastack.dev/zh/docs/web/apple-sign-in.md)