> ## 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-tw/docs/web/ship-in-5-minutes.md)

[設定資料庫](https://supastack.dev/zh-tw/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-tw/docs/web/setup-database.md)

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


如果你想繼續完成設定，可以閱讀《[新增 Apple 登入](https://supastack.dev/zh-tw/docs/web/apple-sign-in.md)》。


## 下一篇

[新增 Apple 登入](https://supastack.dev/zh-tw/docs/web/apple-sign-in.md)