新增 Apple 登入

初學者演練

前提條件：Web 應用在本地執行（5 分鐘啟動）、已遷移且能存真實賬戶的資料庫（設定資料庫），以及一個 Apple Developer Program 會員——與移動端賬戶指南註冊的同一個每年 99 美元的賬戶，如果還沒完成，先完成那一步再繼續。下面開發者門戶裡的所有操作都不額外收費。

為什麼重要：每當 iOS 應用提供 Google 或 GitHub 這類第三方社交登入時，App Store 稽核都要求提供 Sign in with Apple；它在 Web 端也是一顆可靠、低摩擦的按鈕——Apple 使用者用裝置上已有的賬戶即可登入。

快速術語：App ID 是應用的註冊識別符號（com.yourcompany.yourapp）。Services ID 是 Apple 為 Web 和服務端登入簽發的第二個識別符號——它就是你的客戶端 ID。Return URL 是 Apple 允許把登入使用者送回的精確地址——即套件的 Better Auth 回撥。金鑰是 Apple 只提供一次的 .p8 檔案；由你自己把它轉換成客戶端金鑰。

1. 註冊一個帶 Sign in with Apple 能力的 App ID。2. 註冊一個指向它、並持有你的域名和 return URL 的 Services ID。3. 建立 Sign in with Apple 金鑰並下載 .p8 檔案。4. 把該金鑰轉換成 client-secret JWT，並設定三個 env 值。

一個實在的限制：Apple 的 return URL 必須是註冊域名上的絕對 https:// 地址——localhost 和裸 http 都會被拒絕，所以在裸本地伺服器上無法完整走通按鈕。請在已部署的 URL 上驗證，或把本地伺服器放到 https 隧道（如 cloudflared tunnel 或 ngrok）後面，並在測試期間註冊隧道域名及其回撥。

• 建立 Apple Developer 賬戶
• 設定資料庫

註冊 App ID

1. 開啟 developer.apple.com/account，用持有 Developer Program 會員的賬戶登入。

2. 開啟 Certificates, Identifiers & Profiles → Identifiers，點選藍色 + 按鈕。

3. 選擇 App IDs → Continue，型別保持 App → Continue。

4. Description：你的產品名。Bundle ID：選擇 Explicit，輸入反向域名形式 com.yourcompany.yourapp——如果也要釋出 iOS 應用，請使用 apps/mobile/app.json 中的 ios.bundleIdentifier，讓兩個平臺共享同一個 App ID。

5. 在能力列表中勾選 Sign in with Apple → Continue → Register。

預期結果：該識別符號出現在 Identifiers 列表中，且 Sign in with Apple 能力為啟用狀態。後續複用這一個 App ID——Services ID 和金鑰都會把它作為主力應用來關聯。

註冊 Services ID 和 return URL

1. 回到 Identifiers，再次點選 +，選擇 Services IDs → Continue。

2. Description：類似 yourapp web sign-in。Identifier：再來一個反向域名——慣例是 com.yourcompany.yourapp.web——故意與 App ID 不同。這個 Services ID 就是伺服器用於 Web 登入的客戶端 ID；請精確複製，然後 Continue → Register。

3. 在列表中選中新建的 Services ID，勾選 Sign in with Apple，點選 Configure。

4. 在對話方塊中把 Primary App ID 設為上一節的 App ID。在 Website URLs 下新增你的域名（如 yourdomain.com），在 Return URLs 下新增 https://yourdomain.com/api/auth/callback/apple——該路徑就是套件的 Better Auth 回撥 {APP_URL}/api/auth/callback/apple。Save → Continue → Save。

每個 return URL 都必須是註冊域名上的絕對 https:// 地址：localhost、裸 IP 地址和 http 都會被拒絕。本地開發時把應用跑在 https 隧道後面，把隧道域名加進 Services ID，註冊 https://<tunnel-domain>/api/auth/callback/apple，並在測試期間把 APP_URL 設為隧道 URL。

預期結果：Services ID 顯示 Sign in with Apple → Enabled。如果門戶拒絕你的域名，先在賬戶頁面完成域名所有權驗證。

建立 Sign in with Apple 金鑰

1. 在左側邊欄開啟 Keys → +。給金鑰起名（如 yourapp sign-in key），勾選 Sign in with Apple，點選 Configure，選擇 App ID 作為 Primary App ID → Save → Continue → Register。

2. 在確認頁面記下 Key ID，然後點選 Download——.p8 檔案只提供一次。弄丟了就吊銷該金鑰另建一個；Apple 不儲存副本。

3. 同時記下你的 Team ID——它印在開發者賬戶頁面右上角、賬戶名旁邊。

預期結果：現在你持有三個值——.p8 檔案、一個 Key ID 和你的 Team ID。.p8 檔案不要放進 Git：它以你的開發者賬戶簽名。

把值加入應用

套件只期望下面三行——與所有社交提供商相同的 clientId/clientSecret 憑據對。APPLE_CLIENT_ID 是 Services ID（com.yourcompany.yourapp.web），不是 App ID。

Apple 不簽發靜態客戶端金鑰，所以 APPLE_CLIENT_SECRET 是你用 Team ID、Key ID 和 .p8 私鑰自己簽發的 JWT——Better Auth 檔案附帶了生成它的短指令碼。簽發的金鑰最長有效六個月：設個提醒重新生成並更新 env 值，因為它一過期登入就會失敗。絕不要把 .p8 檔案內容或裸 Key ID 粘進 env——那裡只放生成的 JWT。

客戶端金鑰和 .p8 檔案僅限服務端：絕不能出現在 NEXT_PUBLIC_/EXPO_PUBLIC_ 變數裡，也不能提交；生產環境通過託管方的金鑰儲存設定。編輯後重啟開發伺服器；env 變更只在啟動時讀取。

# apps/web/.env.local
AUTH_APPLE_ENABLED=true
APPLE_CLIENT_ID=com.yourcompany.yourapp.web   # the Services ID, not the App ID
APPLE_CLIENT_SECRET=<JWT signed with Team ID + Key ID + .p8>

驗證與排錯

在 /auth 開啟你的 APP_URL——已部署 URL 或 https 隧道——點選 Apple 按鈕，用任意 Apple ID（不必是開發者賬戶）登入，確認回到應用時已登入。

大多數失敗是三種混淆之一：Services ID 與 App ID——客戶端 ID 必須是用於 Web 登入的 Services ID；return URL 不匹配——回撥必須與已註冊的 Return URL 完全相等，包括協議、域名和路徑；或者客戶端金鑰過期/無效——重新生成 JWT，它只是簽發的令牌，不是 .p8 內容。

在設定 AUTH_APPLE_ENABLED=true 之前，/auth 上的 Apple 選項保持停用——檢查 env 名稱並重啟。在沒有 APPLE_CLIENT_ID 和 APPLE_CLIENT_SECRET 的情況下開啟開關會讓啟動失敗並指出缺失的變數。

iOS 應用訪問的是同一個後端——在其中也釋出 Sign in with Apple，好讓 App Store 稽核接受其他社交按鈕。移動端賬戶指南解釋了稽核的關注點。

• 建立移動端賬戶
• 接下來新增 Stripe 支付
• OAuth 提供商概覽