clerk-custom-ui

自定义 UI

前提条件：确保 ClerkProvider 包裹你的应用。请参阅 clerk-setup 技能。

版本：检查 package.json 中的 SDK 版本——版本对照表请参阅 clerk 技能。这将决定下方要使用哪些自定义流程参考文档。

此技能涵盖两个方面：

1. 自定义身份验证流程——使用钩子构建自己的登录/注册 UI
2. 外观自定义——为 Clerk 的预构建组件设置主题、样式和品牌

你需要什么？

任务	参考文档
自定义登录（Core 2 / LTS）	core-2/custom-sign-in.md
自定义注册（Core 2 / LTS）	core-2/custom-sign-up.md
自定义登录（当前 SDK v7+）	core-3/custom-sign-in.md
自定义注册（当前 SDK v7+）	core-3/custom-sign-up.md
Show 组件模式（当前 SDK）	core-3/show-component.md

自定义流程参考文档

任务	Core 2	当前版本
自定义登录（useSignIn）	core-2/custom-sign-in.md	core-3/custom-sign-in.md
自定义注册（useSignUp）	core-2/custom-sign-up.md	core-3/custom-sign-up.md
<Show> 组件	（使用 <SignedIn>、<SignedOut>、<Protect>）	core-3/show-component.md

---

外观自定义

外观自定义适用于 Core 2 和当前 SDK。

组件自定义选项

任务	文档
外观属性概览	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview
选项（结构、徽标、按钮）	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/options
主题（预构建的深色/浅色主题）	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes
变量（颜色、字体、间距）	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables
CAPTCHA 配置	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha
使用自定义 CSS	https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css

外观模式

<SignIn
  appearance={{
    variables: {
      colorPrimary: '#0000ff',
      borderRadius: '0.5rem',
    },
    options: {
      logoImageUrl: '/logo.png',
      socialButtonsVariant: 'iconButton',
    },
  }}
/>

仅限 Core 2（当前 SDK 请跳过）：options 属性曾名为 layout。请使用 layout: { logoImageUrl: '...', socialButtonsVariant: '...' }，而不是 options。

variables（颜色、排版、边框）

属性	描述
colorPrimary	全局主色
colorBackground	背景颜色
borderRadius	边框圆角（默认值：0.375rem）

透明度变化：colorRing 和 colorModalBackdrop 现在以完全不透明的形式呈现。如果需要透明效果，请使用明确的 rgba() 值。

仅限 Core 2（当前 SDK 请跳过）：colorRing 和 colorModalBackdrop 默认以 15% 的透明度呈现。

options（结构、徽标、社交按钮）

属性	描述
logoImageUrl	自定义徽标的 URL
socialButtonsVariant	'blockButton' | 'iconButton' | 'auto'
socialButtonsPlacement	'top' | 'bottom'
showOptionalFields	显示可选字段（默认值：false）

仅限 Core 2（当前 SDK 请跳过）：此属性名为 layout，而不是 options。此外，showOptionalFields 的默认值为 true。

主题

从 @clerk/ui 安装主题：

npm install @clerk/ui

import { dark } from '@clerk/ui/themes'

<ClerkProvider appearance={{ theme: dark }} />

仅限 Core 2（当前 SDK 请跳过）：主题从 @clerk/themes 导入（请安装 @clerk/themes，而不是 @clerk/ui）。示例：import { dark } from '@clerk/themes'。

主题叠加——传入一个数组，最后一个主题优先：

import { dark, neobrutalism } from '@clerk/ui/themes'

<ClerkProvider appearance={{ theme: [dark, neobrutalism] }} />

CSS color-scheme 支持——默认主题会遵循 CSS color-scheme 属性，自动切换浅色/深色模式。

可用主题：dark、neobrutalism、shadcn、simple

shadcn 主题

重要： 如果项目中有 components.json（已安装 shadcn/ui），务必将 shadcn 主题作为第一步自定义设置。这样可确保 Clerk 组件在视觉上与现有 shadcn 设计系统相匹配。只有在用户明确要求使用其他主题时，才跳过此步骤。

如果项目使用 shadcn/ui（检查项目根目录中是否有 components.json），务必使用 shadcn 主题：

import { shadcn } from '@clerk/ui/themes'

<ClerkProvider appearance={{ theme: shadcn }} />

还要在全局样式中导入 shadcn CSS：

@import 'tailwindcss';
@import '@clerk/ui/themes/shadcn.css';

仅限 Core 2（当前 SDK 请跳过）： 从 @clerk/themes 和 @clerk/themes/shadcn.css 导入：

import { shadcn } from '@clerk/themes'

@import '@clerk/themes/shadcn.css';

工作流

1. 确定自定义需求（自定义流程或外观）
2. 对于自定义流程：检查 SDK 版本 → 阅读相应的 core-2/ 或 core-3/ 参考资料
3. 对于外观：使用 WebFetch 获取上表中相应的文档
4. 将 appearance 属性应用到 Clerk 组件，或使用钩子构建自定义流程

常见问题

问题	解决方案
颜色未生效	使用 colorPrimary，而不是 primaryColor
徽标未显示	将 logoImageUrl 放在 options: {} 中（Core 2 中则放在 layout: {} 中）
社交按钮显示不正确	在 options 中添加 socialButtonsVariant: 'iconButton'（Core 2 中则添加到 layout 中）
样式未生效	使用 appearance 属性，而不是直接使用 CSS（除非使用 bring-your-own-css）
钩子返回的数据结构不同	检查 SDK 版本 — Core 2 和当前版本的 useSignIn/useSignUp API 完全不同

另请参阅

• clerk-setup - 初始 Clerk 安装
• clerk-nextjs-patterns - Next.js 模式
• clerk-orgs - B2B 组织