跳到主要内容

自定义你的 UI

Logto 允许你自定义 UI，以完全替换内置的登录体验界面，除了预构建的 UI 自定义选项之外。此功能使你能够上传包含自定义 UI 资源（HTML、CSS、JavaScript、图像等）的 zip 文件，将其托管在 Logto Cloud 服务器上，并将其用作租户用户的登录体验。

备注

此功能要求你的自定义 UI 兼容单页应用程序 (SPA)，并建议始终使用生产构建以获得最佳性能。

在 Logto 控制台中探索自定义 UI 功能​

从官方项目开始​

启动自定义登录 UI 的最快方法是克隆 Logto 体验项目。这是内置的 Logto 登录体验 UI，涵盖了所有功能和 Logto 的最佳实践。你可以根据需要进行自定义。

检出代码后，只需运行以下命令来构建项目：

pnpm install && pnpm build
备注

整个 Logto 项目是一个 pnpm monorepo，如果你想单独运行体验包（不使用 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. 导航到 控制台 > 登录体验 > 品牌 > 自定义你的 UI。
  2. 点击选择或拖放在上一步中创建的 zip 文件，上传过程将自动开始。
  3. 上传完成后，保存更改，你的自定义 UI 将立即提供服务。
  4. 使用自定义登录 UI 时，“登录预览”窗口将被禁用。但是，你仍然可以点击“实时预览”按钮，在新打开的浏览器标签页中测试自定义登录页面。

开发你的自定义 UI​

与体验 (Experience) API 交互​

你的自定义 UI 需要与 体验 (Experience) API 交互，以执行各种操作，如登录、注册、密码重置、绑定社交账户、启用多因素认证 (MFA) 等。为了更好地理解用户流程和实现细节，我们建议查看我们的 体验 (Experience) API 设计 RFC，其中提供了全面的技术规范和示例。

你还需要通过 登录体验 (Experience) API 端点 访问其他登录体验配置，如品牌颜色、公司标志、favicon、密码策略、本地化语言短语，甚至自定义 CSS。

示例项目​

我们提供了一系列示例项目，帮助你快速理解和开始实现自定义 UI。请查看 Logto 体验项目 GitHub 仓库了解详细信息。

此外，我们将继续努力提供更多简化和基于场景的示例项目，以涵盖最常见的用例。请关注我们的未来更新！

本地开发和调试​

对于本地开发和调试，我们提供了 Logto Tunnel CLI 工具，以：

  • 将体验 (Experience) API 请求从本地机器代理到 Logto Cloud 端点。
  • 在本地测试你的自定义 UI 实现。

这允许用户在上传到 Logto Cloud 之前在本地测试和调试自定义 UI。

请参阅 在本地调试和测试你的自定义 UI 了解更多详细信息。

使用 CLI 上传你的自定义 UI 资源​

除了通过控制台上传，你还可以使用 Logto CLI 上传自定义 UI 资源。这对于自动化部署工作流程特别有用。

请参阅 使用 CLI 上传自定义 UI 资源 了解更多详细信息。

恢复到 Logto 内置登录体验​

如果你希望恢复到 Logto 的内置登录体验，只需点击自定义你的 UI 卡上的删除按钮。保存更改后，登录体验 UI 将恢复为 Logto 的默认设置。

相关资源​

RFCS: 体验 (Experience) API

 体验 (Experience) 示例 将自定义登录 UI 引入 Logto Cloud