workos-authkit-nextjs

适用于 Next.js 的 WorkOS AuthKit

步骤 1：获取 SDK 文档（阻塞）

停止。在完成之前不要继续。

WebFetch：https://github.com/workos/authkit-nextjs/blob/main/README.md

README 是事实来源。如果此技能与 README 冲突，请以 README 为准。

步骤 2：预检验证

项目结构

• 确认存在 next.config.js 或 next.config.mjs
• 确认 package.json 包含 "next" 依赖项

环境变量

检查 .env.local 中的以下变量：

• WORKOS_API_KEY - 以 sk_ 开头
• WORKOS_CLIENT_ID - 以 client_ 开头
• NEXT_PUBLIC_WORKOS_REDIRECT_URI - 有效的回调 URL
• WORKOS_COOKIE_PASSWORD - 长度至少为 32 个字符

步骤 3：安装 SDK

检测包管理器，并根据 README 安装 SDK 包。

**验证：**继续之前，确认 SDK 包已存在于 node_modules 中。

步骤 4：版本检测（决策树）

从 package.json 中读取 Next.js 版本：

Next.js version?
  |
  +-- 16+ --> Create proxy.ts at project root
  |
  +-- 15   --> Create middleware.ts (cookies() is async - handlers must await)
  |
  +-- 13-14 --> Create middleware.ts (cookies() is sync)

**关键：**文件必须位于项目根目录（或使用 src 目录时位于 src/）。绝不能放在 app/ 中。

**Next.js 15+ 异步说明：**所有访问 cookie 的路由处理程序和中间件都必须是异步的，并正确等待 cookie 操作。这是相较于 Next.js 14 的破坏性变更。

中间件/代理代码：参见 README 中的 authkitMiddleware() 导出模式。

现有中间件（重要）

如果 middleware.ts 已包含自定义逻辑（速率限制、日志记录、标头等），请使用 authkit() 可组合函数，而不是 authkitMiddleware。

与现有中间件组合的模式：

import { NextRequest, NextResponse } from 'next/server';
import { authkit, handleAuthkitHeaders } from '@workos-inc/authkit-nextjs';

export default async function middleware(request: NextRequest) {
  // 1. Get auth session and headers from AuthKit
  const { session, headers, authorizationUrl } = await authkit(request);
  const { pathname } = request.nextUrl;

  // 2. === YOUR EXISTING MIDDLEWARE LOGIC ===
  // Rate limiting, logging, custom headers, etc.
  const rateLimitResult = checkRateLimit(request);
  if (!rateLimitResult.allowed) {
    return new NextResponse('Too Many Requests', { status: 429 });
  }

  // 3. Protect routes - redirect to auth if needed
  if (pathname.startsWith('/dashboard') && !session.user && authorizationUrl) {
    return handleAuthkitHeaders(request, headers, {
      redirect: authorizationUrl,
    });
  }

  // 4. Continue with AuthKit headers properly handled
  return handleAuthkitHeaders(request, headers);
}

关键函数：

• authkit(request) - 返回 { session, headers, authorizationUrl }，用于组合
• handleAuthkitHeaders(request, headers, options?) - 确保 AuthKit 标头能够正确传递
• 对于重写，请使用 partitionAuthkitHeaders() 和 applyResponseHeaders()（参见 README）

**关键：**始终通过 handleAuthkitHeaders() 返回，以确保 withAuth() 在页面中正常工作。

步骤 5：创建回调路由

解析 NEXT_PUBLIC_WORKOS_REDIRECT_URI 以确定路由路径：

URI path          --> Route location
/auth/callback    --> app/auth/callback/route.ts
/callback         --> app/callback/route.ts

使用 SDK 中的 handleAuth()。不要编写自定义 OAuth 逻辑。

**Next.js 15+ 的关键要求：**路由处理程序必须是异步的，并正确等待 handleAuth()：

// CORRECT - Next.js 15+ requires async route handlers
export const GET = handleAuth();

// If handleAuth returns a function, ensure it's awaited in request context

查看 README 以了解确切用法。如果构建失败并提示 "cookies outside request scope"，很可能是处理程序缺少 async/await。

步骤 6：设置 Provider（必需）

**关键：**必须在 app/layout.tsx 中使用 AuthKitProvider 包裹应用。

这对于以下功能是必需的：

• 通过 useAuth() hook 获取客户端身份验证状态
• 确保客户端/服务端边界之间的身份验证体验一致
• 正确地从 Auth0 迁移（Auth0 使用客户端身份验证）

// app/layout.tsx
import { AuthKitProvider } from '@workos-inc/authkit-nextjs';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthKitProvider>{children}</AuthKitProvider>
      </body>
    </html>
  );
}

查看 README 以确认准确的导入路径——它可能是类似 @workos-inc/authkit-nextjs/components 的子路径导出。

即使在其他地方使用服务端身份验证模式，也不要跳过此步骤。

步骤 7：UI 集成

在 app/page.tsx 中使用 SDK 函数添加身份验证 UI。参见 README 中 getUser、getSignInUrl、signOut 的用法。

验证清单（必须全部通过）

运行以下命令以确认集成。全部通过之前，不要标记为完成：

# 1. Check middleware/proxy exists (one should match)
ls proxy.ts middleware.ts src/proxy.ts src/middleware.ts 2>/dev/null

# 2. CRITICAL: Check AuthKitProvider is in layout (REQUIRED)
grep "AuthKitProvider" app/layout.tsx || echo "FAIL: AuthKitProvider missing from layout"

# 3. Check callback route exists
find app -name "route.ts" -path "*/callback/*"

# 4. Build succeeds
npm run build

**如果检查 #2 失败：**返回步骤 6 并添加 AuthKitProvider。这不是可选项。

错误恢复

“cookies was called outside a request scope”（Next.js 15+）

**最常见原因：**路由处理程序未正确设置为异步，或缺少 await。

回调路由的修复方法：

1. 确认直接导出了 handleAuth()：export const GET = handleAuth();
2. 如果使用自定义封装，请确保其为 async，并等待所有 cookie 操作
3. 确认 authkit-nextjs SDK 版本支持 Next.js 15+（查看 README 了解兼容性）
4. 绝不要在模块级别调用 cookies()——只能在请求处理程序内调用

此错误会导致 OAuth 代码过期（“invalid_grant”），因此请优先修复处理程序。

“middleware.ts 未找到”

• 检查：文件位于项目根目录或 src/ 中，而不是 app/ 内
• 检查：文件名与 Next.js 版本匹配（16 及以上使用 proxy.ts，13-15 使用 middleware.ts）

“客户端组件中无法使用 getUser”

• 检查：组件没有 'use client' 指令，或
• 检查：将身份验证逻辑移至服务端组件/API 路由

SDK 导入提示“找不到模块”

• 检查：编写导入语句前已安装 SDK
• 检查：node_modules 中存在 SDK 包目录

“withAuth 路由未被中间件覆盖”

• 检查：middleware/proxy 文件位于正确位置
• 检查：Matcher 配置包含该路由路径

添加 AuthKitProvider 后构建失败

• 检查：README 中的正确导入路径（可能是子路径导出）
• 检查：没有违反客户端/服务端边界

NEXTPUBLIC 前缀问题

• 客户端组件需要 NEXT_PUBLIC_* 前缀
• 服务端组件使用普通环境变量名称