在受支持项目中添加或迁移 Clerk 认证：用官方…

需要为任意受支持框架项目接入 Clerk 认证，或从现有认证提供方迁移到 Clerk 时使用。

适用场景

解决思路

1. 检查 `package.json` 中的 Clerk SDK 版本，并参考 `clerk` skill 的版本表；遇到标注 `Core 2 ONLY (skip if current SDK)` 的条目时，仅在 Core 2 版本下采用，当前 SDK 则跳过。
2. 优先用 CLI 自动配置（agent-first）。新项目+新 Clerk app 运行：`clerk init --framework <next|react|vue|nuxt|astro|react-router|tanstack-react-start|expressjs|fastify|expo> -y`；该命令安装 SDK、接入项目，并把框架对应的 publishable/secret key 写入正确 env 文件（Next.js 如 `.env.local`，Vite-based 如 `.env`）。
3. 无账号快速开始：在受支持框架上，不要先运行 `clerk auth login`；直接运行未认证的 `clerk init`，它会创建可认领的无账号应用并把临时开发 key 写入项目 env 文件（无需账号、浏览器或额外 flag）；已认证或传 `--app`/`--login` 时，它会通过 PLAPI 创建并链接真实 app。可用 `--template <b2b-saas|b2c-saas|native|waitlist>` 预配置临时 app。注意：现有项目中的未登录真人仍会进入登录流程，除非传 `--accountless`；`--keyless` 是已废弃兼容别名；`--template`/`--fresh` 在目标为真实 app 时会报错；登录只会自动认领由 `clerk init` 创建的应用。
4. 现有项目+现有 Clerk app：运行 `clerk auth login`（已登录可跳过）；运行 `clerk link`（若 `.env` 中已有 `CLERK_PUBLISHABLE_KEY` 则自动链接）；在 agent 模式必须用显式形式 `clerk link --app app_xxx`；运行 `clerk env pull` 写入框架检测到的 env 变量。
5. 现有项目+新 Clerk app：运行 `clerk auth login`；运行 `clerk apps create "My App" --json` 获取新的 `app_id`；运行 `clerk link --app app_xxx`；运行 `clerk env pull`。
6. 日常操作：用 `clerk env pull` 刷新 key（使用已链接 profile）；用 `clerk env pull --instance prod` 拉取生产 key；用 `clerk doctor --json` 做框架集成健康检查。
7. 轮换 secret key：在友好封装发布前用原始 `clerk api`：`clerk api --platform POST /v1/platform/applications/<app_id>/rotate_secret_keys -d '{"delay_old_secrets_expiration_hours": 24, "reason": "scheduled rotation"}'`；`delay_old_secrets_expiration_hours` 让旧 key 在宽限期内继续有效，以便部署无停机滚动。
8. Agent 注意事项：由 `clerk init` 创建的未认领无账号应用可免账号配置，具体哪些命令可用、哪些需要已认领 app 参考 accountless 命令表。`clerk link`（无 flag）仅在 `.env`/`.env.local` 已有 `CLERK_PUBLISHABLE_KEY` 时自动链接；否则 agent 模式报错 `Cannot select an application in agent mode.`，此时运行 `clerk apps list --json`，询问用户要链接哪个 `app_id`，不要猜测。在 `apps list/create`、`users create`、`doctor` 上传 `--json` 以获得可解析输出。CLI 会自动检测框架 env 变量名（Vite 为 `VITE_CLERK_PUBLISHABLE_KEY`，Next.js 为 `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` 等）和目标文件（优先级 `.env.development.local` > `.env.local` > `.env`）。
9. 如果 CLI 不可用（沙箱环境、文档演练），走手动 Dashboard 路径：1) 检查 `package.json` 依赖以检测框架；2) 对相应 docs URL 使用 WebFetch 获取 quickstart；3) 执行步骤，Next.js 创建 `proxy.ts`（Next.js <=15 用 `middleware.ts`）；4) 从 `dashboard.clerk.com/~/api-keys` 获取 API keys。若存在 `components.json`（shadcn/ui），安装后应用 shadcn 主题（见 `clerk-custom-ui` 的 shadcn Theme）。
10. 框架检测：读取 `package.json` 依赖并匹配：`next`→Next.js→`https://clerk.com/docs/nextjs/getting-started/quickstart`；`@remix-run/react`→Remix（已废弃）→迁移到 React Router v7 并使用 React Router quickstart；`react-router`→React Router v7+→`https://clerk.com/docs/react-router/getting-started/quickstart`；`astro`→Astro→`https://clerk.com/docs/astro/getting-started/quickstart`；`nuxt`→Nuxt→`https://clerk.com/docs/nuxt/getting-started/quickstart`；`@tanstack/react-start`→TanStack Start→`https://clerk.com/docs/tanstack-react-start/getting-started/quickstart`；`react`（无框架）→React SPA→`https://clerk.com/docs/react/getting-started/quickstart`；`vue`→Vue→`https://clerk.com/docs/vue/getting-started/quickstart`；`express`→Express→`https://clerk.com/docs/expressjs/getting-started/quickstart`；`fastify`→Fastify→`https://clerk.com/docs/fastify/getting-started/quickstart`；`expo`→Expo→`https://clerk.com/docs/expo/getting-started/quickstart`。
11. 其他平台 quickstart：Chrome Extension `https://clerk.com/docs/chrome-extension/getting-started/quickstart`；Android `https://clerk.com/docs/android/getting-started/quickstart`；iOS `https://clerk.com/docs/ios/getting-started/quickstart`；Vanilla JavaScript `https://clerk.com/docs/js-frontend/getting-started/quickstart`。
12. 决策树执行：读取 `package.json`；若检测到已有认证，则先审计并制定迁移计划；若没有，则全新安装；识别框架后用 WebFetch 获取 quickstart 并照做；若为 Next.js，创建 `proxy.ts`（Next.js <=15 为 `middleware.ts`）；若存在 `components.json`，应用 shadcn 主题（见 `clerk-custom-ui`）。
13. 安装流程第 1 步：读取项目 `package.json`，将依赖匹配到框架表。
14. 安装流程第 2 步：用 WebFetch 获取官方 quickstart：`WebFetch: https://clerk.com/docs/{framework}/getting-started/quickstart`，提示词为 `"Extract the complete setup instructions including all code snippets, file paths, and configuration steps."`。
15. 安装流程第 3 步：执行 quickstart 每一步——安装所需包；设置环境变量；添加 provider 和 proxy/middleware；如需要创建 sign-in/sign-up 路由；测试集成。Next.js 创建 `proxy.ts`（Next.js <=15 为 `middleware.ts`），middleware 策略见 `clerk-nextjs-patterns`。检测到 shadcn/ui（存在 `components.json`）时，始终应用 shadcn 主题，见 `clerk-custom-ui` 的 shadcn Theme。
16. 安装流程第 4 步：获取 API keys。CLI 自动路径：`clerk init` 把临时开发 key 写入项目 env 文件，无需 Clerk 账号；准备好后运行 `clerk auth login`，应用会被自动认领进 Clerk 账号，从而可在 Dashboard 编辑；新项目用这条最简单。手动 Dashboard 路径：从 `dashboard.clerk.com/~/api-keys` 获取 key；Publishable Key 以 `pk_test_` 或 `pk_live_` 开头；Secret Key 以 `sk_test_` 或 `sk_live_` 开头；设置环境变量 `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` 和 `CLERK_SECRET_KEY`。
17. 从其他认证提供方迁移时，若项目已有认证，替换前先创建迁移计划。检测现有认证：检查 `package.json` 中的库：`next-auth`/`@auth/core`→NextAuth/Auth.js；`@supabase/supabase-js`→Supabase Auth；`firebase`/`firebase-admin`→Firebase Auth；`@aws-amplify/auth`→AWS Cognito；`auth0`/`@auth0/nextjs-auth0`→Auth0；`passport`→Passport.js；自定义 JWT/session 实现。
18. 迁移流程：1) 审计当前认证——识别所有认证触点：sign-in/sign-up 页面；session/token 处理；受保护路由与 middleware；用户数据存储（数据库表、外部 ID）；已配置的 OAuth providers。2) 创建迁移计划——考虑：用户数据导出，导出用户并通过 Clerk Backend API 导入；密码哈希，Clerk 可透明升级到 Bcrypt；外部 ID，把旧用户 ID 存为 Clerk 中的 `external_id`；session 处理，切换时现有 session 会终止。3) 选择迁移策略：Big bang——一次性切换所有用户（更简单，需要维护窗口）；Trickle migration——临时并行运行两套系统（风险更低，复杂度更高）。迁移参考：`https://clerk.com/docs/guides/development/migrating/overview`。
19. SDK 包名：Next.js 安装 `@clerk/nextjs`；React 安装 `@clerk/react`；Expo 安装 `@clerk/expo`；React Router 安装 `@clerk/react-router`；TanStack Start 安装 `@clerk/tanstack-react-start`。Core 2 ONLY：React 和 Expo 包名不同，为 `@clerk/clerk-react` 和 `@clerk/clerk-expo`（带 `clerk-` 前缀）。
20. Next.js 中 `ClerkProvider` 放置：必须放在 `<body>` 内部，不要包住 `<html>`：`<html><body><ClerkProvider>{children}</ClerkProvider></body></html>`。Core 2 ONLY：`ClerkProvider` 可以直接包住 `<html>`。
21. Next.js 动态渲染：需要带认证数据的动态渲染时使用 `dynamic` prop：`<ClerkProvider dynamic>{children}</ClerkProvider>`。
22. Node.js 要求：需要 Node.js 20.9.0 或更高。Core 2 ONLY：最低 Node.js 18.17.0。
23. Themes 包：从 `@clerk/ui` 安装：`npm install @clerk/ui`。Core 2 ONLY：主题来自 `@clerk/themes` 而不是 `@clerk/ui`。
24. shadcn 主题：若项目使用 shadcn/ui（项目根目录有 `components.json`），应用 shadcn 主题让 Clerk 组件匹配设计系统：`npm install @clerk/ui`；`import { shadcn } from '@clerk/ui/themes'`；`<ClerkProvider appearance={{ theme: shadcn }}>{children}</ClerkProvider>`；在全局样式中导入 shadcn CSS：`@import 'tailwindcss'; @import '@clerk/ui/themes/shadcn.css';`。Core 2 ONLY：改为从 `@clerk/themes` 和 `@clerk/themes/shadcn.css` 导入。
25. 常见坑：先运行 `clerk doctor`；它检查框架集成、环境变量、middleware 是否存在、SDK 安装状态，并一次性修复很多问题。
26. 常见坑修复：`auth()` 缺少 `await`——Next.js 15+ 中 `auth()` 是异步：`const { userId } = await auth()`；暴露 `CLERK_SECRET_KEY`——绝不在客户端代码使用 secret key，只有 `NEXT_PUBLIC_*` key 安全；middleware matcher 缺失——包含 API routes：`matcher: ['/((?!.*\\..*|_next).*)', '/']`；`ClerkProvider` 放置——root layout 中必须在 `<body>` 内（Core 2 可包 `<html>`）；认证路由未公开——在 middleware 配置中允许 `/sign-in`、`/sign-up`；落地页要求认证——要保持 `/` 公开，排除它：`matcher: ['/((?!.*\\..*|_next|^/$).*)', '/api/(.*)']`；导入路径错误——服务端代码用 `@clerk/nextjs/server`，客户端用 `@clerk/nextjs`；包名错误——用 `@clerk/react` 而不是 `@clerk/clerk-react`（Core 2 命名）。
27. 参见/相关技能：`clerk-custom-ui` 自定义 sign-in/up 组件；`clerk-nextjs-patterns` 高级 Next.js 模式；`clerk-react-patterns` React SPA 模式；`clerk-react-router-patterns` React Router 模式；`clerk-vue-patterns` Vue 模式；`clerk-nuxt-patterns` Nuxt 模式；`clerk-astro-patterns` Astro 模式；`clerk-tanstack-patterns` TanStack Start 模式；`clerk-chrome-extension-patterns` Chrome Extension 模式；`clerk-orgs` B2B 多租户组织；`clerk-webhooks` Webhook→数据库同步；`clerk-testing` E2E 测试设置；`clerk-swift` 原生 iOS 认证；`clerk-android` 原生 Android 认证；`clerk-expo` Expo/React Native 认证；`clerk-backend-api` 后端 REST API 浏览器。
28. 文档链接：Quickstart Overview `https://clerk.com/docs/getting-started/quickstart/overview`；Migration Guide `https://clerk.com/docs/guides/development/migrating/overview`；Full Documentation `https://clerk.com/docs`。

适用边界 · 注意事项

• 不想引入 Clerk 服务/账号，或必须完全自托管认证时。
• 目标框架或平台不在 Clerk quickstart 支持列表，或无法满足 Node.js 20.9.0+（Core 2 为 18.17.0+）时。
• 项目已有认证但无法安排迁移窗口、无法处理用户数据/密码哈希/session 迁移时。