从零搭建 Coze 智能客服前端：Vite + 原生 HTML/CSS/JS 调用 Coze API 实战

无敌的拖拉斯旋风
140 阅读5分钟

3600200f0302eb9b116440629c41127c.jpeg 学 死命学！！

前言

在上一篇文章中，我们学会了如何在 Coze 平台 创建一个具备课程知识库的智能客服机器人。但真正的价值在于——把它集成到你自己的产品中。

本文将手把手带你：

  1. 用最简单的原生 HTML/CSS/JS 搭建一个交互界面
  2. 使用 Vite 构建工具管理环境变量（安全存储 API Key）
  3. 通过 fetch 调用 Coze 官方 API
  4. 实现“用户提问 → Coze 机器人回答”的完整闭环

整个项目无需后端、无需框架，纯前端即可运行，适合快速验证、教学演示或嵌入现有网站，强大的trae帮我们把一切都准备好了，我们只需要自己设计一下前端布局，在重写一下JS部分即可，万能AI开发工具做到我能做到的一切。

一、项目结构预览

我们将创建一个极简但完整的前端项目：

text
编辑
coze-chat-demo/
├── index.html          # 主页面
├── src/
│   └── main.js         # 交互逻辑
└── .env.local          # 存放敏感密钥（不提交到 Git！）

✅ 技术栈：HTML + CSS + 原生 JavaScript + Vite

二、第一步：初始化 Vite 项目

1. 安装 Vite（需 Node.js ≥ 16）

bash
编辑
npm create vite@latest coze-chat-demo -- --template vanilla
cd coze-chat-demo
npm install

--template vanilla 表示使用原生 JS，不带 React/Vue。

2. 启动开发服务器

bash
编辑
npm run dev

默认访问 http://localhost:5173

三、第二步：配置环境变量（安全存储密钥）

创建 .env.local 文件

在项目根目录下新建 .env.local，填入你的 Coze 凭据：

env
编辑
VITE_BOT_ID=7577741712580427817
VITE_API_KEY=cztei_qD7d1lsT3uCJ6VKs85kFG36CLugTuQndcrdIosvGtgP23cJHvpfJHqbX30URP4BTt

🔒 重要安全规则：

  • 所有以 VITE_ 开头的变量会被 Vite 自动注入到前端代码中
  • 绝不要将 .env.local 提交到 Git！在 .gitignore 中确保它被忽略

（这里我想说的是强大AI开放工具一件事搞定这些项目布置，小白的绝世福利）

四、第三步：编写前端页面（index.html）

替换 index.html 内容如下：

html
预览
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Coze 智能客服 Demo</title>
  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
      max-width: 800px;
      margin: 40px auto;
      padding: 0 20px;
      background: #f9fafb;
    }
    h1 {
      text-align: center;
      color: #1f2937;
      margin-bottom: 30px;
    }
    #ipt {
      width: 100%;
      padding: 12px;
      font-size: 16px;
      border: 1px solid #d1d5db;
      border-radius: 8px;
      box-sizing: border-box;
    }
    #reply {
      margin-top: 20px;
      padding: 16px;
      background: white;
      border: 1px solid #e5e7eb;
      border-radius: 8px;
      min-height: 60px;
      line-height: 1.6;
      color: #374151;
    }
  </style>
</head>
<body>
  <h1>🤖 Coze 智能客服 Demo</h1>
  <input type="text" id="ipt" placeholder="例如：课程包含哪些实战项目？" />
  <div id="reply">正在等待您的问题...</div>

  <!-- 使用 type="module" 支持 ES6 import 和环境变量 -->
  <script type="module" src="/src/main.js"></script>
</body>
</html>

💡 设计理念：简洁、清晰、移动端友好

五、第四步：实现核心交互逻辑（main.js）

在 src/main.js 中写入以下代码：

js
编辑
// 获取 DOM 元素
const ipt = document.getElementById('ipt');
const reply = document.getElementById('reply');

// Coze API 配置
const endpoint = 'https://api.coze.cn/open_api/v2/chat';

