clerk-setup

设置 Clerk

使用 Clerk CLI 添加身份验证。在 Agent 环境中，受支持的框架默认采用无需账户的设置：npx -y clerk@latest init 会配置一个可认领的应用，并写入临时开发密钥，无需 Clerk 账户。

开始之前

向用户展示此检查清单，并等待用户确认：

Here's what I'll do to get you set up with Clerk.

1. Set up Clerk in this project, or scaffold a new app if this directory is empty.
2. Install Clerk's agent skills for the coding agents on this machine, if they aren't installed yet.
3. Start your app with Clerk installed.

Shall I proceed?

现有身份验证

在运行 init 之前，检查身份验证依赖项、路由、中间件、会话和用户记录——切勿检查环境文件。如果存在其他身份验证提供商，请停止操作，并获得用户对迁移计划的批准；迁移计划应涵盖：

• 后端 API 用户导入、稳定的外部 ID、兼容的密码哈希和 OAuth 连续性。
• 受保护的路由、令牌、会话切换和发布策略。

未经批准，不要修改或移除现有身份验证。

请参阅迁移指南。

现有 Clerk 项目

对于原生 iOS 或 macOS 应用，请改为遵循 iOS 设置提示词。它会复用已关联的应用，并保留现有配置。

如果项目已使用 Clerk，请在步骤 1a 和 1b 中跳过 init：未登录的 Agent 运行可能会创建另一个应用，并替换项目的 Clerk 密钥。如果 Clerk 已正常工作，且用户要求进行设置，请告知用户无需设置。如果用户报告密钥缺失，请按照下方的“使用现有 Clerk 应用”分支恢复密钥。如果检查发现缺少提供商、中间件或身份验证路由，只需在步骤 2 中根据匹配的快速入门添加这些部分。切勿创建替代应用。

更改任何内容之前，请检查 Clerk 软件包的版本，并使用 clerk skill 中的版本表确定其 SDK 代际。除非用户要求升级，否则请保留该代际；对于 Core 2 项目，请在以下每个步骤中应用这些差异：

• React 和 Expo 使用 @clerk/clerk-react 和 @clerk/clerk-expo，而不是 @clerk/react 和 @clerk/expo。
• 控制组件使用 <SignedIn> 和 <SignedOut>，而不是 <Show>。
• Next.js 的 ClerkProvider 可以包裹 <html>，而不是放在 <body> 内。
• Node.js 的最低版本为 18.17.0，而不是 20.9.0。
• 主题来自 @clerk/themes 和 @clerk/themes/shadcn.css，而不是 @clerk/ui。

使用现有 Clerk 应用（可选）

如果用户要求使用现有 Clerk 应用，或现有 Clerk 项目需要恢复密钥，请遵循此分支。在指定账户级资源之前，让用户先在其主机终端中完成身份验证：

npx -y clerk@latest auth login

如果用户提供了应用 ID，请根据情况在 init 或 link 中使用该 ID。否则，请列出应用：

npx -y clerk@latest apps list --json

显示名称和 ID，并询问用户要使用哪个应用。切勿替用户选择应用。对于新的 Clerk 集成，请将选定的 ID 作为 --app <application_id> 传递给 init。对于已使用 Clerk 的项目，不要运行 init。如果项目尚未关联所选应用，请关联它：

npx -y clerk@latest link --app <application_id>

如果开发密钥缺失，请拉取密钥：

npx -y clerk@latest env pull

只有在用户需要生产密钥时，才使用 npx -y clerk@latest env pull --instance prod。未经用户确认，不要替换可用密钥或切换应用。

步骤 1a：尚未集成 Clerk 的现有项目

对于在 Xcode 中开发的原生 iOS 或 macOS 应用，请按照 iOS 设置提示词操作，而不要继续执行后续步骤。

对于尚未集成 Clerk 的项目，请在项目根目录运行：

npx -y clerk@latest init

init 会检测框架和包管理器、安装 SDK，并配置提供程序、中间件、身份验证路由和环境。它还会全局安装 Clerk 的 Agent 技能。如果用户拒绝安装，或者这些技能已可用（例如，你已将其作为 clerk-setup 技能加载），请添加 --no-skills 跳过此步骤。除非用户要求，否则不要传入 --framework 或 --pm。只有在用户选择了上方可选分支中的应用时，才添加 --app <application_id>。

步骤 1b：空目录

对于原生 iOS 或 macOS 应用，请按照 iOS 设置提示词操作，而不要继续执行后续步骤。该提示词涵盖了创建 Xcode 项目。

询问用户要使用哪种框架和包管理器，默认使用 Next.js 和 npm：

npx -y clerk@latest init --framework <framework> --pm <package-manager>

init 会在新的子目录（例如 my-clerk-next-app）中创建应用，而不是在当前目录中创建。请在该子目录中执行后续步骤。与步骤 1a 一样，如果 Clerk 的技能已可用，或用户拒绝安装，请添加 --no-skills。

init 可以创建 Next.js、React Router、Astro、Nuxt、TanStack Start、React、Vue、JavaScript/Vite 和 Expo 应用。对于 Express、Fastify 或 Android，请先使用相应平台自己的工具创建项目，然后按照步骤 1a 操作。

步骤 1c：无需账户的开发密钥

对于使用支持无需账户模式的框架（Next.js、React Router、Astro、Nuxt 或 TanStack Start）的未登录用户，init 会配置一个可认领的应用，并将临时密钥写入检测到的环境文件。请转告用户 CLI 输出的文件名和认领说明。在用户运行 npx -y clerk@latest auth login 之前，该应用会一直处于未认领状态；除非用户要求，否则不要运行此命令。只有在用户已登录时，才使用 --accountless 强制启用此流程。

