LangGraph智能体聊天界面开发：Agent Chat UI部署与定制指南

1. 项目概述：Agent Chat UI，一个为LangGraph智能体打造的专属聊天界面

如果你正在用LangGraph构建AI智能体，无论是Python还是TypeScript版本，那么你大概率会遇到一个共同的“最后一公里”问题：如何让最终用户方便、直观地与你的智能体进行对话？难道每次都要自己从头搭建一个聊天界面，处理复杂的流式响应、状态管理和错误处理吗？Agent Chat UI就是为了解决这个痛点而生的。它是一个开箱即用的Next.js应用，核心功能就是为你部署好的LangGraph服务器（无论是本地开发还是生产环境）提供一个功能完备、体验流畅的Web聊天界面。

简单来说，它扮演了“前端皮肤”的角色。你专注于在后台用LangGraph设计和训练强大的智能体逻辑，而Agent Chat UI则负责将智能体的“大脑”以用户友好的聊天窗口形式呈现出来。它通过标准的API与你的LangGraph服务器通信，只要你的服务器暴露了符合规范的messages端点，就能无缝接入。这意味着，无论你的智能体是处理客户支持、数据分析还是创意写作，你都可以快速获得一个可交互的演示界面或产品原型，极大地加速了从模型开发到用户可体验产品的过程。

这个项目特别适合几类人：一是独立开发者或小团队，希望快速验证智能体想法，不想在前端投入过多精力；二是AI应用开发者，需要为内部工具或客户交付一个直观的操作界面；三是教育或研究者，希望将复杂的智能体工作流以更易懂的方式展示出来。接下来，我将带你从零开始，深入这个项目的部署、定制化以及生产级应用的全过程，分享我在实际集成中踩过的坑和总结出的最佳实践。

2. 核心架构与设计思路解析

要理解Agent Chat UI的价值，首先得明白在LangGraph生态中，前端界面面临的挑战。LangGraph的核心是构建有状态的、可编排的智能体工作流。当这个工作流部署为服务后，其交互本质上是基于HTTP的请求-响应，尤其是支持Server-Sent Events（SSE）的流式响应。自己实现一个能稳定处理流式消息、管理对话线程、并优雅展示各种类型消息（文本、工具调用、结果、错误）的前端，工作量不小，且容易出错。

2.1 为什么选择Agent Chat UI？

Agent Chat UI的设计哲学是“约定大于配置”。它没有试图成为一个万能的前端框架，而是精准地瞄准了LangGraph智能体聊天这一场景，做了深度优化。其核心优势在于：

1. 开箱即用的流式处理：它内置了对LangGraph流式API的完整支持。当你的智能体生成一个长回复时，用户能看到文字逐个蹦出的效果，这对于提升体验至关重要。这部分涉及到对ReadableStream和SSE事件的复杂处理，UI已经帮你封装好了。
2. 与LangGraph状态模型深度绑定：它的数据模型与LangGraph的StateGraph中常见的messages状态键天然兼容。这意味着前端展示的消息列表，可以直接映射到后端智能体运行过程中的状态变化，减少了数据转换的胶水代码。
3. 灵活的部署与认证适配：它清晰地划分了本地开发和生产部署两种模式。本地开发时，前端可以直接连接你的本地LangGraph服务器，方便调试。生产部署时，它提供了API透传和自定义认证两种方案，安全地将用户请求转发到你的生产环境智能体，而无需在前端暴露敏感的API密钥。
4. 可扩展的UI组件：除了展示纯文本，它还支持渲染“工件”（Artifacts），比如图表、代码块、结构化数据等，可以通过侧边栏进行丰富展示。这为构建功能复杂的智能体应用（如数据分析助手、代码生成器）提供了UI扩展能力。

2.2 技术栈选型：Next.js的优势

项目基于Next.js构建，这是一个非常明智的选择。对于AI聊天类应用，Next.js带来了几个关键好处：

• 全栈能力：Next.js允许你在同一个项目中编写前端React组件和后端API路由。这对于实现上述的“API透传”模式至关重要。你可以在/pages/api或/app/api目录下创建一个代理接口，在前端界面和后端LangGraph服务器之间安全地中转请求和注入认证信息。
• 优秀的开发体验与性能：Next.js的快速刷新、基于文件的路由以及服务端渲染/静态生成能力，能加速开发流程，并优化最终应用的加载性能。对于聊天界面，首屏加载速度直接影响用户体验。
• 活跃的生态：Next.js拥有庞大的社区和丰富的UI组件库（如shadcn/ui，该项目似乎也采用了类似风格），可以快速构建出现代、美观的界面。项目本身的UI就采用了简洁的对话布局，响应式设计做得也不错。

