📜 目录（点击瞬移）

1. 🌌 MCP 为何物？—— 从“对话”到“上下文”
2. 🧠 底层原理：一条 SSE 流如何串起三大洲
3. 🏗️ 对 Web 行业的五连击
4. 🪄 实战：30 行 JS 搭一个“会自己写代码”的 Next.js 页面
5. 🔥 踩坑 & 彩蛋：当 MCP 遇到 CORS、Nginx 与老板的 KPI
6. 🚀 尾声：下一站，“模型即后端”？

---

1. 🌌 MCP 为何物？

官方一句话：
MCP（Model Context Protocol）＝ HTTP + SSE + JSON-RPC，让大模型“长”在你的 Web 里。

白话翻译：

曾经	现在（MCP 加持）
用户 → 前端 → 后端 → OpenAI → 后端 → 前端	用户 → 前端 ↔ 大模型（长连接）
上下文靠开发者手动拼	上下文自动累积，像 Git 一样可回滚
Token 计费 = 黑盒	Token 计费 = 实时仪表盘

🖼️ 配图：左边是传统“HTTP 回旋镖”，右边是 MCP “双向高速公路”。

---

2. 🧠 底层原理：一条 SSE 流如何串起三大洲

2.1 协议三明治

┌------------┐
│   JSON-RPC │  业务语义（方法/参数）
├------------┤
│    SSE     │  服务器推送事件（text/event-stream）
├------------┤
│    HTTP/2  │  复用连接、Header 压缩
└------------┘

2.2 生命周期（伪代码版）

// 1. 建立 SSE 流
const eventSource = new EventSource('/mcp');

// 2. 发送 JSON-RPC 请求
eventSource.onopen = () => {
  eventSource.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'initialize',
    params: { capabilities: {} }
  }));
};

// 3. 接收增量上下文
eventSource.onmessage = (e) => {
  const delta = JSON.parse(e.data);
  appendToUI(delta.content);
};

2.3 底层八卦

• 每条 SSE 事件最大 8 KB，再大就拆包（浏览器：我谢谢你）。
• 上下文窗口用 滑动数组 实现，超出长度就 Array.shift()，像贪吃蛇掉尾巴。
• Token 计数在服务端 逐字累加，前端实时看到账单跳动，心跳也跟着跳。

---

3. 🏗️ 对 Web 行业的五连击

领域	旧玩法	MCP 新姿势
前端框架	useEffect 调 API	useMcp() Hook，上下文即状态
低代码	拖拽生成死页面	拖拽后让模型实时补全逻辑
搜索	关键字 → 10 条链接	关键字 → 模型总结 + 链接
IDE 插件	补全一行代码	直接补全整个 feature 分支
运维	看日志	让模型读日志并自愈（🐍：危险但刺激）

🎭 配图：一张漫画，React 图标和 GPT 图标手牵手，脚下踩着 Express 说：“兄弟，你歇会儿。”

---

4. 🪄 实战：30 行 JS 搭一个“会自己写代码”的 Next.js 页面

4.1 目录

app/
 ├─ api/
 │  └─ mcp/
 │     └─ route.ts     ← SSE 端点
 └─ page.tsx           ← 前端魔法阵

4.2 服务端：/api/mcp/route.ts

import { NextRequest } from 'next/server';
import { Readable } from 'stream';

export async function GET(req: NextRequest) {
  const encoder = new TextEncoder();
  const stream = new ReadableStream({
    start(controller) {
      const send = (data: string) =>
        controller.enqueue(encoder.encode(`data: ${data}\n\n`));

      // 假装这里连的是真 MCP
      send(JSON.stringify({
        jsonrpc: '2.0',
        id: 1,
        result: { greeting: 'Hello MCP, from Next.js Edge Runtime!' }
      }));

      // 每 2 秒推一次代码补丁
      const timer = setInterval(() => {
        send(JSON.stringify({
          jsonrpc: '2.0',
          method: 'textDocument/patch',
          params: { code: 'console.log("✨ auto-generated line")' }
        }));
      }, 2000);

      req.signal.addEventListener('abort', () => clearInterval(timer));
    },
  });

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      Connection: 'keep-alive',
    },
  });
}

