最近在尝试将大模型能力集成到Web应用中时发现许多开发者卡在了本地部署和API对接环节。Claude作为业界领先的AI模型其官方推出的Claude Code工具链为开发者提供了一个相对便捷的本地开发与测试环境。本文将手把手带你从零开始使用Claude Code搭建一个具备基础对话功能的AI网站涵盖环境配置、核心代码编写、前端交互实现到部署上线的完整闭环。无论你是想学习AI应用开发还是希望为自己的项目添加智能对话能力这篇教程都能提供可直接复用的代码和清晰的排错思路。1. 背景与核心概念为什么选择Claude Code在构建AI网站时我们通常有两种选择一是直接调用云服务商提供的API如OpenAI的GPT系列、Anthropic的Claude API二是本地部署开源模型。前者简单快捷但涉及费用和网络依赖后者对硬件要求高且调试复杂。Claude Code的出现在两者之间提供了一个折中的“本地开发套件”方案。它并非一个可以在生产环境无限使用的免费Claude模型而是Anthropic为开发者提供的一个本地开发工具主要用于本地测试与原型开发在编写调用Claude API的代码时可以在本地进行快速测试和调试无需消耗API额度。学习与实验开发者可以熟悉Claude模型的基本交互模式、提示词工程以及流式响应等特性。构建功能演示快速搭建一个可演示的AI对话应用前端。核心概念区分Claude APIAnthropic提供的云端商业接口按Token收费稳定、强大用于生产环境。Claude Code (本地开发套件)一个包含本地模拟服务器、SDK和示例的开发者工具旨在模拟API行为免费用于本地开发但有使用限制如速率限制、非最新模型。Claude Desktop App官方的桌面客户端提供图形化聊天界面。第三方镜像/网页版非官方访问途径存在安全、稳定和法律风险不推荐用于开发。因此使用Claude Code搭建网站本质是构建一个前端界面并连接到一个运行在你本机或测试服务器的、模拟Claude API的后端服务。这是学习AI应用开发非常理想的第一步。2. 环境准备与版本说明在开始编码前请确保你的开发环境满足以下要求。本文将以一个最通用的全栈技术栈为例进行演示。2.1 基础运行环境操作系统Windows 10/11, macOS 10.15, 或 Ubuntu 20.04。本文命令以macOS/Linux的bash和Windows的PowerShell为例。Node.js版本 18 或更高。这是运行前端构建工具和后端开发服务器的基础。Python版本 3.8 或更高。某些后端库或工具可能需要Python环境。包管理工具npm(随Node.js安装) 或yarn。代码编辑器Visual Studio Code (VSCode) 是首选因其对JavaScript/TypeScript和Claude Code扩展有良好支持。2.2 Claude Code 安装与验证这是最关键的一步。Claude Code的安装方式随着版本更新可能变化请以官方GitHub仓库的最新说明为准。访问官方渠道通过搜索引擎查找“Claude Code GitHub”找到官方仓库。务必从官方或可信源获取安装包避免安全风险。下载与安装macOS通常提供.dmg安装包下载后拖入应用程序文件夹即可。Windows提供.exe安装程序或可通过包管理器如winget安装。Linux可能提供.AppImage文件或通过包管理器安装。安装验证 安装完成后启动Claude Code应用程序。首次启动可能会要求你登录Anthropic账户部分功能需要。成功启动后通常会在系统托盘macOS菜单栏/Windows任务栏看到一个图标。获取本地API密钥/端点 Claude Code运行后会在本地启动一个模拟的API服务。你需要找到其访问地址和模拟的API密钥。这些信息通常可以在应用设置或官方文档中找到。例如常见的本地端点可能是http://localhost:3000/v1而API密钥可能是一个固定的字符串如sk-local-...。重要这个密钥仅用于连接本地Claude Code服务不能用于访问真实的Claude API。2.3 项目技术栈选择为了快速构建一个完整的、可演示的网站我们选择以下技术栈前端React Vite。Vite启动快生态好适合现代Web开发。UI库Ant Design (antd)。提供丰富的预制组件加速开发。HTTP客户端Axios。用于向后端发送请求。后端可选为了简化我们初期将让前端直接调用本地Claude Code服务。在生产部署时你需要一个真正的后端如Node.js Express, Python FastAPI来代理请求、管理密钥和实现业务逻辑。3. 核心原理与项目结构设计我们的AI网站核心功能是用户在前端输入问题前端将问题发送给本地的Claude Code服务Claude Code返回AI生成的回答前端再展示给用户。3.1 通信流程用户浏览器 - 输入文本 - 前端React应用 - (HTTP请求) - 本地Claude Code服务 - (处理并返回流式响应) - 前端React应用 - 渲染Markdown并逐字显示由于AI生成内容可能较长为了更好的用户体验我们采用流式响应Server-Sent Events, SSE来接收数据实现打字机效果。3.2 项目结构规划创建项目文件夹claude-ai-website内部结构如下claude-ai-website/ ├── public/ # 静态资源 ├── src/ │ ├── components/ # React组件 │ │ ├── ChatWindow.jsx # 主聊天窗口组件 │ │ └── Message.jsx # 单条消息展示组件 │ ├── services/ # 服务层处理API调用 │ │ └── claudeService.js # 封装与Claude Code的通信 │ ├── App.jsx # 主应用组件 │ ├── main.jsx # 应用入口 │ └── index.css # 全局样式 ├── .env.local # 本地环境变量API端点、密钥 ├── index.html ├── package.json ├── vite.config.js # Vite配置 └── README.md4. 完整实战一步步搭建AI对话网站4.1 初始化项目与安装依赖打开终端执行以下命令# 使用Vite创建React项目 npm create vitelatest claude-ai-website -- --template react cd claude-ai-website # 安装必要的依赖 npm install axios antd ant-design/icons npm install --save-dev sass # 可选用于编写CSS4.2 配置环境变量在项目根目录创建.env.local文件用于存储敏感配置。切记不要将此文件提交到Git仓库。# .env.local VITE_CLAUDE_API_BASE_URLhttp://localhost:3000/v1 # 替换为你的Claude Code本地端点 VITE_CLAUDE_API_KEYsk-local-xxxxxxxxxxxxxxxxxxxxxxx # 替换为你的Claude Code本地密钥4.3 实现API服务层创建src/services/claudeService.js封装与Claude Code的交互逻辑。// src/services/claudeService.js import axios from axios; // 从环境变量读取配置 const API_BASE_URL import.meta.env.VITE_CLAUDE_API_BASE_URL; const API_KEY import.meta.env.VITE_CLAUDE_API_KEY; // 创建Axios实例统一设置请求头 const claudeApi axios.create({ baseURL: API_BASE_URL, headers: { Content-Type: application/json, Authorization: Bearer ${API_KEY}, anthropic-version: 2023-06-01 // 指定Claude API版本 }, }); /** * 向Claude Code发送消息非流式 * param {string} message 用户输入的消息 * param {Array} history 对话历史 * returns {Promisestring} AI的回复 */ export const sendMessage async (message, history []) { try { // 构建符合Claude API格式的messages数组 const messages [ ...history.map(h ({ role: h.role, content: h.content })), { role: user, content: message } ]; const response await claudeApi.post(/messages, { model: claude-3-haiku-20240307, // Claude Code通常支持此模型 max_tokens: 1024, messages: messages, // stream: false, // 非流式 }); // 提取AI回复的文本内容 return response.data.content[0].text; } catch (error) { console.error(调用Claude API失败:, error); if (error.response) { console.error(错误状态:, error.response.status); console.error(错误信息:, error.response.data); } throw new Error(AI服务暂时不可用: ${error.message}); } }; /** * 向Claude Code发送消息流式 * param {string} message 用户输入的消息 * param {Array} history 对话历史 * param {Function} onChunk 接收到数据块时的回调函数 * param {Function} onDone 流式接收完成时的回调函数 * param {Function} onError 发生错误时的回调函数 */ export const sendMessageStream async (message, history, onChunk, onDone, onError) { const messages [ ...history.map(h ({ role: h.role, content: h.content })), { role: user, content: message } ]; const requestBody { model: claude-3-haiku-20240307, max_tokens: 1024, messages: messages, stream: true, // 启用流式 }; try { const response await fetch(${API_BASE_URL}/messages, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${API_KEY}, anthropic-version: 2023-06-01, }, body: JSON.stringify(requestBody), }); if (!response.ok) { throw new Error(HTTP error! status: ${response.status}); } const reader response.body.getReader(); const decoder new TextDecoder(utf-8); let accumulatedText ; while (true) { const { done, value } await reader.read(); if (done) { onDone onDone(accumulatedText); break; } const chunk decoder.decode(value, { stream: true }); const lines chunk.split(\n).filter(line line.trim() ! ); for (const line of lines) { if (line.startsWith(data: )) { const data line.slice(6); // 去掉data: 前缀 if (data [DONE]) { continue; } try { const parsed JSON.parse(data); if (parsed.type content_block_delta parsed.delta?.text) { accumulatedText parsed.delta.text; onChunk onChunk(parsed.delta.text); } } catch (e) { console.warn(解析SSE数据失败:, e, 原始数据:, data); } } } } } catch (error) { console.error(流式请求失败:, error); onError onError(error); } };4.4 构建React聊天组件首先创建单条消息组件src/components/Message.jsx。// src/components/Message.jsx import React from react; import { Avatar, Typography } from antd; import { UserOutlined, RobotOutlined } from ant-design/icons; import ReactMarkdown from react-markdown; // 需要安装npm install react-markdown const { Text } Typography; const Message ({ message }) { const isUser message.role user; return ( div style{{ display: flex, marginBottom: 16px, flexDirection: isUser ? row-reverse : row, }} Avatar sizelarge icon{isUser ? UserOutlined / : RobotOutlined /} style{{ backgroundColor: isUser ? #1890ff : #52c41a, margin: isUser ? 0 0 0 12px : 0 12px 0 0, }} / div style{{ maxWidth: 70%, backgroundColor: isUser ? #1890ff : #f0f0f0, color: isUser ? white : black, padding: 10px 16px, borderRadius: 18px, wordBreak: break-word, }} {message.isStreaming ? ( Text {message.content} span style{{ animation: blink 1s infinite }}▌/span /Text ) : ( ReactMarkdown {message.content} /ReactMarkdown )} /div /div ); }; export default Message;接着创建主聊天窗口组件src/components/ChatWindow.jsx。// src/components/ChatWindow.jsx import React, { useState, useRef, useEffect } from react; import { Input, Button, Card, Spin, Alert } from antd; import { SendOutlined } from ant-design/icons; import Message from ./Message; import { sendMessageStream } from ../services/claudeService; const { TextArea } Input; const ChatWindow () { const [inputText, setInputText] useState(); const [messages, setMessages] useState([ { role: assistant, content: 你好我是由Claude驱动的AI助手。有什么可以帮你的吗 } ]); const [loading, setLoading] useState(false); const [error, setError] useState(null); const messagesEndRef useRef(null); // 自动滚动到底部 const scrollToBottom () { messagesEndRef.current?.scrollIntoView({ behavior: smooth }); }; useEffect(scrollToBottom, [messages]); const handleSend async () { if (!inputText.trim() || loading) return; const userMessage inputText.trim(); setInputText(); setError(null); // 添加用户消息 const newMessages [...messages, { role: user, content: userMessage }]; setMessages(newMessages); setLoading(true); // 添加一个初始的、空的AI消息用于流式更新 const aiMessageIndex newMessages.length; setMessages(prev [...prev, { role: assistant, content: , isStreaming: true }]); try { await sendMessageStream( userMessage, newMessages.slice(0, -1), // 历史消息不包含刚添加的AI空消息 (chunk) { // 流式更新最后一条AI消息的内容 setMessages(prev { const updated [...prev]; if (updated[aiMessageIndex]) { updated[aiMessageIndex].content chunk; } return updated; }); }, (fullText) { // 流式完成更新状态 setMessages(prev { const updated [...prev]; if (updated[aiMessageIndex]) { updated[aiMessageIndex].content fullText; updated[aiMessageIndex].isStreaming false; } return updated; }); setLoading(false); }, (err) { // 发生错误 setError(请求失败: ${err.message}); setMessages(prev prev.filter((_, idx) idx ! aiMessageIndex)); // 移除空的AI消息 setLoading(false); } ); } catch (err) { setError(发送请求时出错: ${err.message}); setMessages(prev prev.filter((_, idx) idx ! aiMessageIndex)); setLoading(false); } }; const handleKeyPress (e) { if (e.key Enter !e.shiftKey) { e.preventDefault(); handleSend(); } }; return ( Card titleClaude AI 对话助手 style{{ width: 100%, maxWidth: 800px, margin: 20px auto }} bodyStyle{{ padding: 24px }} {error ( Alert message错误 description{error} typeerror showIcon closable onClose{() setError(null)} style{{ marginBottom: 16px }} / )} div style{{ height: 500px, overflowY: auto, padding: 16px, border: 1px solid #d9d9d9, borderRadius: 8px, marginBottom: 16px, backgroundColor: #fafafa }} {messages.map((msg, index) ( Message key{index} message{msg} / ))} {loading div style{{ textAlign: center }}Spin tipAI思考中... //div} div ref{messagesEndRef} / /div div style{{ display: flex }} TextArea value{inputText} onChange{(e) setInputText(e.target.value)} onKeyDown{handleKeyPress} placeholder输入您的问题...按Enter发送ShiftEnter换行 autoSize{{ minRows: 3, maxRows: 6 }} disabled{loading} style{{ marginRight: 8px }} / Button typeprimary icon{SendOutlined /} onClick{handleSend} loading{loading} style{{ height: auto }} 发送 /Button /div /Card ); }; export default ChatWindow;4.5 集成组件并启动应用修改src/App.jsx和src/main.jsx。// src/App.jsx import React from react; import ChatWindow from ./components/ChatWindow; import ./App.css; function App() { return ( div classNameApp ChatWindow / /div ); } export default App;// src/main.jsx import React from react; import ReactDOM from react-dom/client; import App from ./App; import antd/dist/reset.css; // 引入Ant Design样式 import ./index.css; ReactDOM.createRoot(document.getElementById(root)).render( React.StrictMode App / /React.StrictMode, );4.6 运行与验证启动Claude Code应用确保Claude Code在后台运行并且你知道它的本地API地址和密钥。启动前端开发服务器在项目根目录下运行npm run devVite会启动一个本地开发服务器通常在http://localhost:5173。打开浏览器访问http://localhost:5173。测试对话在输入框中输入问题如“用Python写一个快速排序函数”点击发送。你应该能看到消息列表更新并且AI的回答以流式打字机效果呈现。5. 常见问题与排查思路在开发过程中你可能会遇到以下问题问题现象可能原因排查步骤与解决方案前端无法连接Claude Code(网络错误/CORS错误)1. Claude Code服务未运行。2. 环境变量VITE_CLAUDE_API_BASE_URL配置错误。3. 浏览器跨域限制。1. 检查Claude Code应用是否已启动。2. 检查.env.local文件中的URL和密钥是否正确。可在浏览器直接访问{你的URL}/health看是否有响应。3. Claude Code可能未配置CORS。对于开发可以配置Vite代理或使用浏览器插件临时禁用CORS仅限开发。API返回 401/403 错误API密钥错误或缺失。1. 确认.env.local中的VITE_CLAUDE_API_KEY与Claude Code设置中的本地密钥一致。2. 检查claudeService.js中请求头Authorization的格式是否正确。API返回 404 错误请求的端点路径错误。1. Claude Code的API路径可能不是标准的/v1/messages。请查阅Claude Code的官方文档或通过其界面查看正确的API路径。2. 确认model参数是Claude Code支持的模型。流式响应不工作一次性返回1. Claude Code服务不支持流式。2. 前端SSE解析逻辑有误。1. 确认你使用的Claude Code版本支持流式响应。可以先用curl或 Postman 测试/messages端点设置stream: true。2. 检查claudeService.js中的sendMessageStream函数特别是对data:前缀和[DONE]事件的处理。应用样式错乱Ant Design CSS未正确引入。确认main.jsx中已导入import antd/dist/reset.css;。react-markdown未找到依赖未安装。在项目根目录运行npm install react-markdown。通用排查命令 在终端使用curl测试Claude Code服务是否正常curl -X POST http://localhost:3000/v1/messages \ -H Content-Type: application/json \ -H Authorization: Bearer sk-local-xxxx \ -H anthropic-version: 2023-06-01 \ -d { model: claude-3-haiku-20240307, max_tokens: 100, messages: [{role: user, content: Hello}] }6. 最佳实践与工程建议将本地Demo推进到更健壮、可部署的项目需要考虑以下方面6.1 安全与配置管理永远不要在前端暴露真实API密钥本文为演示简化将密钥放在前端环境变量中。在生产环境中这是极度危险的行为。必须构建一个后端服务器由后端持有密钥并转发请求。前端只与你的后端通信。使用环境变量将所有配置API地址、模型名称、超时时间通过环境变量管理区分开发、测试、生产环境。实施请求限流与鉴权在你的后端服务中对用户请求进行频率限制和身份验证防止滥用。6.2 用户体验优化上下文管理Claude API支持传递历史对话。合理管理上下文长度避免无限增长导致令牌数超限或性能下降。可以实现“只保留最近N轮对话”或“总结长上下文”的策略。错误友好提示对网络错误、API限额、内容过滤等不同错误类型在前端给出用户能理解的友好提示。支持Markdown渲染如本文所示使用react-markdown等库渲染AI返回的Markdown格式文本提升代码、列表等内容的可读性。添加停止生成按钮在流式响应过程中提供按钮让用户可以中断AI的生成。6.3 代码结构与可维护性状态管理当应用复杂时如多会话、设置页考虑引入状态管理库Zustand, Redux Toolkit。服务层抽象将API调用逻辑封装在独立的服务模块中便于统一处理错误、添加日志、更换AI提供商。组件化将UI拆分为更细粒度的可复用组件如SettingsPanel,ConversationHistory等。6.4 部署上线构建生产版本运行npm run build将生成的dist文件夹内容部署到静态网站托管服务如Vercel, Netlify, GitHub Pages。部署后端代理使用Node.js (Express)、Python (FastAPI/Flask) 或 Go 编写一个简单的后端服务部署在云服务器如AWS EC2, Google Cloud Run或Serverless平台如Vercel Serverless Functions。该后端负责从安全的环境变量中读取真实的Claude API密钥。接收前端请求。将请求转发至真实的Claude API或你最终选用的AI服务。将响应返回给前端。域名与HTTPS为你的网站配置自定义域名和SSL证书确保通信安全。6.5 超越Claude CodeClaude Code是优秀的开发工具但最终你的应用很可能需要连接到真实的Claude API或其他大模型如GPT、DeepSeek、国内大模型。只需将后端代理服务中的目标URL和认证信息更换即可前端代码基本无需改动。这种架构保证了应用的灵活性和可扩展性。通过本教程你不仅搭建了一个可运行的AI对话网站更掌握了一套从本地开发测试到考虑生产部署的完整思路。接下来你可以尝试为网站添加更多功能例如对话历史持久化、多模型切换、文件上传解析等逐步将其完善成一个功能丰富的AI应用原型。