理解了这些设计考量，我们就能更好地利用这个工具，而不是把它当作一个黑盒。接下来，我们进入实战环节，从环境搭建开始。

3. 从零开始：本地开发环境搭建与运行

让我们把手弄脏，先把项目跑起来。官方提供了两种极简的启动方式，我强烈推荐使用npx命令，它能最大程度避免环境差异带来的问题。

3.1 初始化项目

打开你的终端，执行以下命令。这会在当前目录下创建一个名为my-agent-chat的新文件夹，并完成所有基础文件的克隆和依赖安装。

npx create-agent-chat-app my-agent-chat

执行完毕后，进入项目目录：

cd my-agent-chat

注意：如果你遇到网络问题导致npx命令缓慢或失败，可以回退到传统的git clone方式：

git clone https://github.com/langchain-ai/agent-chat-ui.git cd agent-chat-ui

但之后你需要手动安装依赖。npx命令的优势在于它自动处理了这些步骤。

3.2 安装依赖与启动

项目使用pnpm作为包管理器，这比npm或yarn速度更快，磁盘空间利用更高效。如果你还没有安装pnpm，可以全局安装一下：npm install -g pnpm。

在项目根目录下，安装依赖：

pnpm install

这个过程会下载Next.js、React、LangChain相关前端库以及其他UI依赖。完成后，启动开发服务器：

pnpm dev

如果一切顺利，你将在终端看到类似下面的输出，表明应用已在http://localhost:3000启动。

> agent-chat-ui@0.1.0 dev > next dev ▲ Next.js 14.2.5 - Local: http://localhost:3000 - Environments: .env.local ✓ Ready in 2.1s

现在，打开浏览器访问http://localhost:3000。你会看到一个简洁的配置页面，而不是直接的聊天窗口。这是因为你需要告诉UI，它应该连接到哪里。

3.3 首次连接配置详解

首次打开的配置表单包含几个关键字段，理解它们对于后续调试和生产部署至关重要：

1. Deployment URL：这是你的LangGraph服务器的地址。在本地开发时，这通常就是你运行LangGraph服务的地址，例如http://localhost:2024（LangGraph服务的默认端口）。请确保你的LangGraph服务正在运行并监听着这个端口。
2. Assistant/Graph ID：这是你要连接的特定智能体或图的标识符。当你在LangGraph中定义并部署一个智能体时，你需要给它一个名字或ID。这个ID就是在这里填写的。例如，你的Python代码中可能通过app = workflow.compile(name=”customer_support_agent”)定义了名字，那么这里就填customer_support_agent。
3. LangSmith API Key：仅当连接已部署到LangSmith云平台的生产环境LangGraph服务器时才需要。对于本地开发，如果你的本地LangGraph服务不需要LangSmith认证（通常不需要），这里可以留空。如果你有Key，可以在 LangSmith设置页面 找到。
4. Built with Agent Builder：这是一个开关。如果你使用的是LangChain的Agent Builder工具创建并部署的智能体，请打开它。打开后，它会自动将认证方案设置为langsmith-api-key，简化配置。

填写完这些信息（对于本地开发，通常只需填写前两项），点击Continue。如果配置正确，页面将跳转到聊天主界面。此时，你可以在底部的输入框发送消息，界面会尝试连接你的本地LangGraph服务器并获取响应。

实操心得：第一次连接失败很常见。99%的问题出在Deployment URL和Assistant ID不匹配。请务必：

1. 确认你的LangGraph服务正在运行（检查终端是否有错误）。
2. 确认端口号正确。LangGraph默认是2024，但你的应用可能配置了其他端口。
3. 确认Assistant ID与后端代码中定义的完全一致，大小写敏感。
4. 打开浏览器的开发者工具（F12），切换到“网络”（Network）标签页，查看发送的请求是否返回错误（如404或500），这能提供最直接的线索。

4. 深入核心功能：消息控制与工件渲染

