前言¶

幾乎每個 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 覆蓋以下能力：

依賴與環境：安裝 next-auth@beta，用 npx auth secret 生成並寫入 AUTH_SECRET（Auth.js v5 唯一必填環境變量）。
集中式配置：在項目根創建 auth.ts，導出 handlers、signIn、signOut、auth 等 Next.js 集成 API。
App Router 路由：在 app/api/auth/[...nextauth]/route.ts 掛載 GET/POST 處理器。
OAuth 提供商：內置 GitHub、Google 示例，環境變量採用 AUTH_GITHUB_ID、AUTH_GITHUB_SECRET 等 AUTH_ 前綴，可被 Auth.js 自動推斷。
登錄 UI：指導創建調用 signIn / signOut 的組件，或使用 <SignIn /> 等內置方式。
路由保護：在 Server Component 或 Middleware 中調用 auth()，未登錄時重定向到登錄頁。
可選持久化：需要數據庫存儲用戶或會話時，可接入 @auth/drizzle-adapter、@auth/prisma-adapter 等官方 Adapter。
雙路由模式說明：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 的團隊。

使用限制與注意點¶

版本與包名：Skill 針對 Auth.js v5（next-auth@beta）。若項目仍停留在 v4，配置方式不同，需參考 Migrating to v5 而非機械套用本 Skill。
環境變量命名：v5 推薦使用 AUTH_ 前綴；NEXTAUTH_SECRET、NEXTAUTH_URL 在多數場景下已可省略，生產環境若遇反向代理問題可設置 AUTH_TRUST_HOST 或 AUTH_URL。
生產部署：Skill 備註可添加 NEXTAUTH_URL；官方 v5 文檔說明多數平臺可自動推斷 Host，但 OAuth 回調 URL 必須在 Provider 控制檯正確登記（形如 https://你的域名/api/auth/callback/github）。
會話數據：Skill 建議 Session 中只存最少用戶信息，完整資料從數據庫讀取——避免 JWT 過大或泄露敏感字段。
Pages Router：Skill 僅簡要提及 getServerSession / useSession；純 Pages 項目應以 Auth.js 官方 Pages 文檔爲準，必要時人工校正 Agent 輸出。
安全：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

adding-auth：讓 AI Agent 按標準流程接入 Auth.js 認證

前言¶

這是什麼¶

核心功能與亮點¶

安裝與啓用¶

方式一：手動複製（Cursor 通用）¶

方式二：Skills CLI（多 Agent 一鍵安裝）¶

方式三：Codex 內置 `$skill-installer`¶

典型用法示例¶

觸發方式¶

Agent 將執行的集成流程¶

適用場景與注意事項¶

適合誰用¶

使用限制與注意點¶

小結¶

精选优惠券

adding-auth：讓 AI Agent 按標準流程接入 Auth.js 認證

前言¶

這是什麼¶

核心功能與亮點¶

安裝與啓用¶

方式一：手動複製（Cursor 通用）¶

方式二：Skills CLI（多 Agent 一鍵安裝）¶

方式三：Codex 內置 $skill-installer¶

典型用法示例¶

觸發方式¶

Agent 將執行的集成流程¶

適用場景與注意事項¶

適合誰用¶

使用限制與注意點¶

小結¶

精选优惠券

相關文章

方式三：Codex 內置 `$skill-installer`¶