跳到主要内容

自定义你的 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 时，“登录预览”窗口将被禁用。但你仍可点击“实时预览”按钮，在新打开的浏览器标签页中测试你的自定义登录页面。

配置自定义 CSP 来源​

Logto 会为自定义 UI 页面应用 Content Security Policy (CSP) header。如果你的自定义 UI 需要加载第三方脚本，或连接到外部服务，可以在 控制台 > 登录与账户 > 品牌定制 > 自定义你的 UI 中添加额外允许的来源。

你可以配置：

  • script-src：允许 JavaScript module 或 script 的来源，例如 CAPTCHA、分析工具或 tag manager 服务。
  • connect-src：允许 fetch、XMLHttpRequest、EventSource 和 WebSocket 连接使用的网络端点。

示例：

{
  "scriptSrc": ["https://scripts.example.com"],
  "connectSrc": ["https://api.example.com", "wss://events.example.com"]
}

两个 directive 都应使用 HTTPS origin。对于 WebSocket 连接，connect-src 也支持 wss:// origin。只有当自定义 UI 资源处于启用状态时，Logto 才会将这些来源追加到现有安全策略中。

开发你的自定义 UI​

与 Experience API 交互​

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

你还需要通过 sign-in Experience API endpoint 获取其他登录体验配置，如品牌色、公司 logo、favicon、密码策略、本地化语言短语，甚至自定义 CSS。

启用 CAPTCHA 时的处理方式​

内置的 Logto 登录体验会自动处理 CAPTCHA。如果你的租户使用自定义 UI 并启用了 CAPTCHA 机器人防护，你的自定义 UI 必须在调用 PUT /api/experience 前完成前端 CAPTCHA 集成。

将返回的 provider token 作为 captchaToken 放在 PUT /api/experience 请求体中。具体集成方式请参阅各 provider 指南：

示例项目​

我们提供了一系列示例项目，帮助你快速理解并开始实现自定义 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