adding-auth：让 AI Agent 按标准流程接入 Auth.js 认证

大模型Skills Agent Skill Auth.js NextAuth OAuth Cursor 2026-08-08 81 阅读

前言

几乎每个 Web 项目都会碰到登录、注册、OAuth 第三方授权、会话管理与路由保护。Next.js 生态里，Auth.js（原 NextAuth.js）已是主流方案，但官方文档涉及依赖安装、密钥生成、Provider 配置、Route Handler、Server Component 鉴权等多个环节，新手很容易漏步骤或配错环境变量。

adding-auth 是社区 Skill 清单 awesome-cursor-skills 中的一条工作流指令，把 Auth.js v5 在 Next.js App Router 下的集成步骤封装成可复用的 SKILL.md。当你在 Cursor、Codex CLI 等 AI 编程工具里说「给项目加登录」「接入 GitHub OAuth」「保护某个页面」时，Agent 会按 Skill 里的 8 步清单执行，而不是从零摸索文档。

这是什么

adding-auth 是一份 Agent Skill 配置文件，维护在 spencerpauly/awesome-cursor-skills/resources/adding-auth，由社区策展收录，并非 Auth.js 官方出品。

它的定位很清晰：当用户提出与认证、登录、注册、OAuth、会话管理相关的需求时，引导 AI 使用 NextAuth.js（Auth.js v5） 完成集成，覆盖 OAuth 提供商配置、会话读写与路由保护。Skill 正文与 Auth.js 官方安装文档 的步骤高度一致，属于「把官方最佳实践翻译成 Agent 可执行清单」的类型。

核心功能与亮点

根据官方 SKILL.md 与 Auth.js 文档交叉核实，该 Skill 覆盖以下能力：

  1. 依赖与环境：安装 next-auth@beta，用 npx auth secret 生成并写入 AUTH_SECRET（Auth.js v5 唯一必填环境变量）。
  2. 集中式配置：在项目根创建 auth.ts，导出 handlers、signIn、signOut、auth 等 Next.js 集成 API。
  3. App Router 路由：在 app/api/auth/[...nextauth]/route.ts 挂载 GET/POST 处理器。
  4. OAuth 提供商：内置 GitHub、Google 示例，环境变量采用 AUTH_GITHUB_ID、AUTH_GITHUB_SECRET 等 AUTH_ 前缀，可被 Auth.js 自动推断。
  5. 登录 UI：指导创建调用 signIn / signOut 的组件，或使用 <SignIn /> 等内置方式。
  6. 路由保护：在 Server Component 或 Middleware 中调用 auth()，未登录时重定向到登录页。
  7. 可选持久化：需要数据库存储用户或会话时，可接入 @auth/drizzle-adapter、@auth/prisma-adapter 等官方 Adapter。
  8. 双路由模式说明：App Router 走 auth()；Pages Router 仍可用 getServerSession 与 useSession。

Skill 的价值在于：认证是 Web 项目的刚需，而 Auth.js 配置项多、版本迁移（v4 → v5）有 breaking change。把步骤固化后，Agent 不容易跳过密钥生成或漏写 Route Handler，对入门者尤其友好。

安装与启用

Skill 采用通用 SKILL.md 格式，可在多种 AI 编程工具中使用。以下方式均来自官方或社区文档，任选其一即可。

方式一：手动复制（Cursor 通用）

awesome-cursor-skills README 说明：Skill 放在 .cursor/skills/（用户级）或项目内 .cursor/skills/，Agent 会自动发现。

# 在项目根或用户目录执行
mkdir -p .cursor/skills/adding-auth
curl -o .cursor/skills/adding-auth/SKILL.md \
  https://raw.githubusercontent.com/spencerpauly/awesome-cursor-skills/main/resources/adding-auth/SKILL.md

方式二：Skills CLI（多 Agent 一键安装）

Vercel Skills CLI 支持从 GitHub 仓库安装指定 Skill 到 Cursor、Codex 等：

# 列出仓库内可用 Skill
npx skills add spencerpauly/awesome-cursor-skills --list

# 仅安装 adding-auth，并指定 Cursor
npx skills add spencerpauly/awesome-cursor-skills --skill adding-auth -a cursor

# 同时安装到 Codex CLI
npx skills add spencerpauly/awesome-cursor-skills --skill adding-auth -a codex

Codex CLI 默认 Skill 目录为 ~/.codex/skills/，Cursor 为 ~/.cursor/skills/ 或项目 .cursor/skills/（以 CLI 检测为准）。

方式三：Codex 内置 $skill-installer

在 Codex 会话中，可用内置安装器拉取 GitHub 上的 Skill 目录（适用于 OpenAI 官方技能库及自定义仓库 URL）。社区 Skill 若未收录于 OpenAI curated 列表，可尝试提供完整 GitHub 路径安装；安装后重启 Codex 以加载新 Skill。

