在上一章中，我们完成了技术选型与架构设计。从本章开始，我们将正式进入工程落地阶段。

万丈高楼平地起，一个优秀的企业级项目，往往取决于最初的项目骨架是否扎实。本章的目标是搭建整个项目的核心骨架，配置好所有核心依赖，并建立一套清晰、可扩展的目录结构。

1. 为什么需要精心设计的初始化？

很多开发者习惯于使用 create-next-app 生成默认项目后直接开始写业务代码，这在 AI Agent 项目中是致命的。

AI Agent 项目的特殊性：

  • 多职责分离：我们需要区分 UI 组件、业务逻辑、AI 核心逻辑、工具调用、数据库模型等。
  • 服务端与客户端边界：Next.js App Router 对 Server Component 和 Client Component 有严格区分，AI SDK 的某些 Hook 只能在客户端使用，而数据库操作只能在服务端进行。
  • 配置复杂度：Prisma、pgvector、AI SDK、HeroUI 都需要特定的配置才能协同工作。

本章我们将建立：

  1. 标准化的 Next.js 项目骨架。
  2. 核心依赖的安装与配置。
  3. 符合 AI Agent 开发范式的目录结构。
  4. 数据库的初始化与连接。

2. 创建 Next.js 项目

首先，我们使用官方脚手架创建项目。注意，我们选择 src/ 目录结构，这是企业级项目的标准做法，能将应用代码与配置文件彻底隔离。

# 创建项目
npx create-next-app@latest ai-agent-enterprise --typescript --tailwind --app --src-dir --eslint

# 进入项目
cd ai-agent-enterprise

3. 安装核心依赖

根据第二章的技术选型，我们需要安装以下核心包：

# AI 核心
npm install ai @ai-sdk/openai

# 数据库 ORM
npm install prisma @prisma/client

# UI 组件库 (HeroUI)
npm install @heroui/react framer-motion

# Markdown 渲染 (用于 AI 回复)
npm install react-markdown remark-gfm

4. 目录结构设计

一个清晰的目录结构是项目可维护性的基石。我们在 src/ 下建立以下结构：

src/
├── app/                # Next.js App Router 路由与 API
│   ├── api/            # API 路由 (AI 对话接口等)
│   ├── page.tsx        # 首页
│   └── layout.tsx      # 根布局
├── components/         # UI 组件
│   ├── ui/             # 基础 UI 组件 (Button, Input 等)
│   └── chat/           # 聊天业务组件 (ChatWindow, MessageBubble)
├── lib/                # 核心工具与配置
│   ├── ai/             # AI SDK 配置、工具定义
│   ├── db/             # Prisma Client 单例
│   └── utils.ts        # 通用工具函数
├── types/              # 全局 TypeScript 类型定义
└── styles/             # 全局样式

为什么这样设计？

  • app/api：AI 对话接口必须放在这里，利用 Next.js Route Handlers 处理流式响应。
  • lib/ai：将 AI 相关的配置、Prompt 模板、Tool Calling 定义集中管理，避免业务逻辑与 AI 逻辑耦合。
  • lib/db：Prisma Client 在开发环境下会创建大量连接，必须封装为单例（Singleton）以防止连接池耗尽。

5. 核心配置实现

5.1 Prisma 数据库初始化

npx prisma init

这会生成 prisma/schema.prisma 和 .env 文件。

为什么需要 Prisma？
Prisma 提供了类型安全的数据库访问。当我们在 AI Agent 中定义工具时，可以直接将 Prisma 的查询结果作为 Tool 的返回值，TypeScript 会自动推导类型，极大减少运行时错误。

5.2 AI SDK 配置

在 src/lib/ai/config.ts 中：

import { createOpenAI } from '@ai-sdk/openai';

export const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL, // 支持 DeepSeek 等兼容接口
});

5.3 HeroUI 配置

HeroUI 需要包裹 HeroUIProvider。在 src/app/layout.tsx 中：

import { HeroUIProvider } from '@heroui/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh-CN">
      <body>
        <HeroUIProvider>
          {children}
        </HeroUIProvider>
      </body>
    </html>
  );
}

6. 项目架构流转图

初始化完成后，我们的项目数据流如下：
在这里插入图片描述

7. 测试验证

运行开发服务器：

npm run dev

访问 http://localhost:3000，如果看到 Next.js 默认页面且没有报错，说明项目骨架搭建成功。

验证清单：

  • 项目能正常启动
  • HeroUI 组件能正常渲染
  • Prisma 能正常连接数据库（检查控制台无报错）
  • 环境变量能正常读取

8. 常见问题与踩坑分析

问题 1：Prisma 在 Next.js 中导致连接池耗尽

原因：Next.js 的 HMR（热更新）会在每次代码修改时重新执行模块，导致 Prisma Client 被反复实例化。
解决：在 src/lib/db/index.ts 中使用全局单例模式：

import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };

export const prisma = globalForPrisma.prisma || new PrismaClient();

if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

问题 2：HeroUI 样式不生效

原因：HeroUI 依赖 Tailwind CSS 的插件配置。
解决：确保在 tailwind.config.ts 中正确配置了 @heroui/theme 插件。

本章总结

  • 我们创建了基于 App Router 的 Next.js 项目，选择了 src/ 目录结构。
  • 安装了 AI SDK、Prisma、HeroUI、react-markdown 等核心依赖。
  • 建立了符合 AI Agent 开发范式的目录结构，将 UI、AI 逻辑、数据库配置分离。
  • 完成了 Prisma 初始化与 AI SDK 基础配置。
  • 解决了 Prisma 连接池、HeroUI 样式等常见踩坑问题。

项目骨架已经搭建完毕，并且可以正常运行。

从下一章开始，我们将正式接入大模型，实现第一个流式对话功能。

Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

大模型Agent安全实践：Workspace沙箱隔离与全链路审计，规避AI自主运行核心风险21.2

avatar AI Agent技术社区

2026年百元投影仪值不值得买？告别杂牌，首选哈趣H3 Pro

硬件配置方面，哈趣H3 Pro搭载MT9系旗舰智能芯片，配合32GB大存储、Wi-Fi6与蓝牙5.3连接，运行当贝超级AI OS智能系统，整体流畅度大幅提升，支持AI语音交互、全自动对焦、自动梯形校正、智能避障，搭配一体式灵动云台，可灵活调整角度，轻松投射天花板、侧墙，躺卧观影也很方便；哈曼定制音响加持，音质饱满扎实，低音表现出色，还可一键切换蓝牙音响模式，兼具影音播放与日常听歌功能，实现投影、音

avatar AI Agent技术社区
cover

KMP 全栈进化：从 Android 跨端到 AI Agent，Koog 让 Kotlin 彻底摆脱 Python 依赖

avatar AI Agent技术社区