> ## 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

# 原生認證

處理移動端的瀏覽器回跳與已存會話。

## 安裝與配置

在執行任何步驟之前，請閱讀[開始之前](https://supastack.dev/zh-tw/docs/web/before-you-start.md) 和[終端基礎知識](https://supastack.dev/zh-tw/docs/web/terminal-basics.md)。這些說明假設您在 VS Code 中開啟了完整的 supastack monorepo；它的根 package.json 標記儲存庫根。在 pnpm 命令中，工作區包是應用程式或共享程式碼資料夾；在產品中，工作空間是團隊的資料容器和安全邊界。 corepack pnpm --filter ... 從 monorepo 選擇一個包，同時從其根執行命令。如果您僅開啟同步的移動或桌面資料夾，則它不包含 Web 後端、Docker 設定或根指令碼：從此 monorepo 或可訪問的託管伺服器執行後端，並使用平臺資料夾自己的指令碼。環境變數是儲存在本地 .env 檔案或託管儀錶板中的命名設定；更改後重新啟動相關應用程式，並將伺服器機密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。

1、在VS Code中開啟apps/mobile/src/auth/client.ts和apps/mobile/src/auth/mobile-auth-configuration.ts，找到已有的登入流程。

2.將EXPO_PUBLIC_API_URL和EXPO_PUBLIC_APP_SCHEME放入apps/mobile/.env.local，並確保Web伺服器在apps/web/.env.local.中有自己的設定

3. 從 root 啟動 Web，使用 corepack pnpm --filter @supastack/web dev，然後在另一個終端中使用 corepack pnpm --filter @supastack/mobile start 啟動 Expo。預期：測試登入將開啟瀏覽器並返回到移動應用程式。在實體手機上，使用計算機可連線的 Wi-Fi/LAN 地址作為 API；電話-localhost 表示電話本身。

移動應用使用 Better Auth 的 Expo 整合與原生安全儲存。API origin 與應用 scheme 必須與原生配置以及認證伺服器允許的返回流程一致。

```
EXPO_PUBLIC_API_URL=https://your-api.example
EXPO_PUBLIC_APP_SCHEME=supastack
```


## 要複製的命令

按照註釋檢視命令在哪個資料夾中執行。如果標記了兩個終端，請開啟兩個終端視窗，並在使用第二個命令時保持第一個命令執行。

```
# Terminal 1 — Web API (from the monorepo root):
corepack pnpm --filter @supastack/web dev

# Terminal 2 — Expo app (from the monorepo root):
corepack pnpm --filter @supastack/mobile start
```


## 實現流程

沿用現有的原生認證客戶端，不要把 Web Cookie 的假設搬到移動端。通過配置的瀏覽器流程開啟供應商認證，處理回撥，然後先解析已認證會話，再呈現受保護動作。

請將取消登入與成功登入區分開來。成員可以在“設定 → 安全”中啟用生物識別應用鎖（`apps/mobile/src/security/app-lock.ts` 中的 Face ID、Touch ID 或指紋），在應用回到前臺時要求驗證。退出登入時請清除上一位使用者的本地介面狀態以及按工作區隔離的離線讀取快取（`apps/mobile/src/offline/`），並確認服務端會話無法再執行受保護的操作。


## 驗證與排障

如果登入開啟瀏覽器但沒有返回到應用程式，請檢查 EXPO_PUBLIC_APP_SCHEME 是否與 apps/mobile/app.config.ts. 中的方案匹配。如果應用程式無法到達伺服器，請將 localhost 替換為計算機的 LAN 地址，確認兩臺裝置使用相同的網路，然後編輯 apps/mobile/.env.local. 後重新啟動 Expo Expo Go 是 UI 預覽；本機購買接受需要 EAS 開發版本。

在目標構建上演練冷啟動回撥、返回執行中的應用、取消登入與過期會話。如果瀏覽器返回了但應用仍未登入，先檢查 scheme 匹配與 API 可達性，再改供應商配置。


如果你想繼續完成設定，可以閱讀《[移動端權益](https://supastack.dev/zh-tw/docs/mobile/entitlements.md)》。


## 下一篇

[移動端 API](https://supastack.dev/zh-tw/docs/mobile/api.md)