安装完成后无需额外「开关」：Agent 会根据 SKILL.md frontmatter 中的 description 在任务匹配时自动加载完整指令。

典型用法示例

触发方式

Skill 声明在以下场景应被调用——你只需用自然语言描述需求：

  • 「给这个 Next.js 项目加上 GitHub 登录」
  • 「接入 Google OAuth，并保护 /dashboard 页面」
  • 「实现登出按钮和会话管理」

在 Cursor 中也可在对话里 @adding-auth 或 /skills 显式引用（具体入口以当前 Cursor 版本为准）。

Agent 将执行的集成流程

以下步骤摘自 Skill 原文，与 Auth.js 安装指南 一致，便于你对照 Agent 产出是否符合预期。

1. 安装依赖

npm install next-auth@beta

2. 生成密钥

npx auth secret

命令会在 .env.local 写入 AUTH_SECRET。

3. 创建 auth.ts

import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub, Google],
});

4. 添加 Route Handler

在 app/api/auth/[...nextauth]/route.ts：

import { handlers } from "@/auth";
export const { GET, POST } = handlers;

5. 配置环境变量

AUTH_SECRET=...
AUTH_GITHUB_ID=...
AUTH_GITHUB_SECRET=...
AUTH_GOOGLE_ID=...
AUTH_GOOGLE_SECRET=...

6. 添加登录/登出 UI

创建调用 signIn、signOut 的 Server Action 或客户端组件。

7. 保护路由

import { auth } from "@/auth";
import { redirect } from "next/navigation";

export default async function ProtectedPage() {
  const session = await auth();
  if (!session) redirect("/api/auth/signin");
  return <div>Welcome {session.user?.name}</div>;
}

8.（可选）数据库 Adapter

需要持久化用户或会话时，安装对应 Adapter 并在 NextAuth({ ... }) 中配置。

适用场景与注意事项

适合谁用

  • 使用 Next.js App Router（或逐步迁移中的混合项目）的开发者，希望快速接入 OAuth 登录。
  • 已在用 Cursor / Codex 等 Agent 写代码，希望把「加认证」变成可重复的标准作业，减少漏配环境变量。
  • 需要 GitHub、Google 等常见 OAuth，或在此基础上扩展 Credentials、Email 等 Provider 的团队。

使用限制与注意点

  1. 版本与包名：Skill 针对 Auth.js v5（next-auth@beta）。若项目仍停留在 v4，配置方式不同，需参考 Migrating to v5 而非机械套用本 Skill。
  2. 环境变量命名：v5 推荐使用 AUTH_ 前缀；NEXTAUTH_SECRET、NEXTAUTH_URL 在多数场景下已可省略，生产环境若遇反向代理问题可设置 AUTH_TRUST_HOST 或 AUTH_URL。
  3. 生产部署：Skill 备注可添加 NEXTAUTH_URL；官方 v5 文档说明多数平台可自动推断 Host，但 OAuth 回调 URL 必须在 Provider 控制台正确登记（形如 https://你的域名/api/auth/callback/github）。
  4. 会话数据：Skill 建议 Session 中只存最少用户信息，完整资料从数据库读取——避免 JWT 过大或泄露敏感字段。
  5. Pages Router：Skill 仅简要提及 getServerSession / useSession；纯 Pages 项目应以 Auth.js 官方 Pages 文档为准，必要时人工校正 Agent 输出。
  6. 安全：OAuth Client Secret、AUTH_SECRET 只放在环境变量中，不要硬编码进 auth.ts 或提交到 Git。

小结

adding-auth 把 Auth.js v5 在 Next.js 中的认证集成拆成 8 步可执行清单，适合作为 AI 编程助手处理「加登录、OAuth、会话、路由保护」时的标准 playbook。它不改变 Auth.js 本身的能力边界，而是降低 Agent 集成时的遗漏率，对认证刚需的 Web 项目尤其实用。

官方 Skill 地址：https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/adding-auth

Auth.js 官方文档：https://authjs.dev

相关文章

Cursor 3 多 Agent 架构：Planner/Worker 分工最高降本 15 倍 2026-07-29 Cursor 多 Agent 蜂群用 1339 美元重建 SQLite：Planner/Worker 分层才是 Agent 经济学 2026-07-30 600 亿美元收购 Cursor：SpaceX/xAI 要重塑 AI 编程工具格局？ 2026-07-31 Cursor 3 多 Agent 架构：Planner/Worker 分层如何将编码成本降低 15 倍 2026-08-01 GitHub 爆火 Ponytail：让 AI Agent 像「最懒的高级工程师」一样写代码 2026-08-02
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