跳至主要內容

自訂你的 UI

除了預設的 UI 客製化選項外，Logto 允許你自帶 UI，完全取代內建的登入體驗介面。此功能讓你可以上傳包含自訂 UI 資產（HTML、CSS、JavaScript、圖片等）的 zip 檔，並將其託管於 Logto Cloud 伺服器，作為租戶使用者的 登入體驗。

備註:

此功能要求你的自訂 UI 必須相容於單頁應用程式（SPA, Single Page Application），並建議始終使用生產環境建置以獲得最佳效能。

在 Logto Console 體驗自訂 UI 功能​

使用官方專案快速開始​

最快啟動自訂登入 UI 的方式是複製 Logto experience 專案。這是 Logto 內建的登入體驗 UI，涵蓋所有功能並遵循 Logto 最佳實踐。你可以根據需求進行自訂。

檢出程式碼後，只需執行以下指令建置專案：

pnpm install && pnpm build
備註:

整個 Logto 專案為 pnpm monorepo。若你想單獨執行 experience 套件（不使用 pnpm），請將 package.json 中的 workspace: 依賴改為具體版本號（如 ^1.0.0）。

建置完成後，所有編譯後的資產會在 dist 目錄下。接著將 dist 目錄壓縮成 ZIP 檔，稍後即可上傳至 Logto Cloud。

自訂 UI 資產要求​

上傳自訂 UI 資產前，請確保符合以下要求：

  • 上傳資產需打包為單一 zip 檔。
  • zip 檔根目錄需包含 index.html 檔案。
  • zip 檔大小不得超過 20MB。
  • zip 檔內單一檔案不得超過 10MB。
  • zip 檔內總檔案數不得超過 200 個。

上傳你的自訂 UI 資產​

備註:

在生產環境使用此功能時請謹慎，因為會立即影響使用者的登入體驗。

  1. 前往 Console > 登入與帳號 > 品牌設定 > 自訂你的 UI。
  2. 點擊選擇或拖曳你在前一步建立的 zip 檔，系統會自動開始上傳。
  3. 上傳完成後，儲存變更，你的自訂 UI 會立即生效。
  4. 使用自訂登入 UI 時，「登入預覽」視窗將會停用。不過，你仍可點擊「即時預覽」按鈕，在新開的瀏覽器分頁測試自訂登入頁面。

開發你的自訂 UI​

與 Experience API 互動​

你的自訂 UI 需與 Experience API 互動，以執行登入、註冊、重設密碼、綁定社交帳號、啟用 MFA 等多種操作。為更好理解使用者流程與實作細節，建議參考我們的 Experience API 設計 RFC，其中提供完整技術規格與範例。

你也需要透過 sign-in Experience API endpoint 取得其他登入體驗設定，例如品牌色、公司 Logo、favicon、密碼政策、本地化語言字串，甚至自訂 CSS。

範例專案​

我們提供多個範例專案，協助你快速理解並開始實作自訂 UI。詳情請參閱 Logto Experience project GitHub 倉庫。

此外，我們將持續推出更多簡化且情境化的範例專案，涵蓋最常見的使用情境，敬請期待未來更新！

本地開發與除錯​

針對本地開發與除錯，我們提供 Logto Tunnel CLI 工具，可用於：

  • 將本機的 Experience API 請求代理到 Logto Cloud 端點。
  • 在本地測試你的自訂 UI 實作。

這讓你能在上傳至 Logto Cloud 前，於本地測試與除錯自訂 UI。

詳情請參閱 本地除錯與測試自訂 UI。

使用 CLI 上傳自訂 UI 資產​

除了透過 Console 上傳外，你也可以使用 Logto CLI 上傳自訂 UI 資產。這對於自動化部署流程特別有用。

詳情請參閱 使用 CLI 上傳自訂 UI 資產。

還原為 Logto 內建登入體驗​

若你希望還原為 Logto 內建的登入體驗，只需點擊「自訂你的 UI」卡片上的刪除按鈕。儲存變更後，登入體驗 UI 會恢復為 Logto 預設樣式。

RFCS：Experience API

 Experience samples 將自訂登入 UI 帶到 Logto Cloud