4.3 前端：app/page.tsx

'use client';
import { useEffect, useState } from 'react';

export default function Home() {
  const [lines, setLines] = useState<string[]>([]);

  useEffect(() => {
    const es = new EventSource('/api/mcp');
    es.onmessage = (ev) => {
      const { params } = JSON.parse(ev.data);
      if (params?.code) setLines(l => [...l, params.code]);
    };
    return () => es.close();
  }, []);

  return (
    <main className="p-8 font-mono">
      <h1 className="text-2xl mb-4">🪄 MCP 正在替我写代码：</h1>
      <pre className="bg-gray-900 text-green-400 p-4 rounded">
        {lines.join('\n')}
      </pre>
    </main>
  );
}

🖼️ 动态图：页面每 2 秒自动追加一行 console.log，背景是黑客帝国雨。

---

5. 🔥 踩坑 & 彩蛋

坑	原因	解药
浏览器 6 条 SSE 并发限制	HTTP/1.1 规范	升级到 HTTP/2，或把多个流复用在同一条 SSE
Nginx 缓存 60 秒断流	proxy_buffering=on	关掉： proxy_buffering off;
Token 爆炸	上下文无限增长	前端定期 session.clear()，像清理浏览器缓存
老板 KPI	想让模型 100% 准确	告诉他：模型是概率引擎，不是真理机

彩蛋：
在 DevTools 的 Console 输入

fetch('/api/mcp', { method: 'POST', body: '{"method":"ping"}' })

会看到服务端回你一个 🏓 pong，附带随机一句程序员笑话。

---

6. 🚀 尾声：下一站，“模型即后端”？

“如果 MCP 继续进化，我们可能会看到：
前端直接 import model from 'gpt://v1'；
后端变成一行 export default model；
而产品经理的 PRD 直接喂给模型，
它吐出前端 + 后端 + 测试 + 上线脚本。”

到那时，Web 行业的岗位 JD 也许只剩下一句：
“会呼吸，能写 prompt。”

---

🧙‍♂️ 彩蛋口令

在评论区打出

npx create-mcp-app@latest

即可召唤官方脚手架，一键进入“模型上下文”新世界！

开场白：为什么你的 AI 像便秘？ 想象一下你在咖啡馆里，隔壁桌的程序员小哥对着屏幕怒吼：“快出来啊！” 你以为他在催稿，结果他只是调 OpenAI 的接口——等待 8 秒一次性返回 800 个 to

在这个 AI 大模型如雨后春笋般涌现的时代，让前端应用与本地大模型来一场 “亲密接触”，就像给你的 React 应用装上一个 “本地智囊团”。今天，我们就来实现一个看似高深实则简单的需求：用 React 对接本地 Ollama 服务。这就好比教两个素未谋面的朋友打招呼，Ollama 是守在本地的 “AI 达人”，React 则是活泼的 “前端信使”，我们要做的就是搭建它们之间的沟通桥梁。

底层原理：通信的奥秘

在开始编码前，我们得先搞明白这两个 “朋友” 是如何交流的。Ollama 作为本地运行的大模型服务，会在你的电脑上开启一个 “通信窗口”—— 也就是 HTTP 服务器，默认情况下这个窗口的地址是 http://localhost:11434。而 React 应用要做的，就是通过 HTTP 协议向这个窗口发送 “消息”（请求），并等待 “回复”（响应）。

这就像你去餐厅吃饭，Ollama 是后厨的厨师，React 是前厅的服务员，http://localhost:11434 就是厨房的传菜口。服务员把顾客的订单（请求）通过传菜口递给厨师，厨师做好菜后再通过传菜口把菜（响应）送回给服务员。

准备工作：工具就位

在正式开始前，我们需要准备好 “食材” 和 “厨具”：

1. 安装 Ollama：去 Ollama 官网下载并安装，这一步就像把厨师请到厨房里。安装完成后，打开命令行，输入 ollama run llama3 来启动一个基础模型，这里我们用 llama3 作为示例，你也可以换成其他喜欢的模型。

2. 创建 React 应用：如果你还没有 React 项目，可以用 Create React App 快速创建一个，命令是 npx create-react-app ollama-demo，这就像搭建好前厅的场地。

