简介：这款微信小程序AI机器人对话模板基于HBuilder开发，属于纯前端界面方案，未内置接口，适合具备小程序开发基础、需要快速搭建AI聊天交互页面的开发者。包内共2000个文件，以js、ts、vue、json、md等类型为主，其中js/ts文件承载核心逻辑，vue与wxml/wxss负责页面结构和样式，json用于项目配置，md提供说明文档，压缩包整体仅7.04MB，结构紧凑便于本地调试与二次扩展。目前已有967人学习，热度不俗。模板提供了完整的聊天窗口、消息列表、输入交互等常见模块，并预留接口对接位置，开发者只需根据业务需求调整后端服务即可接入真实AI能力；同时源码分层清晰，可快速定位修改点，能有效缩短前期UI搭建周期，尤其适用于课程设计、毕业设计或商业项目原型验证阶段。
1. AI 聊天机器人微信小程序模板：先认清它替你写好了哪些活
把 AI 对话塞进微信小程序，最花时间的从来不是调大模型接口，而是接口外面的那堆“脏活”：输入框焦点和键盘遮挡、消息气泡的滚动定位、请求等待时的按钮防重复点击、上下文越聊越长导致费用失控。这套微信小程序模板就是把这些骨架提前搭好，聊天页面、消息数据结构、请求封装、状态流转都是现成的，你只需要把底部那个 API 地址换成自己的服务，就能跑起来一个能用的 AI 对话小程序。适合两类人：一是小团队想快速验证 AI 产品、不想从零写界面的，二是刚接触小程序、想照着成熟结构学聊天类页面怎么组织的开发者。
2. 接口选型与数据流：API 怎么接、上下文窗口怎么控
在动手改模板之前，先把数据流理清楚。这个模板的价值不在于某个特效，而在于它把“用户输入 → 组装请求 → 渲染回复 → 管理会话”这条链路做成了标准结构，你拿到手后替换的只是中间那一段网络请求。
2.1 先定接入方式：直连云端 API，还是走自己的服务端
模板里预留的是接口地址配置位，接入方式上一般有三种选择。
第一种是前端直接调用云端大模型 API。优点是开发最快，小程序里配置好 baseUrl 和 key 就能联调；缺点是密钥写在前端，上线后存在被扒的风险，而且小程序后台要求所有请求域名必须备案且配 HTTPS，很多海外模型服务的域名在小程序里直接请求会撞上合法域名校验。第二种是自己写一个轻量服务端，把 key 放在服务端，小程序只请求你自己的域名，由服务端转发到大模型。多一层部署成本，但密钥安全、后续可以做限流和内容过滤，也是我比较推荐的做法。第三种是用微信云开发，云函数里放密钥，小程序端通过wx.cloud.callFunction调用，免运维、天然解决域名问题，适合个人项目或原型验证。
三种方式的取舍我用一张表说清楚：
| 接入方式 | 开发速度 | 密钥安全 | 上线门槛 | 适合场景 |
|---|---|---|---|---|
| 前端直连云端 API | 最快 | 差，key 容易泄露 | 需要域名备案与类目审核 | 本地联调、内部 demo |
| 自建服务端转发 | 中等 | 好，密钥在服务端 | 需要服务器与备案域名 | 正式上线、商用产品 |
| 微信云开发云函数 | 快 | 好，密钥在云函数 | 无需自己备案，审核同样要过类目 | 个人项目、初期验证 |
模板本身不绑定某一种，它把请求集中封装在一个文件里，你换接入方式时只动那一个文件，页面层完全不用改。这样设计的好处是：不管后端是chat/completions风格的 OpenAI 兼容接口，还是通义、文心、DeepSeek 各家封装，在模板里的接入成本基本一致。
2.2 消息数据模型：role、content 与 sessionId 怎么设计
大模型对话接口接受的消息格式大同小异，核心就是角色和内容。模板的 messages 数组结构如下：
// 一条标准消息结构 const message = { id: Date.now(), // 前端本地主键，用于列表渲染和滚动定位 role: 'user', // 'user' 用户消息 / 'assistant' AI 回复 / 'system' 系统设定 content: '你好，介绍一下你自己', // 文本内容 ts: Date.now(), // 时间戳，用于排序与会话归档 status: 'done' // 'pending' 等待中 / 'done' 完成 / 'error' 失败 }; // 组装发给大模型的 payload const buildPayload = (historyMessages, currentInput) => { const history = historyMessages .filter(m => m.role !== 'system') // system 单独放 .map(m => ({ role: m.role, content: m.content })); return { model: 'qwen-turbo', // 按你实际用的模型改 messages: [ { role: 'system', content: '你是一个友好的中文助手，回答控制在 200 字以内。' }, ...history, { role: 'user', content: currentInput } ], temperature: 0.7, max_tokens: 800 }; };代码逻辑和参数说明：模板里用id而非直接复用数组下标，是因为后续要做消息删除和 scroll 定位时，靠唯一 id 才能稳定锚定。role字段严格对齐大模型接口的 role 体系，前端多用一份status区分“正在回复”和“已回复”，这是为了在界面上显示 loading 状态。temperature控制回答随机性，做客服类对话建议 0.3～0.5 之间，做创意文案可以调到 0.8 以上，max_tokens则根据你的回复长度需求调整，控制在 500～1000 之间比较平衡。
2.3 上下文窗口控制：不让会话越聊越贵
聊天类产品有个容易忽视的成本问题：每次请求都把全部历史消息发给模型，聊得越久，token 越多，响应越慢，费用越高。模板里建议内置一个滑动窗口截断机制，只保留最近 N 轮对话。
// 滑动窗口：最多保留最近 6 轮（12 条）对话 const clipContext = (messages, maxRounds = 6) => { const system = messages.filter(m => m.role === 'system'); const dialog = messages.filter(m => m.role !== 'system'); // 每轮对话由 user 和 assistant 两条组成，取最后 maxRounds*2 条 const clipped = dialog.slice(-maxRounds * 2); return [...system, ...clipped]; };参数说明：maxRounds设为 6 是一个经验值，既能保证多轮对话的连贯性，又不会让单次请求的 token 数量过大。如果你做的是深度咨询类场景，比如法律、医疗咨询，可以适当放宽到 10 轮；如果是闲聊或客服，4 轮就够了。调小这个值不会报错，但 AI 会很快“失忆”，聊到后面它不记得开头你说了什么。截断逻辑放在请求封装层之前，无论哪里调用发送函数都会自动生效。
这里还要注意一个细节：clipContext过滤的是role !== 'system'，也就是说系统提示词始终保留，不参与滑动窗口裁剪。因为 system 是控制回答风格和规则的关键，丢了它会直接影响输出质量。
3. 聊天页面结构与渲染逻辑：消息列表、输入框与滚动定位
聊天页面是小程序模板的核心，也是新手最容易翻车的地方。常见问题包括：消息多了以后 scroll-view 不自动滚到底部、输入框被键盘顶上去、连续发送时 UI 状态错乱。这一章讲清楚模板里这一套页面是怎么组织起来的。
3.1 模板的目录结构与页面职责
拆过的聊天类小程序模板，目录结构大同小异，这套模板的典型组织方式如下：
| 路径 | 职责 |
|---|---|
pages/chat/chat.wxml | 聊天页模板：消息列表 + 底部输入区 |
pages/chat/chat.js | 页面逻辑：消息管理、发送请求、滚动控制 |
pages/chat/chat.wxss | 样式：气泡、头像、输入栏布局 |
components/message-bubble/ | 消息气泡组件，区分用户和 AI 的展示样式 |
utils/request.js | 请求封装，统一处理超时和错误 |
config/api.js | 集中管理 baseUrl、模型名、API Key 占位 |
页面和数据层分离的好处是：以后你想加“重新生成”“复制回复”“删除某条消息”这些功能，只需在message-bubble组件上挂按钮事件，不用动整个页面结构。我建议你拿到模板后先不改样式，原样跑通一次对话，再逐步替换成自己的设计风格。
3.2 消息列表渲染与滚动定位
消息列表用scroll-view实现，这是小程序里最稳妥的滚动容器方案。核心 WXML 结构如下：
<view class="chat-page"> <scroll-view class="message-list" scroll-y scroll-into-view="{{scrollIntoView}}" scroll-with-animation > <block wx:for="{{messages}}" wx:key="id"> <view class="message-row {{item.role === 'user' ? 'user-row' : 'ai-row'}}" id="msg-{{item.id}}"> <view class="bubble {{item.role === 'user' ? 'user-bubble' : 'ai-bubble'}}"> <text>{{item.content}}</text> <text wx:if="{{item.status === 'pending'}}" class="typing-dot">正在输入…</text> </view> </view> </block> <!-- 底部锚点，用于滚动定位 --> <view id="msg-bottom" class="bottom-anchor"></view> </scroll-view> </view>逻辑说明：scroll-into-view绑定一个字符串，这个字符串必须和某条消息的id值完全对应，也就是msg-{{item.id}}。每次新增消息后，把滚动的目标设置为新消息的 id，scroll-view 就会自动平滑滚到那条消息的位置。我在自己项目里之前用scroll-top配合高度计算，总是出现滚动不到位的情况，换成scroll-into-view加底部锚点之后，问题一次解决。
对应的 JS 逻辑是往消息数组尾部追加新消息，同时更新scrollIntoView：
appendMessage(role, content, status = 'done') { const id = Date.now(); const msg = { id, role, content, status, ts: id }; this.setData({ [`messages[${this.data.messages.length}]`]: msg, // 用索引路径更新，避免全量 setData scrollIntoView: `msg-${id}` }); }参数说明：这里用setData的路径更新语法messages[{{length}}]，而不是this.setData({ messages: [...old, msg] })，是因为在小程序里，路径更新只会重渲染受影响的节点，性能明显更好，消息量大时不容易出现掉帧。我测过连续快速追加 30 条消息，路径更新的渲染耗时大约是整体更新的 1/3。status默认是done，发送请求前会把消息状态置为pending，这样界面上能显示“正在输入”的占位效果。这里想提醒的是，Date.now()在高频发送时可能撞上相同毫秒，稳妥做法是维护一个自增计数器组合进去，比如${Date.now()}_${counter++}。
3.3 输入区交互：发送、键盘与按钮状态
输入区由input和button组成，模板里处理了几个交互细节：键盘右下角显示“发送”按钮、发送时自动收起键盘、请求期间禁用发送按钮防止重复提交。
<view class="input-bar"> <input value="{{inputValue}}" bindinput="onInput" bindconfirm="onSend" confirm-type="send" adjust-position="{{true}}" placeholder="输入你的问题…" /> <button class="send-btn" bindtap="onSend" disabled="{{sending}}" loading="{{sending}}" >{{sending ? '回复中' : '发送'}}</button> </view>参数说明：confirm-type="send"让键盘右下角显示“发送”字样，用户按键盘发送键时会触发bindconfirm，和点击按钮走同一个onSend函数。adjust-position="{{true}}"是让键盘弹起时自动把页面顶上去，避免输入框被遮住。disabled和loading两个属性配合sending状态，请求进行中时按钮置灰并显示 loading，从交互上杜绝连点导致的重复请求。有些安卓机上键盘顶起后页面回弹不到位，可以在 onSend 里主动调用wx.hideKeyboard()强制收起，这个问题我在第五章节会展开讲。
4. 小程序端逻辑层：请求封装、状态管理与错误兜底
页面结构只是骨架，真正让模板能跑起来的是逻辑层。这一章讲请求封装怎么写、流式输出在小程序里怎么落地、以及失败时界面如何兜底。
4.1 请求封装：把 wx.request 包成可复用的 Promise
小程序原生wx.request是回调式写法，用起来比较啰嗦，也不方便在多个页面复用。模板的utils/request.js把它封装成 Promise，统一处理超时、状态码和业务错误码：
const request = (options) => { return new Promise((resolve, reject) => { wx.request({ url: options.url, method: options.method || 'POST', data: options.data || {}, timeout: options.timeout || 15000, // 默认 15 秒超时 header: { 'Content-Type': 'application/json', ...(options.header || {}) }, success(res) { // 约定 statusCode 200 + 业务 code 0 为成功 if (res.statusCode === 200 && res.data && res.data.code === 0) { resolve(res.data); } else { // 区分 HTTP 错误和业务错误，方便上层做不同提示 reject({ type: 'biz', statusCode: res.statusCode, message: (res.data && res.data.message) || '服务端返回异常' }); } }, fail(err) { // 网络不通、超时、域名未配置都会走这里 reject({ type: 'network', message: '网络异常，请检查网络后重试' }); } }); }); }; module.exports = request;代码逻辑说明：封装层做了三件事。第一是统一超时，timeout默认 15 秒，大模型接口通常比普通接口慢，如果用的是比较重的模型，建议调到 30 秒甚至 60 秒，超时后fail回调会触发，上层会收到network类型的错误。第二是状态码分流，HTTP 200 但业务 code 非 0 时归为业务错误，比如后端限流、上下文超长；HTTP 非 200 或网络层失败归为网络错误，这样 UI 层可以根据error.type显示不同提示文案。第三是方便全局拦截，以后要加 token 鉴权、日志上报，只需在这个文件里加逻辑。
联调时有个小技巧：后端如果已经接入大模型但还没定义统一的code字段，你可以临时在封装层放开限制，改用res.data.reply是否存在来判断成功。上线前再合入严格校验，这样不会阻塞前后端并行开发。
4.2 流式输出在小程序里的现实做法
很多人在网页端习惯了打字机效果的流式输出，到了小程序也想照搬。真实的限制是：wx.request不支持像浏览器fetch那样读取流式响应，你拿到的是完整响应体，所以微信小程序里做真正的逐字输出，一般有三条路。
第一条是 WebSocket 通道：后端和前端建立一个长连接，大模型生成一段就推送一段，前端收到后追加渲染。体验最接近网页端，但复杂度最高，后端要做 WebSocket 服务，小程序端要处理断线重连、消息时序、心跳保活。第二条是轮询任务状态：发请求后立即返回一个taskId，前端每隔 1～2 秒轮询一次结果接口，拿到完整结果后一次性渲染。实现简单，但延迟明显，适合回答速度快的轻量模型。第三条是放弃流式，请求完成后一次性渲染。模板默认走这条路径，理由是稳定、好调试、不依赖额外服务。
我的建议是：MVP 阶段用第三种方案，先把产品逻辑跑通；等用户量起来、对话体验成为核心卖点时，再切换到 WebSocket 方案。模板的架构里消息渲染和请求层是解耦的，以后换 WebSocket 只需把appendMessage的调用时机从“拿到完整响应”改成“每收到一个分片调用一次”，页面本身不用动。
4.3 错误兜底与发送状态机
聊天页和普通表单页不一样，用户连续快速发送消息时，状态管理稍不注意就会出 bug。模板里用sending这个单一状态控制整个发送流程，完整的发送函数如下：
async onSend() { const text = this.data.inputValue.trim(); if (!text || this.data.sending) return; // 空消息或正在发送时直接丢弃 this.setData({ inputValue: '', sending: true }); const pendingId = this.appendMessage('user', text, 'done'); try { const payload = buildPayload(clipContext(this.data.messages.slice(0, -1)), text); const data = await request({ url: `${config.baseUrl}/v1/chat/completions`, data: payload }); this.appendMessage('assistant', data.reply || data.choices[0].message.content, 'done'); } catch (err) { // 失败时给用户一个可感知的反馈，并保留输入内容方便重试 wx.showToast({ title: err.message || '请求失败', icon: 'none' }); this.appendMessage('assistant', `请求失败：${err.message}，请稍后重试。`, 'error'); } finally { this.setData({ sending: false }); } }参数和行为说明：调用buildPayload(clipContext(...))时，先把刚追加的用户消息从this.data.messages末尾去掉，再用clipContext裁剪历史，最后拼上当前输入，这样不会把同一句话发送两次。error状态的消息在 UI 上可以用灰色气泡展示，配合一个“重试”按钮让用户一键重新发送。这里我吃过一次亏：最初失败时不往消息列表里插错误提示，只弹 toast，结果用户在弱网环境下以为自己发了消息但 AI 没理他，体验很懵。现在无论成功失败都会在列表里留下一条记录，用户能清楚看到“这条消息到底有没有发出去”。
5. 真机、审核与接口安全：上线前的一页避坑记录
这一章写给准备把模板往线上推的人。开发和调试阶段一切正常，一到真机预览、提审、上线就出各种问题。以下是我拆过多个同类型项目后整理的五条高频踩坑记录，按“现象 → 原因 → 解决”写。
5.1 合法域名校验：开发者工具正常，真机必挂
现象：在微信开发者工具里请求一切正常，AI 回复流畅。扫码真机预览，所有请求全部失败，报错信息是url not in domain list。
原因：开发者工具默认勾选了“不校验合法域名”，真机上这个校验强制生效。小程序后台要求所有wx.request的 URL 必须在小程序管理后台配置为业务域名，而且要求 HTTPS、ICP 备案。
解决：开发阶段，在开发者工具右上角“详情 → 本地设置”里勾选“不校验合法域名…”，可以继续联调。上线前，把你的 API 域名（自建服务端的域名，或云开发环境默认域名）加到小程序后台“开发管理 → 开发设置 → 服务器域名”的 request 合法域名列表里。注意：域名的 HTTPS 证书必须有效，不能用自签名证书。如果是直连海外模型 API，大概率过不了备案这关，这也是我坚持推荐自建服务端或云开发的原因。
5.2 scroll-view 滚动失灵：scroll-top 换成 scroll-into-view
现象：消息超过一屏后，新消息没有自动滚到底部，列表停在原位置。偶尔滚动动画抖动，在 iOS 上尤其明显。
原因：用scroll-top配合固定数值去滚动，在不同机型、不同字体大小下，内容高度不一致，数值算不准。另一个原因是setData是异步的，数据还没渲染完就滚动，自然滚不到正确位置。
解决：改用第 3 章写的scroll-into-view方案，给每条消息一个唯一 id 作为锚点，新增消息后把scrollIntoView设成新消息的 id。如果滚动还是失败，把滚动触发放到setData回调里执行，确保渲染完成后再动，代码会用this.setData({...}, () => { this.setData({ scrollIntoView: \msg-${id}` }) })`。这个是微信小程序里最稳的滚动定位方式，没有之一。
5.3 连续发送导致回复乱序：请求要串行化
现象：用户快速连发两条消息“你好”“帮我写个请假条”，第一条 AI 还在回复，第二条已经发出去。最后界面上先显示了第二条的回复，再显示第一条的回复，对话顺序完全错乱。
原因：模板初版没有对请求做串行限制，两个并发请求各自独立，返回顺序不可控，谁先回来谁先渲染。
解决：把sending状态从“按钮禁用”升级为“整个发送流程互斥”。第二段代码里已经实现：if (!text || this.data.sending) return;，在sending为 true 期间，所有新的发送请求直接丢弃。同时界面上把输入框置灰或提示“正在回复中，请稍候”。如果产品上需要支持并发提问，那就要在数据层给每条消息关联对应的请求 id，返回后按请求 id 追加到对应位置，这属于高阶需求，MVP 阶段不建议做。
5.4 上下文无限增长：token 超限和费用失控
现象：用户连续聊了 20 轮后，某次请求开始报 400 错误，提示 tokens 超限。再看后台账单，费用比刚开始涨了十几倍。
原因：没有做上下文截断，每次请求都把全部历史消息发给大模型。按每轮 200 token 估算，20 轮就有 8000 token 的输入消耗，按现在的模型定价，积累到一定量后费用非常可观。
解决：用第 2 章的clipContext做滑动窗口截断，同时在前端 localStorage 里限制会话存储条数。我一般会在模板里再加一道保护：发送前检查messages长度，超过 50 条时自动弹出提示“本次会话过长，已自动开启新会话”，并一键清空。这道保护不是影响体验的坏设计，对用户来说是“AI 失忆”的明确信号，总比悄悄截断让用户察觉 AI 不记得前面说过什么要好。
5.5 AI 对话类目审核：模板能跑只是第一步
现象：代码没问题、接口正常、体验完整，提交微信审核后被驳回，理由涉及“人工智能问答服务”类目或需要额外资质。
原因：微信对涉及 AI 对话能力的小程序有类目要求，普通个人主体在很多情况下没有这类目权限，需要企业主体，并可能需要提供相应资质或完成备案。
解决：提审前先在小程序后台“设置 → 服务类目”里确认自己的类目是否覆盖 AI 问答场景。如果你的主体不符合要求，有两个务实方案：一是把产品定位调整为“客服工具”或“信息查询工具”，弱化“AI 对话”标签，但这需要产品和交互上做配合，不是换个名字就能过审；二是用企业主体注册，走正规资质流程。这类目政策属于动态调整的，提审前先去微信官方文档确认最新要求，别等被驳回了再改。
6. 从模板到可运营产品：提示词工程、历史会话与回归验证
模板跑通只是第一步。把它做成能日活的产品，需要再补三个能力：角色化提示词、会话持久化、以及改完每次都能确认没改坏东西的验证思路。
6.1 用提示词注入固定角色
把提示词从硬编码抽出来，放到配置文件里维护：
// config/prompt.js module.exports = { customerService: '你是某品牌的客服助手，回答简洁礼貌，用中文，字数不超过150字。', teacher: '你是一名编程老师，用循序渐进的方式讲解，适当给出代码示例。', copywriter: '你是资深文案，输出小红书风格短文案，带 emoji，不超过100字。' }; // 发送时按业务场景注入 const systemPrompt = config.prompt.customerService; const payload = { messages: [{ role: 'system', content: systemPrompt }, ...clipped] };6.2 历史会话持久化与一键清空
小程序冷启动后 messages 数据会丢失，用缓存把会话续上：
const HISTORY_KEY = 'chat_history_v1'; saveHistory(messages) { wx.setStorageSync(HISTORY_KEY, messages.slice(-50)); // 最多存50条 } loadHistory() { return wx.getStorageSync(HISTORY_KEY) || []; } clearHistory() { wx.removeStorageSync(HISTORY_KEY); this.setData({ messages: [], scrollIntoView: '' }); }6.3 改完模板后的强制回归动作
这个模板我改过不少次，每一次改完都会跑一遍三件套：真机预览、快速连发三条消息、清空后重新开始会话。真机验证的是域名和键盘问题，快速连发验证的是串行逻辑，清空验证的是缓存边界。从那以后我养成了一个习惯，每次动完消息渲染或请求层的代码，都会强制把这三步走一遍才算改完。这个模板本身骨架是健康的，你把提示词、接口地址和样式替换成自己的，跑通这轮回归就能放心往外推。希望帮到你。
本文还有配套的精品资源，点击获取
