用 Next.js + Auth.js + Postgres 一键部署带登录的管理后台模板

方案简介

用 Next.js + Auth.js + Postgres 一键部署带登录的管理后台模板。Vercel 部署时自动创建 Postgres 并注入环境变量，配合 Auth.js 实现 GitHub OAuth 登录。

亮点与能力

根据 README 与 package.json 提炼，该模板提供以下能力：

• 基于 Next.js 15 App Router 的应用骨架，支持 layouts、组件同位（colocation）、组件级数据获取。
• 使用 Auth.js (NextAuth v5 beta) 接入 GitHub OAuth 登录鉴权。
• 使用 Vercel Postgres（底层依赖 @neondatabase/serverless）作为数据库，并通过 Drizzle ORM + drizzle-zod 直接在源码里写 schema 与校验。
• 内置 products 示例表（id / image_url / name / status / price / stock / available_at），用于演示后台数据展示。
• 使用 Tailwind CSS + Shadcn UI + Radix UI 构建可访问的对话框、下拉、标签页、提示等组件。
• 集成 Vercel Analytics 收集访问数据。
• 使用 Prettier 统一代码风格。
• 提供一键 seed 路由：/api/seed，把示例产品数据写入 Postgres。

原句证据：

This template uses the new Next.js App Router. This includes support for enhanced layouts, colocation of components, tests, and styles, component-level data fetching, and more.

前置要求

根据 README "Getting Started" 段落，运行此模板需要：

• Node.js 运行环境（以便执行 npm i -g vercel 与 pnpm 命令；具体版本未在材料中给出）。
• Vercel CLI：通过 npm i -g vercel 全局安装，用于把本地项目关联到 Vercel 并拉取环境变量。
• Vercel 账号：用于托管应用，并在部署时被提示创建 Postgres 数据库。
• GitHub OAuth App：按 .env.example 提示创建，用于 Auth.js 登录。
• pnpm：模板使用 pnpm install 与 pnpm dev 作为包管理与启动命令。

README 中给出的关键准备命令：

npm i -g vercel
vercel link
vercel env pull

实施步骤

1. 克隆并部署模板

从 Vercel 模板页面 Clone & Deploy，README 明确：

During the deployment, Vercel will prompt you to create a new Postgres database. This will add the necessary environment variables to your project.

部署过程中 Vercel 会引导创建 Postgres 数据库并把所需环境变量写入项目。

2. 在 Vercel Postgres 中建表

进入 Vercel Postgres Dashboard，按仓库中 app/api/seed.ts 同款的 schema 创建 products 表与 status 枚举：

CREATE TYPE status AS ENUM ('active', 'inactive', 'archived');

CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  image_url TEXT NOT NULL,
  name TEXT NOT NULL,
  status status NOT NULL,
  price NUMERIC(10, 2) NOT NULL,
  stock INTEGER NOT NULL,
  available_at TIMESTAMP NOT NULL

3. 启用 seed 路由写入示例数据

README 说明："uncomment app/api/seed.ts and hit http://localhost:3000/api/seed to seed the database with products." 即取消 app/api/seed.ts 的注释，然后访问 http://localhost:3000/api/seed 触发种子数据写入。

4. 配置本地环境变量

按 README："copy the .env.example file to .env and update the values. Follow the instructions in the .env.example file to set up your GitHub OAuth application." 即把 .env.example 复制为 .env 并填写 GitHub OAuth 等凭据。

5. 关联 Vercel 项目并拉取环境变量

npm i -g vercel
vercel link
vercel env pull

6. 安装依赖并启动开发服务器

pnpm install
pnpm dev

启动后可访问 http://localhost:3000：

You should now be able to access the application at http://localhost:3000.

使用与配置要点

本地开发：

pnpm install
pnpm dev

应用默认监听 http://localhost:3000，README 提示：

You should now be able to access the application at http://localhost:3000.

• 鉴权使用：按 .env.example 完成 GitHub OAuth 应用创建后，访问站点会被引导走 Auth.js 的登录流程。
• 数据库连接：使用 vercel env pull 把生产环境 Postgres 凭据同步到本地 .env。
• 写入示例数据：取消 app/api/seed.ts 注释后访问 http://localhost:3000/api/seed。
• 部署：直接 vercel 部署或使用 Vercel 模板页面的 "Clone & Deploy"。

注意事项与常见问题

• 数据源强依赖 Vercel Postgres：README 中 "Database - Postgres" 链接指向 https://vercel.com/postgres，依赖列表里同时含 @neondatabase/serverless，因此若脱离 Vercel 平台使用，需要自行替换数据库驱动与连接方式。
• 示例表 schema 不完整：README 里贴出的 SQL 末尾是被截断的（缺少最后 ); 之类的闭合），实际创建时要按仓库内完整 app/api/seed.ts 的定义补齐。
• next-auth 仍是 5.0.0-beta.25：依赖列表显示 next-auth 5.0.0-beta.25，属于 beta 版，鉴权实现可能与正式 v5 文档略有出入。
• seed 路由默认是注释掉的：必须手动取消注释 app/api/seed.ts 才会生效，README 明确提示这一点。
• 包管理器固定为 pnpm：所有安装与启动命令都使用 pnpm，混用 npm/yarn 可能与 lockfile 不一致。

优缺点

• ✓ 部署与数据库开通一键完成
• ✓ Next.js 15 App Route
• ✕ 强绑定 Vercel Postgres

出处

本方案挖掘自开源项目 vercel/nextjs-postgres-nextauth-tailwindcss-template，方案内容与实施命令均来自其 README 原文。