ICY 智能对话助手：基于 Next.js 的 AI 大模型项目从 0 到 1 全栈开发指南

本文完整梳理了 ICY 智能对话助手的从零开发全流程，基于 Next.js + DeepSeek AI + Clerk + Drizzle ORM 核心技术栈，覆盖项目初始化与基建、全栈底层架构配置、后端 API 路由开发、前端核心 UI 与交互开发、体验优化与部署上线全阶段，手把手教你复刻具备用户认证、多会话管理、流式对话、思维链展示与数据持久化能力的 AI 聊天应用。

第一阶段：项目初始化与基建

1. 创建 Next.js 项目

采用最新版 Next.js (App Router) 与 React 19 初始化项目底座。核心配置项推荐选择 JavaScript、开启 ESLint、集成 Tailwind CSS，并启用 src/ 目录。

npx create-next-app@latest icy-next

2. 安装核心依赖包

根据项目需求，分模块安装相关技术栈：

# UI 与样式引擎
npm install antd @ant-design/icons lucide-react clsx class-variance-authority tailwindcss @tailwindcss/postcss sass tw-animate-css

# Radix 无头组件 (用于高定制化基础交互)
npm install @radix-ui/react-separator @radix-ui/react-slot @radix-ui/react-tooltip

# 数据库与 ORM 工具
npm install drizzle-orm postgres
npm install -D drizzle-kit

# 身份认证系统
npm install @clerk/nextjs

# AI SDK 与核心模型支持
npm install ai @ai-sdk/react @ai-sdk/deepseek

# 状态管理、数据请求与其他工具
npm install @tanstack/react-query dayjs zod dotenv streamdown

3. 环境变量配置

在项目根目录创建 .env.development 和 .env.production，并注入以下核心鉴权与连接凭证：

• Clerk Auth: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY
• Database (PostgreSQL): DATABASE_URL
• AI/LLM: DEEPSEEK_API_KEY 及大模型的基础 URL 代理配置。

第二阶段：全栈底层架构与配置

1. 数据库架构设计 (Drizzle ORM)

• 配置连接: 修改 drizzle.config.js，绑定 Postgres 环境变量。
• 定义表结构: 在 src/db/schema.js 中构建 chatsTable（会话主记录）与 messagesTable（消息明细记录）。
• 初始化实例: 在 src/db/index.js 中接入 postgres 驱动并导出 Drizzle 客户端实例。
• 同步结构: 执行 npx drizzle-kit push 将本地 Schema 推送至远端数据库。

// 核心代码：src/db/schema.js (片段)
import { pgTable, text, uuid, timestamp } from "drizzle-orm/pg-core";

export const chatsTable = pgTable("chats", {
    id: uuid("id").defaultRandom().primaryKey(),
    title: text("title").notNull(),
    userId: text("user_id").notNull(),
    model: text("model").notNull(),
    createdAt: timestamp("created_at").defaultNow().notNull(),
    updatedAt: timestamp("updated_at").defaultNow().notNull().$onUpdate(() => new Date()),
});

2. 全局 Provider 与样式封装

• Tailwind CSS V4: 于 src/app/globals.css 引入核心指令并定义全局 CSS 变量。
• Ant Design 定制: 封装 AntdConfig.jsx 与 AntdAppProvider.jsx，覆盖默认 Token（如圆角、主色调）以统一 UI 视觉规范。
• React Query 注入: 使用 QueryClientProvider 包裹应用根节点，优化客户端数据的拉取、缓存与状态失效管理。

3. 用户身份集成 (Clerk)

• 全局拦截: 在 src/app/layout.js 最外层包裹 <ClerkProvider> 提供鉴权上下文。
• 路由保护: 编写 middleware.js 阻断未授权访问，确保仅已登录用户可进入 /(main) 内部聊天路由。
• 页面对接: 创建 src/app/sign-in/[[...sign-in]]/page.jsx 实现标准的登录与注册流。

第三阶段：后端 API 路由开发

在 src/app/api 目录下构建 RESTful 与流式接口，实现前后端数据闭环：

流式接口核心代码 (src/app/api/chat/route.js)：

import { streamText, convertToModelMessages } from 'ai';
import { auth } from '@clerk/nextjs/server'
import { createDeepSeek } from "@ai-sdk/deepseek";

const apiKey = process.env.DEEPSEEK_API_KEY;

export async function POST(req) {
    const { messages, chat_id, isThinkingMode } = await req.json();
    const { userId } = await auth(); // 拦截鉴权
    
    const modelId = isThinkingMode ? 'deepseek-reasoner' : 'deepseek-chat';
    const deepseek = createDeepSeek({ apiKey });

    const result = streamText({
        model: deepseek(modelId),
        messages: await convertToModelMessages(messages),
    });

    return result.toUIMessageStreamResponse({
        sendReasoning: isThinkingMode,
        onFinish: async ({ messages: generatedMessages }) => {
            // 在此执行数据持久化，将对话写入 Postgres
        }
    });
}

第四阶段：前端核心 UI 与交互开发

前端工作量主要集中在 src/components 和 src/app/(main) 目录下，注重状态流转与用户体验。

1. 主框架布局 src/app/(main)/layout.jsx

• 左侧边栏 (Sidebar)：动态渲染历史对话列表，集成“新建对话”与“重命名/删除”模态框。
• 用户信息区：底部固定展示 Clerk <UserButton /> 及全局 <SettingsModal />。

2. 聊天主视口 src/app/(main)/chat/[chat_id]/page.jsx

• 数据绑定：利用 AI SDK 的 useChat() Hook 接管消息的双向绑定与传输封装。
• 页面结构：顶部为包含模型切换的导航栏，中间为支持自动滚动的对话瀑布流，底部悬浮输入面板。

3. 核心业务组件

• <MessageBubble />：聊天气泡组件。利用 streamdown 解析 Markdown，为 AI 回复提供富文本与代码高亮支持。
• <ReasoningItem />：专为 DeepSeek R1 设计的深度思考渲染组件，支持折叠/展开 AI 的“思维链 (CoT)”。
• <ChatInput />：底部多行文本输入框，提供发送请求与中断生成（Stop）的控制台。
• useAutoScroll Hook：监听流式数据更新，平滑滚动至页面底部，保障阅读连贯性。

第五阶段：体验优化与部署上线

• 渲染增强: 深度定制 Markdown 组件，确保复杂代码块和数据表格的美观输出。
• 状态隔离: 切换 chat_id 路由时，快速重置 useChat 状态，并配合 React Query 防抖，避免多开会话时数据串线。
• 动效打磨: 引入 tw-animate-css 与 Radix UI 的动画原语，优化侧边栏切出、气泡弹出的自然过渡。
• 容器化部署: 编写 Dockerfile 对 Next.js 项目进行多阶段构建，搭配 docker-compose.yml 即可一键拉起 Web 服务与 Postgres 实例。

项目总结

经过全流程的开发与打磨，ICY 智能对话助手已从零基础完成全栈构建，最终落地为一款功能完整的 AI 聊天应用。该应用深度整合了用户认证体系、多会话智能管理、流式对话交互、AI 思维链可视化展示及全链路数据持久化能力，全方位覆盖智能对话场景的核心需求。 如需体验完整功能，可访问在线演示地址：chat.yangyingfu.com