当基础聊天功能跑通后，你会面临更精细的控制需求：比如，有些中间步骤的消息不想展示给用户看，或者除了文本之外还想展示图表、文件等丰富内容。Agent Chat UI提供了强大的机制来处理这些场景。

4.1 精细控制消息可见性

在复杂的智能体工作流中，后台LLM（大语言模型）可能会产生一些用于内部推理、工具调用的中间消息，这些消息如果直接流式输出给用户，会造成干扰。Agent Chat UI提供了两种粒度的控制方式。

方法一：仅隐藏流式输出，但最终保留消息

有时，你希望某些模型调用过程不“一个字一个字”地流式显示，但调用完成后生成的消息内容仍然可以出现在对话历史中。这可以通过为聊天模型添加特定的标签来实现。

• 原理：Agent Chat UI前端通过监听LangGraph发出的on_chat_model_stream事件来实时渲染流式文本。当你给模型打上langsmith:nostream标签后，该模型调用就不会触发流式事件，因此前端不会显示流式过程。
• 操作示例（Python）：

  from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, END from typing import TypedDict, List from langchain_core.messages import BaseMessage class State(TypedDict): messages: List[BaseMessage] # 定义你的工作流 def call_llm(state: State): model = ChatOpenAI(model=”gpt-4”, temperature=0).with_config( config={“tags”: [“langsmith:nostream”]} # 关键在这里 ) # … 你的消息处理逻辑 result = model.invoke(state[“messages”]) return {“messages”: [result]} workflow = StateGraph(State) workflow.add_node(“llm_node”, call_llm) # … 设置边和入口 app = workflow.compile()

  在这个例子中，call_llm节点中的模型调用将不会在前端产生流式打字机效果，但result消息最终会被添加到状态中，并可能在下一次状态更新时显示在聊天记录里。

方法二：永久隐藏消息

如果你希望某些消息永远不出现在聊天界面中，无论是流式过程还是最终状态，你需要结合使用标签和消息ID前缀。

