第 3 章：项目初始化：Next.js + TypeScript + LangChain.js

第 3 章：项目初始化：Next.js + TypeScript + LangChain.js

本章目标

这一章开始搭项目。我们会用 Next.js App Router 作为全栈框架，前端负责页面和流式渲染，后端 API Route 负责调用 LangChain.js。

最终效果预览

第 3-15 章会逐步把项目完善成下面这个工作台：

为什么选 Next.js

对前端开发者来说，Next.js 的好处是：

• 同一个项目里写页面和服务端接口
• API Route 可以安全保存模型密钥
• 部署到 Vercel 很方便
• App Router 适合组织复杂应用
• TypeScript 支持完整

这不是唯一选择。你也可以用 Vue + NestJS、React + Express、Nuxt、Hono。但小册需要降低读者心智负担，选择一个主线框架更好。

创建项目

npx create-next-app@latest ai-kb-agent

建议选择：

TypeScript: Yes
ESLint: Yes
Tailwind CSS: Yes
src directory: Yes
App Router: Yes
Turbopack: 可选

进入项目：

cd ai-kb-agent

安装依赖

LangChain 官方文档要求 Node.js 20+。基础依赖：

npm install langchain @langchain/core zod

如果用 OpenAI 供应商：

npm install @langchain/openai

后续章节如果接入其他供应商，再安装对应包。

环境变量

在项目根目录创建 .env.local：

OPENAI_API_KEY=your_api_key
CHAT_MODEL=openai:gpt-5.4

不要把 .env.local 提交到 Git 仓库。

.env.local

推荐目录结构

src/
  app/
    page.tsx
    api/
      chat/
        route.ts
  components/
    chat/
      ChatPanel.tsx
      MessageList.tsx
      MessageInput.tsx
  lib/
    ai/
      model.ts
      prompts.ts
      tools.ts
    rag/
      splitter.ts
      embeddings.ts
      vector-store.ts
  types/
    chat.ts

前期可以少建文件，但小册里最好提前说明最终结构。读者知道代码会长到哪里，后面不容易迷路。

模型工厂

创建 src/lib/ai/model.ts：

import { initChatModel } from "langchain";

export async function createChatModel() {
  return initChatModel(process.env.CHAT_MODEL ?? "openai:gpt-5.4", {
    temperature: 0.2,
    timeout: 30000,
    maxRetries: 3
  });
}

这里先保留简单配置。生产环境要继续补充错误处理、模型路由和日志。

第一个 API Route

创建 src/app/api/health/route.ts：

export async function GET() {
  return Response.json({
    ok: true,
    name: "ai-kb-agent"
  });
}

启动项目：

npm run dev

访问：

http://localhost:3000/api/health

能看到 { "ok": true } 就说明基础项目没问题。

实战任务

这一章的交付物：

• 一个 Next.js + TypeScript 项目
• 安装 LangChain.js 基础依赖
• 配置 .env.local
• 创建模型工厂
• 创建健康检查接口

常见坑

第一，模型密钥不能写在前端组件里。所有模型调用都应该从服务端接口发起。

第二，Node.js 版本要满足要求。版本太旧时，依赖安装或运行时会出现奇怪问题。

第三，模型名不要散落在业务代码里。统一通过环境变量或配置读取。

本章小结

我们完成了项目骨架。下一章会真正调用模型，并设计多模型切换方式。