Prisma 7.2.0 + MySQL + Next.js 16 完整配置指南
项目概述
本项目是一个基于Next.js 16 + Prisma ORM的AI Agent智能体系统,采用Manus上下文工程理念,支持30-50步长流程任务。
核心技术栈
- Next.js 16 (Turbopack)
- Prisma ORM 7.2.0 (最新版,配置方式大幅变更)
- MySQL数据库 (现有生产数据库)
- NextAuth.js 4.24 (用户认证)
- OpenAI API (AI模型调用)
核心挑战与解决方案
Prisma 7.2.0 重大变更
- 不再支持
schema.prisma中直接写url = env("DATABASE_URL") - 必须使用
adapter或accelerateUrl配置PrismaClient - 需要创建
prisma.config.ts用于CLI命令 @db.Enum属性不再支持
现有MySQL数据库集成
- 数据库已有15+张表和完整数据
- 需要无损迁移(不能删除现有数据)
- 需要扩展现有表(如
users)以支持新功能 - 需要新增
agent_sessions表存储AI会话
Next.js 16 新特性适配
- Server Components默认启用
SessionProvider无法在Server Component中使用- Turbopack构建系统需要特殊配置
- 模块导入方式变更(ESM vs CommonJS)
完整配置流程
步骤1:安装依赖
pnpm add @prisma/client@7.2.0 prisma@7.2.0
pnpm add @prisma/adapter-mariadb mariadb
pnpm add @next-auth/prisma-adapter next-auth
pnpm add bcryptjs openai axios fs-extra pdf-parse node-html-parser
pnpm add -D @types/bcryptjs @types/node @types/react
步骤2:配置环境变量
创建 .env文件:
# 数据库连接(必需)
DATABASE_URL="mysql://app_user:password@host:3306/spacehelper"
# NextAuth认证(必需)
NEXTAUTH_SECRET="生成的32位随机密钥"
NEXTAUTH_URL="http://localhost:3000"
# OpenAI配置(必需)
OPENAI_API_KEY="sk-your-key"
OPENAI_BASE_URL="https://api.openai.com/v1"
MODEL_NAME="gpt-4o-mini"
# Agent工作区(可选)
WORKSPACE_BASE="C:/temp/agent_workspaces"
MAX_STEPS=50
步骤3:创建Prisma配置文件
3.1 prisma/schema.prisma
generator client {
provider = "prisma-client-js"
}
datasource db {
provider = "mysql"
// ❌ 不要写 url = env("DATABASE_URL")
}
model User {
id Int @id @default(autoincrement())
uuid String? @unique @db.VarChar(36)
email String @unique @db.VarChar(100)
name String? @db.VarChar(50)
password String? @db.VarChar(255)
status UserStatus @default(ACTIVE)
role UserRole @default(USER)
createdAt DateTime @default(now()) @map("created_at")
updatedAt DateTime @updatedAt @map("updated_at")
accounts Account[]
sessions Session[]
agentSessions AgentSession[]
@@map("users")
@@index([email])
}
model AgentSession {
id String @id @default(cuid())
userId Int? @map("user_id")
sessionKey String @unique @map("session_key")
context String @db.Text
workspace String @db.VarChar(500)
status String @db.VarChar(50)
totalSteps Int @default(0) @map("total_steps")
fileList Json? @map("file_list")
createdAt DateTime @default(now()) @map("created_at")
updatedAt DateTime @updatedAt @map("updated_at")
user User? @relation(fields: [userId], references: [id], onDelete: Cascade)
@@map("agent_sessions")
@@index([userId])
@@index([sessionKey])
}
enum UserStatus {
ACTIVE
INACTIVE
BANNED
}
enum UserRole {
USER
ADMIN
SUPERADMIN
}
3.2 prisma.config.ts
import { defineConfig } from '@prisma/client/generator-config';
export default defineConfig({
datasource: {
db: {
url: process.env.DATABASE_URL!,
},
},
});
步骤4:配置Prisma Client适配器
创建 src/lib/db.ts:
import { PrismaClient } from '@prisma/client';
import { PrismaMariaDb } from '@prisma/adapter-mariadb';
import mariadb from 'mariadb';
// 解析DATABASE_URL
const url = new URL(process.env.DATABASE_URL || 'mysql://localhost:3306/test');
const pool = mariadb.createPool({
host: url.hostname,
port: parseInt(url.port) || 3306,
user: url.username,
password: url.password,
database: url.pathname.slice(1),
connectionLimit: 20, // 连接池大小
acquireTimeout: 60000, // 获取连接超时60秒
connectTimeout: 10000, // 建立连接超时10秒
idleTimeout: 300000, // 空闲连接超时5分钟
minimumIdle: 2, // 最小空闲连接数
});
// 全局单例
const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
export const prisma = globalForPrisma.prisma || new PrismaClient({
adapter: new PrismaMariaDb(pool) as any, // 类型转换
log: process.env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
});
if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
export default prisma;
步骤5:同步数据库架构
5.1 从现有数据库拉取架构(推荐)
# 拉取现有表结构到schema.prisma
npx prisma db pull
# 生成Prisma Client
npx prisma generate
# 验证是否成功
npx prisma studio
5.2 推送本地架构到数据库(危险!)
# ⚠️ 会修改数据库结构,可能导致数据丢失
npx prisma db push
# 如果确认要执行
npx prisma db push --accept-data-loss
步骤6:配置NextAuth.js
6.1 创建API路由
src/app/api/auth/[...nextauth]/route.ts:
import { authOptions } from "@/lib/auth";
import NextAuth from "next-auth";
const handler = NextAuth(authOptions);
export { handler as GET, handler as POST };
6.2 配置认证选项
src/lib/auth.ts:
import { PrismaAdapter } from "@next-auth/prisma-adapter";
import { NextAuthOptions } from "next-auth";
import CredentialsProvider from "next-auth/providers/credentials";
import { prisma } from "./db";
import { AUTH_CONFIG } from "@/config";
import bcrypt from "bcryptjs";
export const authOptions: NextAuthOptions = {
adapter: PrismaAdapter(prisma),
secret: AUTH_CONFIG.secret,
session: { strategy: "jwt", maxAge: 30 * 24 * 60 * 60 },
pages: { signIn: "/", signOut: "/" },
providers: [
CredentialsProvider({
name: "Credentials",
credentials: {
email: { label: "邮箱", type: "email" },
password: { label: "密码", type: "password" },
},
async authorize(credentials) {
if (!credentials?.email || !credentials?.password) return null;
const user = await prisma.user.findUnique({ where: { email: credentials.email } });
if (!user || !user.password) return null;
const isPwdValid = await bcrypt.compare(credentials.password, user.password);
if (!isPwdValid) return null;
return {
id: String(user.id), // NextAuth要求id为string
email: user.email,
name: user.name,
image: user.image,
};
},
}),
],
callbacks: {
async jwt({ token, user }) {
if (user) token.userId = user.id;
return token;
},
async session({ session, token }) {
if (token.userId) session.user.id = token.userId as string;
return session;
},
},
};
6.3 创建类型声明
src/types/next-auth.d.ts:
import "next-auth";
import "next-auth/jwt";
declare module "next-auth" {
interface Session {
user: {
id: string;
name?: string | null;
email?: string | null;
image?: string | null;
};
}
interface User {
id: string;
}
}
declare module "next-auth/jwt" {
interface JWT {
userId: string;
}
}
6.4 创建Client Provider
src/components/Providers.tsx:
"use client";
import { SessionProvider } from "next-auth/react";
export default function Providers({ children }: { children: React.ReactNode }) {
return <SessionProvider>{children}</SessionProvider>;
}
6.5 更新根布局
src/app/layout.tsx:
import Providers from "@/components/Providers";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="zh-CN">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
步骤7:实现Agent API路由
src/app/api/agent/route.ts:
import { NextRequest, NextResponse } from 'next/server';
import { getServerSession } from 'next-auth';
import { prisma } from '@/lib/db';
import { authOptions } from '@/lib/auth';
export async function POST(req: NextRequest) {
try {
const session = await getServerSession(authOptions);
const userId = session?.user.id ? Number(session.user.id) : null; // 支持游客
const { userInput, sessionKey } = await req.json();
// 创建AI会话
const agentSession = await prisma.agentSession.create({
data: {
sessionKey,
userId,
context: JSON.stringify([{ role: "user", content: userInput }]),
workspace: `C:/temp/workspaces/${sessionKey}`,
status: "running",
fileList: [],
},
});
return NextResponse.json({ success: true, session: agentSession });
} catch (error: any) {
console.error('Agent API Error:', error);
return NextResponse.json(
{
success: false,
error: error.message,
details: process.env.NODE_ENV === 'development' ? error.stack : undefined,
},
{ status: 500 }
);
}
}
步骤8:配置Next.js
next.config.ts:
import type { NextConfig } from 'next';
const nextConfig: NextConfig = {
output: 'standalone',
reactStrictMode: true,
env: {
NEXT_PUBLIC_APP_NAME: 'AI Agent (Manus+Next.js16)',
},
// ❌ 不要写不支持的experimental配置
};
export default nextConfig;
常见错误及解决方案
错误1:连接池超时
现象:
Error [DriverAdapterError]: pool timeout: failed to retrieve a connection from pool after 10011ms
原因:
- 连接池配置过小
- 网络延迟
- 热重载导致连接泄漏
解决方案:
// 在src/lib/db.ts中增加连接池参数
const pool = mariadb.createPool({
connectionLimit: 20, // 增加连接数
acquireTimeout: 60000, // 增加超时时间
idleTimeout: 300000, // 空闲连接超时
minimumIdle: 2, // 最小空闲连接
});
错误2:datasource property 'url' is no longer supported
解决方案:
- 从
schema.prisma中删除url = env("DATABASE_URL") - 创建
prisma.config.ts配置CLI URL - 在
src/lib/db.ts中使用adapter配置运行时连接
错误3:React Context is unavailable in Server Components
解决方案:
创建 src/components/Providers.tsx客户端组件包裹 SessionProvider
错误4:Module '"@prisma/client"' has no exported member 'PrismaClient'
解决方案:
# 重新生成Prisma Client
npx prisma generate
错误5:Failed to fetch 'Inter' from Google Fonts
解决方案:
// 临时注释掉Google Fonts导入
// import { Inter } from "next/font/google";
验证和测试
1. 数据库连接测试
# 拉取架构验证连接
npx prisma db pull
# 打开Prisma Studio查看数据
npx prisma studio
2. 启动开发服务器
pnpm dev
# 验证输出:
# ✓ Next.js 16.1.0 (Turbopack)
# - Local: http://localhost:3000
# ✓ Ready in 1356ms
3. 测试API路由
# 测试NextAuth Session
curl http://localhost:3000/api/auth/session
# 测试Agent API
curl -X POST http://localhost:3000/api/agent \
-H "Content-Type: application/json" \
-d '{"userInput": "测试任务", "sessionKey": "test123"}'
4. 构建生产版本
pnpm build
# 验证输出:
# ✓ Compiled successfully
# ✓ Collecting page data
# ✓ Generating static pages
项目结构总览
ai-agent-manus/
├── prisma/
│ ├── schema.prisma # 数据库架构定义(不含url)
│ └── prisma.config.ts # CLI命令配置(含url)
├── src/
│ ├── app/
│ │ ├── api/
│ │ │ ├── auth/[...nextauth]/route.ts # NextAuth API
│ │ │ ├── agent/route.ts # Agent执行API
│ │ │ └── agent/history/route.ts # 历史记录API
│ │ ├── layout.tsx # 根布局(使用Providers)
│ │ └── page.tsx # 首页
│ ├── components/
│ │ └── Providers.tsx # 客户端Provider封装
│ ├── lib/
│ │ ├── db.ts # Prisma Client + Adapter
│ │ ├── auth.ts # NextAuth配置
│ │ └── agent/
│ │ ├── tools.ts # Agent工具定义
│ │ └── models.ts # AI模型调用
│ ├── types/
│ │ └── next-auth.d.ts # NextAuth类型扩展
│ └── config.ts # 全局配置
├── .env # 环境变量(不提交到Git)
├── .env.example # 环境变量模板
├── next.config.ts # Next.js配置
├── package.json # 依赖管理
├── tsconfig.json # TypeScript配置
└── TROUBLESHOOTING.md # 故障排查文档
核心技术要点
1. Prisma 7.2.0 三层配置体系
- CLI层:
prisma.config.ts提供datasource.db.url - 运行时层:
src/lib/db.ts使用adapter配置连接池 - 架构层:
prisma/schema.prisma仅定义数据模型
2. 数据库连接优化
- 使用MariaDB驱动(性能优于mysql2)
- 连接池大小20(根据并发调整)
- 超时时间60秒(适应远程数据库)
- 最小空闲连接2(减少冷启动延迟)
3. Next.js 16 最佳实践
- Server Components默认启用(性能优势)
- Client Components仅用于交互逻辑(如SessionProvider)
- Turbopack构建速度提升5-10倍
- 模块导入使用ESM优先
4. AI Agent架构设计
- 上下文外部化:使用
context字段存储完整对话历史 - 工作区隔离:每个会话独立文件夹(
workspace字段) - 步数限制:最大50步防止无限循环(
totalSteps字段) - 游客支持:
userId可为null(支持未登录用户)
生产部署检查清单
- 确保
.env文件不提交到Git(检查.gitignore) - 使用强随机密钥(
NEXTAUTH_SECRET至少32字符) - 数据库连接使用生产凭据
- 设置
NODE_ENV=production - 执行
pnpm build验证构建成功 - 配置反向代理(Nginx)
- 启用HTTPS(Let's Encrypt)
- 配置数据库备份策略
- 监控日志和错误(Sentry/LogRocket)
- 负载测试(k6/JMeter)
总结
本项目成功整合了Prisma 7.2.0的全新配置方式、Next.js 16的Server Components架构以及现有MySQL数据库,实现了一个高性能、可扩展的AI Agent系统。关键突破包括:
- 无损数据迁移:通过
db pull从现有数据库生成架构,保证数据安全 - 连接池优化:合理配置MariaDB连接池参数,解决远程数据库超时问题
- 类型安全:扩展NextAuth类型,实现端到端类型检查
- 错误处理:完整的try-catch机制和详细日志,便于生产环境排查问题
整个配置流程已沉淀为可复用的技术方案,适用于类似的Prisma + MySQL + Next.js项目。