• 原理：前端代码会显式过滤掉所有id字段以do-not-render-开头的消息。因此，你需要在将消息保存到图状态之前，修改其ID。
• 操作示例（TypeScript）：

  import { ChatOpenAI } from “@langchain/openai”; import { BaseMessage } from “@langchain/core/messages”; import { StateGraph } from “@langchain/langgraph”; interface State { messages: BaseMessage[]; } const model = new ChatOpenAI({ modelName: “gpt-4” }).withConfig({ tags: [“langsmith:do-not-render”], // 第一步：添加标签 }); const someNode = async (state: State) => { // … 前置逻辑 const result = await model.invoke(state.messages); // 第二步：在保存到状态前，给消息ID加上前缀 result.id = `do-not-render-${result.id}`; return { messages: [result] }; };

  通过这两步操作，这条消息将被前端完全忽略。这在处理内部系统提示、调试信息或临时计算中间件时非常有用。

注意事项：这两种方法都需要在你的LangGraph智能体代码中进行修改，而不是在Agent Chat UI的前端代码里。这体现了前后端职责分离的设计：显示逻辑由前端根据约定（标签和ID）决定，而后端负责产生符合约定的数据。

4.2 渲染复杂工件（Artifacts）

纯文本对话有时不足以展示智能体的全部能力。例如，一个数据分析智能体可能需要展示一个图表，一个代码生成智能体可能需要高亮显示生成的代码块。Agent Chat UI通过“工件”系统支持这种富内容渲染。

工件被渲染在聊天界面右侧的一个可展开/折叠的侧边栏面板中。其核心机制是：LangGraph服务器可以在线程的元数据（thread.meta.artifact）中附加一个React组件及其状态，前端接收到后将其渲染在侧边栏。

后端如何发送工件？这取决于你的LangGraph服务器实现。通常，你需要在某个节点（Node）的执行逻辑中，不仅更新messages状态，还会向线程的元数据中注入工件信息。具体的API取决于你使用的LangGraph SDK版本和部署方式。

前端如何使用工件？项目提供了一个实用的Hook：useArtifact。它用于从当前聊天线程的上下文中获取工件组件和它的状态包（一个包含open、setOpen、context、setContext的对象）。

下面是一个更完整的前端组件示例，展示如何创建并连接一个工件：

// src/components/ChartArtifact.tsx import { useArtifact } from “../utils/use-artifact”; import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend } from ‘recharts’; // 假设后端传来的工件上下文是一个图表数据数组 interface ChartContext { title: string; data: Array<{name: string, value: number}>; } export function ChartArtifact() { // 使用Hook，并指定上下文类型 const [ArtifactComponent, artifactBag] = useArtifact<ChartContext>(); // 假设有一个按钮，点击后触发智能体生成图表数据 const handleRequestChart = async () => { // 这里应该是发送消息给智能体的逻辑... // 智能体处理后会设置 `thread.meta.artifact` }; // 如果当前没有活跃的工件，artifactBag.context 可能是 undefined const chartData = artifactBag?.context?.data || []; return ( <div> <button onClick={handleRequestChart}>生成销售图表</button> {/* ArtifactComponent 是一个由框架提供的包装器组件 */} <ArtifactComponent title={artifactBag?.context?.title || “图表”}> {/* 这里是工件的具体内容 */} {chartData.length > 0 ? ( <LineChart width={500} height={300} data={chartData}> <CartesianGrid strokeDasharray=”3 3″ /> <XAxis dataKey=”name” /> <YAxis /> <Tooltip /> <Legend /> <Line type=”monotone” dataKey=”value” stroke=”#8884d8″ /> </LineChart> ) : ( <p>暂无图表数据</p> )} </ArtifactComponent> </div> ); }

在这个例子中，ChartArtifact组件内部使用了useArtifact。当用户点击按钮，消息发送给智能体，智能体在处理过程中，除了返回文本回复，还会设置thread.meta.artifact，其中包含了图表数据和标题。前端框架会自动将artifactBag.context更新为这些数据，并打开侧边栏，渲染出LineChart。

实操心得：工件的渲染是Agent Chat UI的高级特性，它需要前后端协同设计。建议先从简单的文本或JSON展示开始，确保通信链路畅通。一个常见的坑是前后端对context数据结构的定义不一致，导致渲染错误。使用TypeScript并明确定义接口，能极大减少这类问题。

5. 迈向生产环境：部署与认证策略全解析

在本地玩转之后，下一步就是让其他人也能用上你的智能体。直接将本地开发模式（前端直连后端）部署到公网是不安全且不可行的，因为这要求每个访问你网页的用户都有自己的LangSmith API Key。Agent Chat UI提供了两种生产级方案。

5.1 方案一：API透传（推荐给大多数场景）

这是最简单、最快速的投产方式。其核心思想是：在前端（Next.js应用）和后端（LangGraph生产服务器）之间，建立一个你自己的API代理。所有从前端发出的、目标为LangGraph的请求，都先发到你自己的Next.js服务器端，由服务器端加上认证信息（如LangSmith API Key）后，再转发给真正的LangGraph服务器。这样，敏感的API Key就只存在于你的服务器环境变量中，对用户不可见。

项目已经集成了langgraph-nextjs-api-passthrough包来简化这一过程。你需要做的主要是配置环境变量。

生产环境变量配置（.env.production 文件）：

# 前端需要知道的助手ID，非机密，所以用 NEXT_PUBLIC_ NEXT_PUBLIC_ASSISTANT_ID=”your_production_assistant_id” # 你的生产环境LangGraph服务器地址（机密，不要加NEXT_PUBLIC_） LANGGRAPH_API_URL=”https://your-agent-12345.us.langgraph.app” # 你的网站部署后的域名 + /api 路径 NEXT_PUBLIC_API_URL=”https://your-website.com/api” # 你的LangSmith API Key（绝对机密！） LANGSMITH_API_KEY=”lsv2_sk_…”

关键点解析：

• NEXT_PUBLIC_API_URL：这是前端实际请求的地址。你设置为你的域名/api，意味着前端的所有聊天请求都会发送到你自己的Next.js应用的/api路由下。
• LANGGRAPH_API_URL和LANGSMITH_API_KEY：这两个变量在Next.js的服务端环境中被langgraph-nextjs-api-passthrough包读取。该包在/pages/api/[...path].ts或/app/api/[...path]/route.ts中创建了一个“万能”代理路由，它会将接收到请求的路径和参数，转发到LANGGRAPH_API_URL，并在请求头中自动加入Authorization: Bearer ${LANGSMITH_API_KEY}。
• 工作流程：用户发送消息 -> 前端请求https://your-website.com/api/...-> Next.js服务器端代理接收到请求 -> 代理将请求转发至https://your-agent-12345.us.langgraph.app/...并附加API Key -> 获取LangGraph响应 -> 代理将响应返回给前端。

这种方式部署后，用户打开你的网站，将直接进入聊天界面，而不会看到最初的配置表单，因为所需信息已通过环境变量提供。

5.2 方案二：自定义认证（适用于企业级集成）

如果你的安全要求更高，或者希望集成现有的用户认证体系（如OAuth2、JWT），那么可以使用LangGraph部署的“自定义认证”功能。在这种模式下，你的LangGraph服务器不再依赖LangSmith API Key，而是使用你自己定义的认证逻辑（例如，验证一个由你的主业务服务器签发的JWT令牌）。

实施步骤：

1. 配置LangGraph服务器：按照 LangGraph Python 或 TypeScript 的文档，为你的部署设置自定义认证。例如，你可以配置它只接受带有特定签名JWT令牌的请求。

2. 修改Agent Chat UI前端：你需要修改前端，使其在发送请求时携带自定义的认证令牌。

   • 首先，设置环境变量：NEXT_PUBLIC_API_URL直接指向你的生产LangGraph服务器地址，NEXT_PUBLIC_ASSISTANT_ID设置为对应的助手ID。不再需要LANGGRAPH_API_URL和LANGSMITH_API_KEY。
   • 然后，你需要修改前端请求的源头。在Agent Chat UI中，主要的通信逻辑封装在useTypedStream这个Hook里（通常位于src/providers/Stream.tsx或类似位置）。你需要在这里注入你的认证头。

   // 假设你有一个从你的认证服务获取Token的函数 import { getAuthToken } from ‘../lib/auth’; const streamValue = useTypedStream({ apiUrl: process.env.NEXT_PUBLIC_API_URL, // 直接指向你的LangGraph服务器 assistantId: process.env.NEXT_PUBLIC_ASSISTANT_ID, // … 其他配置 defaultHeaders: { // 添加你的自定义认证头，例如Bearer Token ‘Authorization’: `Bearer ${getAuthToken()}`, // 或者可能是你自定义的头部 ‘X-API-Key’: ‘your-custom-api-key’, }, });

3. 处理Token获取与刷新：在实际应用中，getAuthToken()需要实现从你的认证服务器获取、缓存并在过期时刷新令牌的逻辑。这通常涉及更复杂的状态管理，可能需要在应用顶层提供认证上下文。

注意事项：自定义认证方案提供了最大的灵活性，但也带来了更高的复杂度和维护成本。你需要自己负责令牌的生命周期管理、安全性（如HTTPS、令牌存储）等。对于大多数中小型项目或快速原型，API透传方案是更稳妥、更省心的选择。

6. 常见问题排查与实战技巧

在实际集成和使用Agent Chat UI的过程中，你肯定会遇到一些拦路虎。下面是我总结的一些典型问题及其解决方法，希望能帮你少走弯路。

6.1 连接与配置问题

问题1：打开页面后，一直卡在初始配置表单，点击“Continue”没反应或报错。

• 检查点1：控制台网络请求。打开浏览器开发者工具（F12），点击“Continue”后查看网络（Network）标签页。应该有一个向/api/assistants或类似端点发送的POST请求。查看这个请求的响应状态码和响应体。
  • 状态码400/404：通常是Deployment URL或Assistant ID错误。确认你的LangGraph服务正在运行且URL可访问（可以尝试在浏览器或curl中直接访问{Deployment_URL}/assistants/{Assistant_ID}看看）。
  • 状态码401：认证失败。如果你连接的是生产服务器且未使用API透传，请确认LangSmith API Key是否正确，或是否开启了Built with Agent Builder开关。
• 检查点2：CORS错误。如果你在本地开发，前端(localhost:3000)直接连接另一个本地后端服务(localhost:2024)，可能会遇到跨域问题。确保你的LangGraph服务器配置了正确的CORS头，允许来自localhost:3000的请求。对于LangGraph，你可以在创建FastAPI应用时添加CORS中间件。

问题2：可以进入聊天界面，但发送消息后无响应，或提示“Failed to fetch”。

• 检查点1：流式端点。确认你的LangGraph服务器是否正确实现了流式响应端点（通常是/runs/stream）。Agent Chat UI依赖于此。你可以用工具如curl或Postman测试该端点。

  curl -N -X POST “http://localhost:2024/assistants/{assistant_id}/runs/stream” \ -H “Content-Type: application/json” \ -d ‘{“input”: {“messages”: [{“role”: “user”, “content”: “Hello”}]}}’

  你应该看到持续的SSE数据流。如果没有，检查你的LangGraph应用代码。
• 检查点2：环境变量覆盖。如果你设置了.env.local文件来跳过配置表单，请确保变量名和值完全正确。一个常见的错误是NEXT_PUBLIC_API_URL末尾多了或少了斜杠。它应该类似于http://localhost:2024，而不是http://localhost:2024/（除非你的服务器路由需要）。

6.2 样式与UI问题

问题3：界面样式混乱或组件不显示。

• 检查点1：依赖安装。确保使用pnpm install安装了所有依赖。如果之前用过npm或yarn，建议删除node_modules和pnpm-lock.yaml，然后用pnpm重新安装。
• 检查点2：CSS冲突。如果你在自己的项目中集成了Agent Chat UI的组件，可能会遇到样式冲突。Agent Chat UI通常使用Tailwind CSS和某个UI库（如shadcn/ui）。确保你的主项目正确引入了这些样式，并且没有全局样式覆盖了组件的关键类名。

问题4：消息流式显示异常，比如不逐字出现，或显示乱码。

• 检查点：后端响应格式。Agent Chat UI期望LangGraph服务器返回严格符合特定格式的Server-Sent Events（SSE）。每条消息应该是一个以data:开头的JSON字符串，并以两个换行符\n\n结束。如果你的后端响应格式有偏差，前端解析就会失败。使用浏览器开发者工具的“网络”标签，查看流式响应的原始内容，确保其符合规范。

6.3 生产部署问题

问题5：使用API透传模式部署到Vercel后，聊天功能失效。

• 检查点1：环境变量。在Vercel项目设置的“Environment Variables”中，确保你添加了所有必要的变量：NEXT_PUBLIC_ASSISTANT_ID,NEXT_PUBLIC_API_URL,LANGGRAPH_API_URL,LANGSMITH_API_KEY。特别注意，LANGGRAPH_API_URL和LANGSMITH_API_KEY是服务端变量，不要加NEXT_PUBLIC_前缀。
• 检查点2：API路由。确保langgraph-nextjs-api-passthrough包创建的API路由已正确部署。部署后，访问https://your-website.com/api/assistants（将your-website.com换成你的域名）应该返回一个JSON响应，而不是404。如果是404，检查你的Next.js项目结构，确保/pages/api或/app/api目录存在且包含代理路由文件。
• 检查点3：服务器时区与超时。Vercel的Serverless函数有默认的超时限制。如果与你的LangGraph服务器通信时间过长，可能会超时。考虑在Vercel项目设置中调整函数的最大执行时长，或者优化你的智能体响应速度。

问题6：如何自定义UI主题（如颜色、字体）？Agent Chat UI的样式很大程度上由它使用的UI库决定。查看项目的tailwind.config.js和src/styles目录。你可以通过修改Tailwind配置来扩展主题色，或者直接覆盖相关组件的CSS类。更彻底的方式是，将你需要的组件（如ChatInterface）复制到你自己的项目中，然后直接修改其JSX和样式代码，进行深度定制。

6.4 高级调试技巧

• 启用详细日志：在开发时，可以在useTypedStreamHook的配置中或Next.js的API路由中添加详细的日志，打印出请求和响应的头信息、URL和 body，这对于排查认证和转发问题非常有效。
• 使用LangSmith进行追踪：如果你的智能体部署在LangSmith上，一定要利用好LangSmith的追踪（Tracing）功能。当聊天出现问题时，去LangSmith控制台查看对应链路的追踪记录，可以看到每一步的执行情况、输入输出，是定位后端逻辑错误的终极武器。
• 隔离测试：当问题复杂时，将系统拆解测试。先用curl或Postman直接测试LangGraph服务器的API，确保它本身工作正常。然后，单独测试你的Next.js API代理路由（如果用了透传），确保它能正确转发请求并添加头部。最后再测试前端界面。这种分层排查法能快速定位问题所在层。