添加 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 提供商概览