自定义你的 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 资源
在生产环境中使用此功能时请谨慎操作，因为它会立即影响用户的登录体验。
- 进入 控制台 > 登录与账户 > 品牌定制 > 自定义你的 UI。
- 点击选择或拖拽你在上一步创建的 zip 文件，上传过程会自动开始。
- 上传完成后，保存更改，你的自定义 UI 会立即生效。
- 使用自定义登录 UI 时，“登录预览”窗口将被禁用。但你仍可点击“实时预览”按钮，在新打开的浏览器标签页中测试你的自定义登录页面。
配置自定义 CSP 源
Logto 会为自定义 UI 页面添加内容安全策略（CSP）头。如果你的自定义 UI 加载第三方脚本或连接外部服务，请在 控制台 > 登录与账户 > 品牌定制 > 自定义你的 UI 中添加额外的源地址。
你可以配置：
script-src：允许 JavaScript 模块或脚本来源，如验证码、分析或标签管理器服务商。connect-src：允许fetch、XMLHttpRequest、EventSource 和 WebSocket 连接使用的网络端点。
示例：
{
"scriptSrc": ["https://scripts.example.com"],
"connectSrc": ["https://api.example.com", "wss://events.example.com"]
}
两项都应使用 HTTPS 源。connect-src 也接受 WebSocket 连接的 wss:// 源。Logto 仅在你的自定义 UI 资源生效时，将这些源追加到现有安全策略中。
配置 Cross-Origin-Opener-Policy 头
默认情况下，Logto 不发送 Cross-Origin-Opener-Policy（COOP）头，因此在弹窗中打开登录页面的应用可以通过 window.opener 与其通信。如果你的应用不通过弹窗登录，可以将自定义登录 UI 与其他浏览器窗口隔离。在 控制台 > 登录与账户 > 品牌定制 > 自定义你的 UI 下选择 Cross-Origin-Opener-Policy 策略：
| 选项 | 发送的头部 | 效果 |
|---|---|---|
| 未设置（无头部） | 无 | 默认。所有基于弹窗的集成均可正常工作。 |
same-origin-allow-popups | Cross-Origin-Opener-Policy: same-origin-allow-popups | 切断打开登录页面的窗口。自定义 UI 打开的弹窗只要停留在其他站点，仍保留 window.opener。 |
same-origin | Cross-Origin-Opener-Policy: same-origin | 也会切断自定义 UI 打开的弹窗。 |
你也可以通过 更新登录体验 Management API 设置 crossOriginOpenerPolicy 字段。它接受 unsafe-none（默认，不发送头部）、same-origin-allow-popups 和 same-origin。
在选择策略前，请检查你的应用和自定义 UI 如何使用弹窗：
- 如果应用通过弹窗打开登录页面并依赖
window.opener（例如通过postMessage接收结果），则在任一策略下都无法正常工作。在有此类应用时请保持默认，或先迁移到基于重定向的登录流程。 - 自定义 UI 打开的弹窗一旦跳回自定义 UI（如社交登录回调页），就会失去
window.opener。如果弹窗停留在其他站点并从那里发送结果（如服务商自己的登录弹窗），在same-origin-allow-popups下仍可正常工作。使用same-origin时，弹窗一打开就会失去window.opener。
如需设置策略，优先选择 same-origin-allow-popups 而非 same-origin。
Logto 仅在你的自定义 UI 资源被访问时发送该头部。内置登录页面、/oidc/* 页面和账户中心（/account）不会发送 COOP 头，因此安全扫描器可能仍会报告这些页面缺少该头部。
开发你的自定义 UI
与 Experience API 交互
你的自定义 UI 需要与 Experience API 交互，以完成登录、注册、重置密码、绑定社交账号、开启 MFA 等操作。为更好地理解用户流程和实现细节，建议查阅我们的 Experience API 设计 RFC，其中提供了全面的技术规范和示例。
你还需要通过 登录体验 API endpoint 获取其他登录体验配置，如品牌色、公司 logo、favicon、密码策略、本地化语言短语，甚至自定义 CSS。
启用验证码时的处理方式
内置的 Logto 登录体验会自动处理验证码。如果你的租户使用自定义 UI 并启用了验证码防护，你的自定义 UI 必须在调用 PUT /api/experience 前完成前端验证码集成。
将验证码服务商返回的 token 作为 captchaToken，放在 PUT /api/experience 请求体中。具体集成方式请参考服务商指南：
示例项目
我们提供了一系列示例项目，帮助你快速理解并实现自定义 UI。请访问 Logto Experience project 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