代码实现：搭建沟通桥梁

一切准备就绪，现在我们来编写核心代码，实现 React 与 Ollama 的通信。

首先，我们需要一个发送请求的函数。在 React 组件中，我们可以用 fetch API 来发送 HTTP 请求到 Ollama 的 API 端点。Ollama 的聊天接口是 http://localhost:11434/api/chat，我们需要向这个接口发送包含模型名称和消息内容的 JSON 数据。

import { useState } from 'react';
function OllamaChat() {
  const [message, setMessage] = useState('');
  const [response, setResponse] = useState('');
  const sendMessage = async () => {
    try {
      // 构建请求体，指定模型和消息
      const requestBody = {
        model: 'llama3',
        messages: [{ role: 'user', content: message }],
        stream: false // 不使用流式响应，等待完整回复
      };
      // 发送 POST 请求到 Ollama 的聊天接口
      const response = await fetch('http://localhost:11434/api/chat', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(requestBody),
      });
      // 解析响应数据
      const data = await response.json();
      
      // 提取并显示 AI 的回复
      if (data.message && data.message.content) {
        setResponse(data.message.content);
      }
    } catch (error) {
      console.error('与 Ollama 通信出错：', error);
      setResponse('抱歉，无法连接到 AI 服务，请检查 Ollama 是否正在运行。');
    }
  };
  return (
    <div style={{ maxWidth: '600px', margin: '0 auto', padding: '20px' }}>
      <h2>React × Ollama 聊天 Demo</h2>
      <div style={{ marginBottom: '20px' }}>
        <input
          type="text"
          value={message}
          onChange={(e) => setMessage(e.target.value)}
          placeholder="输入你的问题..."
          style={{ width: '70%', padding: '8px', marginRight: '10px' }}
        />
        <button onClick={sendMessage} style={{ padding: '8px 16px' }}>
          发送
        </button>
      </div>
      <div style={{ border: '1px solid #ccc', padding: '10px', borderRadius: '4px' }}>
        <h3>AI 回复：</h3>
        <p>{response}</p>
      </div>
    </div>
  );
}
export default OllamaChat;

代码解析：庖丁解牛

让我们来仔细看看这段代码的工作原理，就像拆解一台精密的机器。

1. 状态管理：我们用 useState 钩子创建了两个状态变量，message 用来存储用户输入的消息，response 用来存储 AI 的回复。这就像两个储物盒，分别存放要发送的消息和收到的回复。

2. 发送消息函数：sendMessage 是核心函数，它通过 fetch 发送请求到 Ollama。请求体中指定了要使用的模型（llama3）和用户的消息。这里的 stream: false 表示我们希望一次性收到完整的回复，而不是逐字接收。

3. 处理响应：当 Ollama 处理完请求后，会返回一个 JSON 格式的响应。我们从中提取出 AI 的回复内容，并更新 response 状态，这样页面上就会显示出 AI 的回答了。

4. 错误处理：如果通信过程中出现错误（比如 Ollama 没有运行），我们会捕获错误并显示友好的提示信息。

运行测试：见证奇迹的时刻

现在，让我们来测试一下这个 Demo 是否能正常工作。

1. 确保 Ollama 正在运行：打开命令行，输入 ollama run llama3，等待模型加载完成。

2. 启动 React 应用：在项目目录下运行 npm start，打开浏览器访问 http://localhost:3000。

3. 发送消息：在输入框中输入一个问题，比如 “你好，Ollama！”，然后点击 “发送” 按钮。稍等片刻，你应该就能看到 AI 的回复了。

如果一切顺利，你会看到 React 应用和 Ollama 成功 “牵手”，完成了一次愉快的对话。如果遇到问题，先检查 Ollama 是否正在正常运行，模型名称是否正确，网络连接是否通畅。

进阶思考：拓展可能性

这个简单的 Demo 只是一个开始，就像我们只是搭建了一座简陋的小桥。你可以基于这个基础进行很多拓展：

1. 实现流式响应：将 stream 设置为 true，然后处理流式响应，让 AI 的回复像打字一样逐字显示，提升用户体验。

2. 增加聊天历史：用状态管理存储聊天记录，让对话可以上下文连贯。

