跳到主要内容

自定义你的 UI

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

备注:

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

在 Logto 控制台探索自定义 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. 进入 控制台 > 登录与账户 > 品牌定制 > 自定义你的 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 项目 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 示例 为 Logto Cloud 带来自定义登录 UI