mcpField
C
clerk-validator

clerk-validator

github.com/shipshitdev安全38159 次安装2 天前更新
代码仓库

关于 clerk-validator

面向在 Next.js 16 项目中配置或审查 Clerk 认证的开发者。Python 脚本检查包版本、配置和认证写法，并支持严格的 CI 验证模式。

主要功能

  1. 01检查 Clerk 包版本
  2. 02检查 Next.js 16 proxy 与 middleware
  3. 03验证 ClerkProvider 配置
  4. 04检查认证导入写法
  5. 05严格 CI 验证

适用场景

  1. 01审查现有 Clerk 配置
  2. 02检查生成的认证代码
  3. 03实施前验证配置
  4. 04在 CI/CD 中运行认证检查

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/shipshitdev/skills --skill clerk-validator

安装后在 Claude Code 中输入/clerk-validator确认已加载。

附带文件plugin.jsonreferences/full-guide.md

详细介绍

Clerk 验证器

验证 Clerk 身份验证配置，并在 Next.js 16 中强制使用现代 Clerk 模式。

何时启用

  • 设置 Clerk 身份验证
  • 开始任何身份验证实现工作之前
  • 审核现有 Clerk 配置
  • AI 生成 Clerk 代码后
  • CI/CD 流水线验证

快速开始

python3 scripts/validate.py --root .
python3 scripts/validate.py --root . --strict

检查内容

1. 包版本
// GOOD: Latest Clerk
"@clerk/nextjs": "^6.0.0"

// BAD: Old version
"@clerk/nextjs": "^4.0.0"
2. Proxy 与 Middleware（Next.js 16）

正确 - Next.js 16：

// proxy.ts
import { clerkMiddleware } from "@clerk/nextjs/server";
export default clerkMiddleware();

错误 - 已弃用：

// middleware.ts (deprecated in Next.js 16)
import { authMiddleware } from "@clerk/nextjs";  // DEPRECATED
export default authMiddleware();
3. ClerkProvider 设置

正确： 在 app/layout.tsx 中使用 <ClerkProvider> 包裹整个应用。 错误： 将其放在 _app.tsx 中（Pages Router，已弃用），或忘记包裹整个组件树。

完整布局示例请参阅 references/full-guide.md（§ 使用 Clerk 组件的根布局）。

4. 身份验证导入模式

正确 - 服务端：

import { auth } from "@clerk/nextjs/server";

export default async function Page() {
  const { userId } = await auth();
  // ...
}

错误 - 旧模式：

// Don't use
import { getAuth } from "@clerk/nextjs/server";  // OLD
import { currentUser } from "@clerk/nextjs";     // Check version
5. 环境变量

必需：

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...

可选，但建议设置：

NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding

已弃用的模式

已弃用替代方案
authMiddleware()clerkMiddleware()
middleware.tsproxy.ts（Next.js 16）
getAuth()auth()
@clerk/nextjs < v5@clerk/nextjs@latest
_app.tsx 提供程序app/layout.tsx 提供程序
withClerkMiddlewareclerkMiddleware()

验证输出

=== Clerk Validation Report ===
Package Version: @clerk/[email protected] ✓
Configuration: ✓ ClerkProvider  ✓ proxy.ts  ✗ middleware.ts found (deprecated)
Auth Patterns:  ✓ auth()  ✗ authMiddleware() in 1 file (deprecated)
Summary: 2 issues found

现代 Clerk 模式

受保护的路由（服务端组件）

调用 await auth()；如果缺少 userId，则重定向到 /sign-in，并且仅在完成检查后渲染。

完整页面请参阅 references/full-guide.md（§ 受保护的路由示例）。

受保护的路由（客户端组件）

将组件标记为 "use client"，从 useAuth() 读取 { isLoaded, userId }，并在两者都已解析前渲染加载或重定向状态。

完整组件请参阅 references/full-guide.md（§ 使用 Auth Hook）。

API 路由

在路由处理程序中调用 await auth()；如果缺少 userId，则在执行任何工作前返回 401。

完整处理程序请参阅 references/full-guide.md（§ 受保护的 API 路由）。

NestJS Guard

提取 bearer token，使用 clerkClient.verifyToken 验证，并将 userId 附加到请求；任何失败时都返回 false 或抛出异常。

完整 Guard 请参阅 references/full-guide.md（§ 身份验证 Guard）。

Webhook 配置

使用 svix 包，根据 CLERK_WEBHOOK_SECRET 验证 svix-id / svix-timestamp / svix-signature 标头后，再信任负载；绝不要处理未经验证的 webhook 请求体。

完整路由处理程序请参阅 references/full-guide.md（§ Webhooks（Next.js App Router））；NestJS 控制器对应实现请参阅（§ Webhook 处理程序）。

CI/CD 集成

# .github/workflows/validate.yml
- name: Validate Clerk Config
  run: |
    python3 scripts/validate.py \
      --root . \
      --strict \
      --ci

集成

  • nextjs-validator - 验证 Next.js 16（proxy.ts）
  • biome-validator - 验证 lint 配置
  • git-safety - 确保没有提交机密信息

评论

支持 Markdown