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 项目

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

更改任何内容前，先检查 Clerk 软件包版本，并使用 Clerk 技能中的版本表识别其 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 的现有项目

对于尚未使用 Clerk 的项目，从项目根目录运行：

npx -y clerk@latest init

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

第 1b 步：空目录

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

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

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

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

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

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

不支持无需账户流程的框架需要真实的 API 密钥。在这些框架中，init 会尽可能完成设置，并打印剩余步骤。

第 2 步：init 未完成时改用文档

如果 init 提示框架不受支持或无法检测到，请改为按照快速入门操作。如果执行完成但打印了剩余步骤，请按照这些步骤操作，并针对未涵盖的内容使用相应的快速入门。

对于缺少集成文件的现有 Clerk 项目，请使用相应的快速入门，仅添加缺失的部分，不要运行 init。

init 可以配置 Next.js、React、React Router、Nuxt、TanStack Start、Astro、Vue、JavaScript/Vite、Expo、Express 和 Fastify 项目。对于 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：

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

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

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 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。