大模型React组件配置：从环境准备到流式对话验证
想把大模型对话功能接进 React 项目，核心是配置好请求封装和流式响应组件。
本文按零基础可照做的顺序，从环境准备到最终验证，讲清楚每一步的配置项和常见报错。
适用于使用 React 18 及以上版本、通过浏览器直接调用大模型 API 的场景。
环境准备与依赖安装
先确认本地已安装 Node.js 18 以上版本和 npm。
打开终端执行 node -v，能输出 v18.x.x 或更高版本即可。
在项目根目录安装必要依赖。
如果使用官方 SDK，以 OpenAI 兼容接口为例：
npm install openai如果不想引入 SDK，也可以用浏览器原生 fetch，本文以 fetch 为例，减少依赖体积。
创建环境变量文件 .env.local，写入密钥：
REACT_APP_LLM_API_KEY=你的密钥
REACT_APP_LLM_BASE_URL=https://你的接口地址/v1注意：React 默认只读取以 REACT_APP_ 开头的变量。
密钥不要提交到 Git，把 .env.local 加入 .gitignore。
封装请求组件与流式处理
在 src 下新建 useLLM.js，封装对话请求。
关键点有两个：一是把消息数组按接口格式提交，二是用 ReadableStream 逐块读取返回内容。
import { useState, useCallback } from 'react';
export function useLLM() {
const [messages, setMessages] = useState([]);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const send = useCallback(async (content) => {
setLoading(true);
setError(null);
const nextMessages = [...messages, { role: 'user', content }];
setMessages(nextMessages);
try {
const res = await fetch(`${process.env.REACT_APP_LLM_BASE_URL}/chat/completions`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.REACT_APP_LLM_API_KEY}`
},
body: JSON.stringify({
model: '你的模型名称',
messages: nextMessages,
stream: true
})
});
if (!res.ok) {
throw new Error(`请求失败：${res.status}`);
}
const reader = res.body.getReader();
const decoder = new TextDecoder('utf-8');
let assistant = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value, { stream: true });
const lines = chunk.split('\n').filter(Boolean);
for (const line of lines) {
const cleaned = line.replace(/^data: /, '').trim();
if (cleaned === '[DONE]') continue;
try {
const json = JSON.parse(cleaned);
const delta = json.choices?.[0]?.delta?.content || '';
assistant += delta;
setMessages([...nextMessages, { role: 'assistant', content: assistant }]);
} catch (e) {
// 忽略不完整分片
}
}
}
} catch (err) {
setError(err.message);
} finally {
setLoading(false);
}
}, [messages]);
return { messages, loading, error, send };
}这段代码把用户消息和助手回复都保存在 messages 状态中，每次发送时带上完整历史。
实际项目里建议对历史长度做截断，避免超出模型上下文限制。
在页面中挂载对话组件
新建 ChatBox.jsx，引入上面的 Hook，渲染消息列表和输入框：
import { useState } from 'react';
import { useLLM } from './useLLM';
export default function ChatBox() {
const { messages, loading, error, send } = useLLM();
const [input, setInput] = useState('');
const handleSubmit = (e) => {
e.preventDefault();
if (!input.trim() || loading) return;
send(input.trim());
setInput('');
};
return (
{messages.map((m, i) => (
{m.role}：{m.content}
))}
{error && 出错了：{error}
}
);
}把 ChatBox 放到任意页面路由即可。
如果构建后页面空白，先检查浏览器控制台是否有 process is not defined，这通常是环境变量没有重新编译导致的，重启 npm start 即可。
避坑指南：密钥泄露与跨域问题
不要在前端代码里硬编码密钥。 本文的配置方式适合本地开发和内部演示。
生产环境应把请求转发到自己的后端服务，由后端保管密钥并限制调用频率，否则密钥一旦暴露可能被滥用。
跨域报错 CORS 通常是因为接口服务没有允许当前域名。
检查接口提供方是否支持浏览器直接调用；
如果不支持，需要在后端做一层代理，把 /api/chat 转发到模型接口，前端只请求自己的域名。
流式输出中断 时先看网络面板里响应状态码。
401 表示密钥无效或未带上 Authorization 头；
429 表示触发频率限制，需要降低请求频率或检查账户额度；
500 以上多为服务端问题，可稍后重试并查看接口方状态页。
消息重复渲染 在流式更新时比较常见。
本文通过每次替换最后一条助手消息来避免追加重复，如果你的实现里出现整段重复，检查是否在循环里误用了 push 而不是重建数组。
效果验证与上线前检查
在浏览器打开页面，输入一句“你好，请用一句话介绍自己”，点击发送。
预期结果是按钮变为“生成中…”，回复文字逐步出现，结束后按钮恢复可点击，且控制台没有红色报错。
上线前逐项确认：.env.local 已加入 .gitignore；
接口地址和模型名称与提供方文档一致；
历史消息有长度控制；
错误状态有用户可见提示。
如果准备公开访问，务必把密钥迁移到后端，前端只保留请求封装逻辑。
配置完成后，可以继续补充会话清空、重试按钮和 Markdown 渲染等增强功能。
遇到异常时，优先按本文的报错对照表定位，再检查环境变量是否在修改后重新加载。