不支持无需账户模式的框架需要真实的 API 密钥。对于这类框架，init 会完成可执行的设置，并输出剩余步骤。

第 2 步：初始化不完整时改用文档

如果 init 报告框架不受支持或未检测到框架，请改用快速入门。如果命令已完成但输出了剩余步骤，请按步骤操作；未涵盖的内容则参考对应的快速入门。

对于缺少集成文件的现有 Clerk 项目，请参考对应的快速入门，只添加缺少的部分，不要运行 init。

init 可配置 Next.js、React、React Router、Nuxt、TanStack Start、Astro、Vue、JavaScript/Vite、Expo、Express 和 Fastify 项目，以及现有的 iOS 和 macOS Xcode 项目（参见 iOS 设置提示）。对于 Android，它只会输出设置步骤，因此请参考快速入门。

使用对应的快速入门：

• Next.js
• React
• React Router
• Nuxt
• TanStack Start
• Astro
• Vue
• JavaScript 或 Vite
• Expo
• Express
• Fastify
• iOS
• Android
• Chrome 扩展

其他情况请使用 Clerk 的 llms.txt。

第 3 步：添加可见的身份验证控件

仅后端项目（例如 Express 或 Fastify API）可跳过此步骤。对于 Expo、iOS 和 Android，请改用对应快速入门中的原生组件。

Web 应用需要登录、注册和已登录用户控件，并将它们整合到现有布局或导航中。如果这些控件已存在，请调整现有控件，而不是重复添加。

对于 Next.js App Router，如果 <Show> 在 Server Component 中渲染，它会读取请求，因此请将其包裹在 <Suspense> 中：

import { SignInButton, SignUpButton, Show, UserButton } from '@clerk/nextjs'
import { Suspense } from 'react'

<Suspense>
  <Show when="signed-out">
    <SignInButton />
    <SignUpButton />
  </Show>
  <Show when="signed-in">
    <UserButton />
  </Show>
</Suspense>

Astro 从 @clerk/astro/components 导入组件。Nuxt 会自动导入组件；显式导入时使用 @clerk/nuxt/components。其他框架使用其 Clerk 包中的相同名称，例如 @clerk/vue 或 @clerk/react。

第 4 步：验证

npx -y clerk@latest doctor

然后启动应用，确认身份验证控件已渲染，并修复 CLI 报告的任何问题。

机器人防护可能会阻止你在自动化浏览器中注册。如果要在此类浏览器中测试一个尚无账户的新应用，请运行 npx -y clerk@latest users create --email <unique>[email protected] --password <random-16-char-alphanumeric> --yes，然后登录。如果系统要求输入验证码，请输入 424242。告知用户你创建了这个测试用户。对于现有应用，创建用户前请先征求用户同意。要测试注册，请使用 @clerk/testing。

第 5 步：使用 shadcn/ui 时

如果项目根目录中存在 components.json，请使用项目的包管理器添加 @clerk/ui。根据锁文件选择命令：pnpm-lock.yaml → pnpm add，yarn.lock → yarn add，bun.lock 或 bun.lockb → bun add，package-lock.json → npm install。

在 provider 中应用主题：

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

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

添加到全局 CSS：

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

关键规则

• 当前 Clerk SDK 需要使用 Node.js 20.9.0 或更高版本。
• Next.js 15+：auth() 是异步的。务必使用 await auth()。
• Next.js：当 next.config 设置 cacheComponents: true（create-next-app 的默认设置）时，如果在 <Suspense> 外读取请求数据，next build 会失败。请将 Server Component 中渲染的 <Show>，以及任何调用 auth() 或 currentUser() 的 Server Component，都放在 <Suspense> 中，并尽可能靠近依赖身份验证的 UI。还请将兜底路由中的 <SignIn />、<SignUp />、<UserProfile /> 和 <OrganizationProfile /> 页面放在 <Suspense> 中，包括 Clerk CLI 创建的登录和注册页面。请参阅在 Suspense 内读取身份验证数据和兜底路由中的预构建组件。
• 对于当前的 Next.js SDK，ClerkProvider 应放在 <body> 内，而不是包裹 <html>。
• 切勿在客户端代码中暴露 CLERK_SECRET_KEY。
• 对于全新配置，请使用当前框架的包，例如 @clerk/nextjs、@clerk/react、@clerk/expo、@clerk/react-router 或 @clerk/tanstack-react-start。
• 不要读取或打印现有的环境变量文件；如缺少非敏感配置，请向用户询问。

完成设置后

请让用户注册成为第一个测试用户。导航栏中出现个人资料图标后，向他们表示祝贺。

然后询问他们希望用户如何注册和登录——使用哪些标识符（电子邮件、电话、用户名）和社交身份提供商。要更改这些设置，必须先认领应用：请用户先运行 npx -y clerk@latest auth login，然后使用 npx -y clerk@latest config pull 查看配置，并使用 npx -y clerk@latest config patch 修改配置（支持 --dry-run）；也可以使用 Clerk Dashboard。详情请参阅注册和登录选项。

上线前，请让用户通过 npx -y clerk@latest auth login 认领应用，然后使用 npx -y clerk@latest deploy 配置生产环境。未认领的应用和临时密钥无法用于生产环境。

接着询问他们是否需要 Organizations——多租户、团队邀请、角色与权限，以及企业 SSO。

如果需要：

1. 运行 npx -y clerk@latest enable orgs。
2. 在现有的 <UserButton /> 旁添加 <OrganizationSwitcher />，或使用对应框架的等效组件。
3. 让他们通过切换器创建一个组织并邀请一位队友。

如果不需要，请指引他们查看 Organizations、Components 和 Clerk Dashboard。