// 监听输入框的 "回车" 或 "失去焦点" 事件（更友好）
ipt.addEventListener('keypress', async function (event) {
  if (event.key === 'Enter') {
    const prompt = event.target.value.trim();
    if (!prompt) return;

    // 显示加载状态
    reply.innerHTML = '🤔 正在思考...';

    try {
      // 构造请求体
      const payload = {
        bot_id: import.meta.env.VITE_BOT_ID,
        user: 'user_' + Date.now(), // 简单生成唯一用户ID
        query: prompt,
        chat_history: [], // 本次为单轮对话
        stream: false,
        custom_variables: {} // 可选，用于传递上下文
      };

      // 发送请求到 Coze API
      const response = await fetch(endpoint, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${import.meta.env.VITE_API_KEY}`
        },
        body: JSON.stringify(payload)
      });

      // 处理响应
      const data = await response.json();

      if (data.code !== 0) {
        throw new Error(data.msg || 'API 调用失败');
      }

      // 渲染机器人回复
      reply.innerHTML = data.messages[0].content || '抱歉，我无法回答这个问题。';

    } catch (error) {
      console.error('Error:', error);
      reply.innerHTML = `❌ 出错了：${error.message}`;
    }
  }
});

✅ 关键点解析见下文

六、交互流程详解：从用户输入到 AI 回答

整个过程分为 5 个阶段：

阶段 1️⃣：用户输入问题

  • 用户在 <input id="ipt"> 中输入文本
  • 按下 Enter 键 触发 keypress 事件

阶段 2️⃣：前端构造 API 请求

  • 读取环境变量：import.meta.env.VITE_BOT_ID 和 VITE_API_KEY

  • 构建 payload 对象，包含：

    • bot_id：你的 Coze 机器人 ID
    • query：用户的问题
    • user：唯一用户标识（用于会话追踪）
    • chat_history：留空表示单轮对话

阶段 3️⃣：调用 Coze API

  • 使用 fetch 向 https://api.coze.cn/open_api/v2/chat 发起 POST 请求

  • 请求头包含：

    • Content-Type: application/json
    • Authorization: Bearer <你的API_KEY>

阶段 4️⃣：接收并解析响应

  • Coze 返回 JSON 格式数据，结构如下：

    json
编辑
{
  "code": 0,
  "msg": "success",
  "messages": [
    { "role": "assistant", "content": "Python 入门课包含三个项目..." }
  ]
}

  • 提取 data.messages[0].content 作为回答

阶段 5️⃣：更新页面显示

  • 将 AI 回答写入 <div id="reply">
  • 若出错，显示友好错误提示

七、常见问题与调试技巧

❌ 问题 1：401 Unauthorized

  • 原因：API Key 错误或未正确注入

  • 解决：

    • 检查 .env.local 是否命名为 VITE_API_KEY
    • 确保变量名以 VITE_ 开头
    • 重启 Vite 开发服务器（.env 修改后需重启） （小提示，不要将.env.local写入与你html文件同级的文件中，我也犯这个错误了，写在比项目文件大一级的文件夹中，不然你的tokens 将会一直报错，因为他根本没识别）

❌ 问题 2：data.messages is undefined

  • 原因：API 返回错误（如 code: 4101 token 错误）

  • 解决：

    • 在 console.log(data) 查看完整响应
    • 检查 Bot ID 是否正确（注意不是 Space ID）

✅ 调试建议：

image.png

八、进阶优化方向

功能实现方式
多轮对话保存 chat_history，每次追加用户和 AI 的消息
流式响应设置 stream: true，用 SSE 或 WebSocket 接收实时输出
图片上传使用 Coze 的文件上传 API，先传图再提问
部署上线npm run build 生成静态文件，部署到 Vercel/Netlify

九、总结

通过这个小项目，你已经掌握了：

  • ✅ 如何用 原生 HTML/CSS/JS 快速搭建交互界面
  • ✅ 如何用 Vite 管理环境变量，安全使用 API Key
  • ✅ 如何 调用 Coze 官方 API，接入你的专属智能体
  • ✅ 完整的 前端 → AI → 前端 数据流

记住：
“AI 的价值不在模型本身，而在它如何融入你的业务场景。”
—— 现在，你已经有了把 Coze 机器人嵌入任何网页的能力。

🚀 下一步行动

  1. 替换 .env.local 中的 BOT_ID 和 API_KEY 为你自己的
  2. 运行 npm run dev
  3. 在浏览器中提问：“你们的 Python 课程有什么项目？”
  4. 看着你的知识库内容被精准回答！

你离“随处智能”只差这一个文件。全员大厂，冲冲冲！！！

avatar
文章
阅读
粉丝