3. 切换不同模型：在界面上增加模型选择功能，让用户可以根据需要切换不同的 Ollama 模型。

4. 优化错误处理：增加更详细的错误提示，帮助用户排查问题。

总结：本地 AI 的魅力

通过这个 Demo，我们展示了 React 对接本地 Ollama 服务的全过程。相比于调用云端的 AI 服务，本地部署的 Ollama 具有隐私性好、响应速度快、无需网络连接等优点，就像把 AI 助手请到了自己家里，随时可以交流。

希望这篇文章能帮助你理解 React 与本地 AI 服务对接的原理和方法。现在，你可以基于这个基础，开发出更强大、更有趣的本地 AI 应用了。让我们一起探索前端与 AI 结合的无限可能吧！

在 Web 开发的世界里，前端与后端就像一对需要默契配合的舞者。前端负责优雅地展示数据，后端则默默在幕后准备数据，而接口就是它们之间传递信号的乐谱。在 Next.js 的舞台上，pages/api/*.ts就是谱写这份乐谱的最佳创作室。今天，我们就来揭开在 Next.js 中创建接口的神秘面纱，用 TypeScript 为你的全栈应用搭建起高效的数据桥梁。

接口的本质：数据交换的高速公路

在深入技术细节之前，让我们先理解接口的本质。想象你在餐厅点餐，你（前端）告诉服务员（接口）想要什么，服务员把需求传达给厨房（数据库 / 业务逻辑），然后把做好的食物（数据）端给你。这个过程中，服务员就是接口，负责规范请求格式、处理业务逻辑并返回结果。

在计算机科学中，接口本质上是客户端与服务器之间约定的数据交换格式和规则。Next.js 的 API 路由之所以强大，是因为它允许我们在同一个项目中同时编写前端页面和后端接口，就像在同一个屋檐下同时拥有餐厅大堂和厨房，大大提高了开发效率。

初探 pages/api：Next.js 的接口魔法

Next.js 的 API 路由基于一个简单而强大的约定：在pages/api目录下创建的文件会自动成为 API 接口。这个机制背后其实是 Next.js 的文件系统路由在起作用，当服务器启动时，它会扫描pages/api目录下的所有文件，为每个文件创建对应的路由端点。

比如我们创建pages/api/hello.ts文件，访问http://localhost:3000/api/hello就能调用这个接口。这种设计就像给每个接口分配了独立的办公室，它们互不干扰又能协同工作。

第一个接口：Hello World 的进阶版

让我们从经典的 Hello World 开始，创建一个能返回个性化问候的接口。在pages/api目录下新建greet.ts文件，输入以下代码：

export default function handler(req, res) {
  // 从请求中获取查询参数name
  const { name = "World" } = req.query;
  
  // 设置响应状态码为200（成功）
  res.status(200).json({ 
    message: `Hello, ${name}!`,
    timestamp: new Date().toISOString()
  });
}

这个接口做了三件事：

1. 从请求的查询参数中获取 name，如果没有提供则默认使用 "World"

2. 设置 HTTP 响应状态码为 200，表示请求成功

3. 返回一个 JSON 对象，包含问候消息和当前时间戳

运行你的 Next.js 应用，访问http://localhost:3000/api/greet?name=Next.js，你会看到类似这样的响应：

{
  "message": "Hello, Next.js!",
  "timestamp": "2025-08-17T12:34:56.789Z"
}

处理不同的 HTTP 方法：接口的多面手

一个健壮的接口应该能处理不同的 HTTP 方法，就像一个多才多艺的演员能胜任不同的角色。常见的 HTTP 方法有 GET（获取数据）、POST（创建数据）、PUT（更新数据）和 DELETE（删除数据）。

让我们创建一个简单的任务管理接口，支持 GET 和 POST 方法：

// pages/api/tasks.ts
let tasks = [
  { id: 1, title: "学习Next.js", completed: false },
  { id: 2, title: "创建API接口", completed: true }
];
export default function handler(req, res) {
  // 获取请求方法
  const { method } = req;
  switch (method) {
    case 'GET':
      // 处理GET请求：返回所有任务
      res.status(200).json(tasks);
      break;
    case 'POST':
      // 处理POST请求：创建新任务
      const { title } = req.body;
      
      // 验证请求数据
      if (!title) {
        return res.status(400).json({ error: "任务标题不能为空" });
      }
      
      // 创建新任务
      const newTask = {
        id: tasks.length + 1,
        title,
        completed: false
      };
      
      // 添加到任务列表
      tasks.push(newTask);
      
      // 返回创建的任务，状态码201表示资源创建成功
      res.status(201).json(newTask);
      break;
    default:
      // 处理不支持的方法
      res.setHeader('Allow', ['GET', 'POST']);
      res.status(405).end(`方法 ${method} 不被允许`);
  }
}

这个接口展示了如何根据不同的 HTTP 方法执行不同的操作：

• 当使用 GET 方法访问时，它返回所有任务列表

• 当使用 POST 方法并发送包含 title 的 JSON 数据时，它创建一个新任务

• 当使用不支持的方法（如 PUT 或 DELETE）时，它返回 405 错误

你可以使用工具如 Postman 或 curl 来测试这个接口：

# 测试GET请求
curl http://localhost:3000/api/tasks
# 测试POST请求
curl -X POST -H "Content-Type: application/json" -d '{"title":"新任务"}' http://localhost:3000/api/tasks

接口参数处理：精准获取请求数据

在实际开发中，我们经常需要从不同位置获取请求数据。Next.js 的 API 路由提供了多种方式来获取这些数据，就像有多个入口可以进入一个建筑：

1. 查询参数（Query Parameters） ：位于 URL 中?后面的键值对，通过req.query获取

2. 路径参数（Path Parameters） ：URL 路径中的动态部分，通过文件名中的[param]定义

3. 请求体（Request Body） ：POST、PUT 等方法发送的数据，通过req.body获取

让我们创建一个支持路径参数的接口，用于获取单个任务：

// pages/api/tasks/[id].ts
// 假设tasks数组与前面的例子相同
let tasks = [
  { id: 1, title: "学习Next.js", completed: false },
  { id: 2, title: "创建API接口", completed: true }
];
export default function handler(req, res) {
  const { id } = req.query;
  // 将id转换为数字
  const taskId = parseInt(id, 10);
  
  // 验证id是否有效
  if (isNaN(taskId)) {
    return res.status(400).json({ error: "无效的任务ID" });
  }
  
  // 查找任务
  const task = tasks.find(t => t.id === taskId);
  
  if (task) {
    res.status(200).json(task);
  } else {
    res.status(404).json({ error: "任务不存在" });
  }
}

现在，访问http://localhost:3000/api/tasks/1会返回 ID 为 1 的任务，而访问http://localhost:3000/api/tasks/99会返回 404 错误。

错误处理：接口的安全网

就像现实生活中需要应急预案一样，接口也需要完善的错误处理机制。一个好的错误处理策略应该：

• 返回适当的 HTTP 状态码

• 提供清晰的错误信息

• 避免暴露敏感信息

让我们改进前面的任务接口，添加更完善的错误处理：

// pages/api/tasks/[id].ts（改进版）
let tasks = [
  { id: 1, title: "学习Next.js", completed: false },
  { id: 2, title: "创建API接口", completed: true }
];
export default function handler(req, res) {
  try {
    const { id } = req.query;
    const taskId = parseInt(id, 10);
    
    if (isNaN(taskId)) {
      // 400 Bad Request：请求参数无效
      return res.status(400).json({ 
        error: "无效的任务ID",
        details: "ID必须是数字"
      });
    }
    
    const task = tasks.find(t => t.id === taskId);
    
    if (task) {
      // 200 OK：请求成功
      res.status(200).json(task);
    } else {
      // 404 Not Found：资源不存在
      res.status(404).json({ 
        error: "任务不存在",
        details: `没有ID为${taskId}的任务`
      });
    }
  } catch (error) {
    // 500 Internal Server Error：服务器内部错误
    console.error("处理请求时出错：", error);
    res.status(500).json({ 
      error: "服务器内部错误",
      details: "请稍后再试"
    });
  }
}

这个改进版接口使用 try-catch 块捕获可能的错误，并为不同类型的错误返回相应的状态码和详细信息，同时避免将内部错误直接暴露给客户端。

接口的性能考量：让数据流动更快

随着应用规模的增长，接口的性能变得越来越重要。以下是一些提高 API 路由性能的小贴士：

1. 数据缓存：对于不经常变化的数据，可以使用缓存减少重复计算

2. 请求验证：尽早验证请求数据，避免不必要的处理

3. 分页处理：对于大量数据，使用分页减少数据传输量

4. 异步处理：对于耗时操作，考虑使用异步处理避免阻塞

让我们实现一个带分页功能的任务列表接口：

// pages/api/tasks/paginated.ts
let tasks = [
  // 假设这里有很多任务...
  { id: 1, title: "任务1", completed: false },
  { id: 2, title: "任务2", completed: true },
  // ...更多任务
];
export default function handler(req, res) {
  try {
    // 获取分页参数，默认页码为1，每页10条
    const { page = 1, limit = 10 } = req.query;
    const pageNum = parseInt(page, 10);
    const limitNum = parseInt(limit, 10);
    
    // 验证分页参数
    if (isNaN(pageNum) || isNaN(limitNum) || pageNum < 1 || limitNum < 1) {
      return res.status(400).json({ 
        error: "无效的分页参数",
        details: "页码和每页数量必须是正整数"
      });
    }
    
    // 计算总页数
    const totalPages = Math.ceil(tasks.length / limitNum);
    
    // 计算起始索引
    const startIndex = (pageNum - 1) * limitNum;
    
    // 获取当前页的任务
    const paginatedTasks = tasks.slice(startIndex, startIndex + limitNum);
    
    res.status(200).json({
      data: paginatedTasks,
      pagination: {
        total: tasks.length,
        page: pageNum,
        limit: limitNum,
        totalPages
      }
    });
  } catch (error) {
    console.error("分页查询出错：", error);
    res.status(500).json({ error: "服务器内部错误" });
  }
}

这个接口支持通过page和limit参数控制返回的数据量，减轻了服务器和网络的负担。

部署与注意事项：让接口飞向生产环境

当你的接口准备好部署到生产环境时，有几个重要的注意事项：

1. 环境变量：敏感信息如数据库连接字符串应该使用环境变量，而不是硬编码在代码中

2. CORS 设置：如果你的前端和后端不在同一个域名下，需要配置跨域资源共享（CORS）

3. 速率限制：为了防止滥用，考虑添加速率限制功能

4. 日志记录：添加适当的日志记录以便调试和监控

在 Next.js 中配置 CORS 非常简单，你可以使用cors中间件：

// pages/api/with-cors.ts
import cors from 'cors';
// 初始化cors中间件
const corsMiddleware = cors({
  origin: process.env.NEXT_PUBLIC_FRONTEND_URL || '*',
  methods: ['GET', 'POST', 'PUT', 'DELETE']
});
// 辅助函数：将中间件转换为Promise
function runMiddleware(req, res, fn) {
  return new Promise((resolve, reject) => {
    fn(req, res, (result) => {
      if (result instanceof Error) {
        return reject(result);
      }
      return resolve(result);
    });
  });
}
export default async function handler(req, res) {
  // 应用CORS中间件
  await runMiddleware(req, res, corsMiddleware);
  
  // 处理请求
  res.status(200).json({ message: "这个接口支持跨域请求！" });
}

总结：接口开发的艺术与科学

在 Next.js 中创建 API 接口就像在构建一座连接前端和后端的桥梁，它需要扎实的技术基础，也需要对用户需求的深刻理解。通过pages/api/*.ts文件，我们可以快速创建功能完善的接口，处理各种 HTTP 方法，获取不同来源的请求数据，并返回结构化的响应。

记住，一个好的接口应该是清晰、健壮、高效且安全的。它不仅要能正确处理正常情况，还要能优雅地应对错误；不仅要能满足当前需求，还要为未来的扩展留有余地。

随着你对 Next.js API 路由的深入了解，你可以尝试更高级的功能，如数据库集成、身份验证、文件上传等。全栈开发的世界充满了可能性，而接口就是打开这个世界的钥匙。现在，拿起这把钥匙，开始构建你的全栈应用吧！