首页 > 网页制作 >新手必看玩转TinyRobot避坑指南

新手必看玩转TinyRobot避坑指南

来源：互联网 2026-06-14 08:22:02

TinyRobot常见坑包括忘记引入样式导致排版混乱、组件名需加Tr前缀、全局与按需引入不可混用、Node.js需≥20.13.0、必须用ThemeProvider包裹启用主题、useMessage需在setup中调用、v0.3.x升级v0.4.0需用SenderCompat过渡、SSE流需用sseStreamToGenerator转换、推荐按需引入以利用T

坑 1：忘记引入样式——组件能渲染但外观丑陋

症状： 页面上能看到 tr-bubble、tr-sender 的结构，但排版混乱，背景色、圆角、间距全部丢失，如同裸奔的 HTML。

原因： TinyRobot 的组件逻辑和样式是分离打包的。您只引入了 JS，未引入 CSS，组件虽然注册成功，但所有 --tr-* CSS 变量和样式规则均未加载。

长期稳定更新的攒劲资源： >>>点此立即查看<<<

修复： 在 main.ts 中加上样式导入，这一步不管是按需引入还是全局引入都不能省略：

import { createApp } from 'vue'
import App from './App.vue'
import '@opentiny/tiny-robot/dist/style.css' // 必须引入！const app = createApp(App)
app.mount('#app')

坑 2：组件名写错——用 Bubble 而不是 TrBubble

症状： 模板里写了或，Vue 提示组件未注册，页面空白。

原因： TinyRobot 所有组件都以 Tr 前缀注册（TinyRobot 缩写）。按需引入时导入名是 TrBubble、TrSender，模板里对应的标签是、，不是。

修复：

完整对应关系：TrBubble → ，TrSender → ，TrContainer → ，ThemeProvider → （注意 ThemeProvider 没有 Tr 前缀）。

坑 3：全局引入和按需引入混用——组件重复注册

症状： 控制台出现 Vue 组件重复注册警告，某些组件行为异常，或打包体积明显偏大。

原因： 您在 main.ts 里用 app.use(TinyRobot) 全局注册了所有组件，然后在页面里又 import { TrBubble } from '@opentiny/tiny-robot' 按需引入，两套注册冲突。

修复： 选择一种方式，不要混用：

// 方案 A：纯全局引入（适合快速原型）
import TinyRobot from '@opentiny/tiny-robot'
import '@opentiny/tiny-robot/dist/style.css'
app.use(TinyRobot) // 全局注册，页面里不用再 import// 方案 B：纯按需引入（推荐，体积更小）
// main.ts 只引样式，不 app.use
import '@opentiny/tiny-robot/dist/style.css'
// 页面里按需 import
import { TrBubble, TrSender } from '@opentiny/tiny-robot'

坑 4：Node.js 版本过低——构建悄无声息地失败

症状： pnpm install 或 pnpm build 报一堆奇怪错误，如 ERR_MODULE_NOT_FOUND、语法解析失败，或依赖安装成功但运行时白屏。

原因： TinyRobot 依赖较新 JavaScript 特性（如 using 声明、Symbol.asyncDispose 等），要求 Node.js >= 20.13.0。若使用 Node 16 或 18，构建工具在解析阶段就会出错，且错误信息往往不直观。

修复：

# 检查当前版本
node -v# 如果低于 20.13.0，升级 Node
# 推荐用 nvm 管理版本
nvm install 20
nvm use 20

坑 5：没用 ThemeProvider 包裹——主题切换永远不生效

症状： 调了 setColorMode('dark')，页面毫无变化，CSS 变量值始终是亮色模式。

原因： TinyRobot 主题系统基于 ThemeProvider 组件注入，它会在目标元素上添加 data-tr-theme 和 data-tr-color-mode 属性。若应用未被 ThemeProvider 包裹，useTheme() 返回 false，主题切换自然无效。

修复：

坑 6：useMessage 用在了错误的作用域

症状： sendMessage 调用后无响应，messages 不更新，或报 Cannot read properties of undefined 等错误。

原因： useMessage 本身不依赖 ThemeProvider，但常见错误在于在 setup 之外调用（如普通函数或 setTimeout 里），导致响应式上下文丢失。另一个常见问题是把 useMessage 返回值当普通对象解构，丢失响应性。

修复：

坑 7：v0.3.x 代码直接搬到 v0.4.0——大面积报错

症状： 从 v0.3.x 升级到 v0.4.0 后，项目编译报错：client 不存在、AIClient 已废弃、Sender 的 allowSpeech/buttonGroup 等属性消失、事件名变更。

原因： v0.4.0 是一次重大升级（Breaking Changes），核心变更包括：

useMessage 的 client 参数改为 responseProvider
AIClient 标记为废弃，需用 useMessage + responseProvider 代替
Sender 组件整体重构，allowSpeech、buttonGroup、theme、suggestions 等旧 props 全部移除
多个旧事件名被替换

修复（快速迁移方案）： 使用 SenderCompat 做过渡：

//  v0.3.x 旧代码
import { TrSender } from '@opentiny/tiny-robot'//  快速迁移：改一行导入即可
import { TrSenderCompat as TrSender } from '@opentiny/tiny-robot'

SenderCompat 保留了 v0.3.x 大部分 API，只需处理 5 个破坏性变更（紧凑模式用 size="small" 代替 class、插槽名变更等）。详细迁移步骤参考官方文档。

修复（useMessage 迁移）：

//  v0.3.x：使用 client
const { messages } = useMessage({
  client: new AIClient({ ... }),
})//  v0.4.0：使用 responseProvider
const { messages } = useMessage({
  responseProvider: async (requestBody, abortSignal) => {
    const response = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(requestBody),
      signal: abortSignal,
    })
    return sseStreamToGenerator(response)
  },
})

坑 8：SSE 流处理不对——responseProvider 没用 sseStreamToGenerator

症状： AI 对话发送后，消息列表只出现一条空的 assistant 消息，内容始终不更新；或者后端返回了数据但前端只显示最后一个 chunk。

原因： responseProvider 的返回值决定响应模式。返回 Promise 时为一次性结果；返回 AsyncGenerator 时才能逐块消费、增量合并。若将 SSE 流的 Response 直接当作 Promise 返回，useMessage 无法逐块处理。

修复： 使用 sseStreamToGenerator 将 fetch Response 转换为 AsyncGenerator：

import { sseStreamToGenerator } from '@opentiny/tiny-robot-kit'const { messages, sendMessage } = useMessage({
  responseProvider: async (requestBody, abortSignal) => {
    const response = await fetch('/api/chat/completions', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(requestBody),
      signal: abortSignal,
    })    //  关键：用 sseStreamToGenerator 转换 SSE 流
    return sseStreamToGenerator(response, { signal: abortSignal })
  },
})

坑 9：无视 Tree Shaking——全局引入导致 bundle 臃肿

症状： 打包后产物体积异常大，首屏加载慢，Lighthouse 性能分数低。

原因： 使用了全局引入 app.use(TinyRobot)，所有组件（包括 Bubble、Sender、Container、History、McpServerPicker 等十几个组件）被全量打包，哪怕仅用了 TrBubble 和 TrSender。

修复： 只引入所需组件：

// main.ts 只引样式，不 app.use
import '@opentiny/tiny-robot/dist/style.css'

这样 Vite/Rollup 的 Tree Shaking 会自动剔除未使用的组件，bundle 体积可缩减 60% 以上。

坑 10：事件名搞错——submit 还是 onSubmit？

症状： 在模板里写了 @onSubmit 或 @on-send，发送消息后回调完全不触发。调试半天，代码逻辑没问题，就是事件无响应。

原因： Vue 3 组件事件名有明确规范：模板中用 @submit（kebab-case 也行 @submit），不是 @onSubmit。TinyRobot 的 Sender 组件事件名是 submit、clear、cancel、focus、blur、input，不带 on 前缀。

修复：

其他常见易混淆事件：

你可能写的	正确事件名	说明
`@onSubmit`	`@submit`	Sender 提交事件
`@onCancel`	`@cancel`	Sender 取消事件（v0.4 新增）
`@onFilesSelected`	`@select`（UploadButton）	v0.4 改了，不在 Sender 上了
`@onSpeechEnd`	`@speech-end`（VoiceButton）	v0.4 移到 VoiceButton 组件
`@onChange`	`@blur` 或 `@input`	v0.4 移除了 change 事件

总结速查表

坑	一句话记忆
1	样式必引：`@opentiny/tiny-robot/dist/style.css` 不能忘
2	Tr 前缀：组件名是 `TrBubble`，标签是
3	别混用：全局引入和按需引入选一个
4	Node >= 20.13.0：低版本构建失败，报错还不直观
5	ThemeProvider 包裹：主题切换的前提条件
6	setup 中调用：useMessage 别跑到异步回调里
7	SenderCompat 过渡：v0.3.x 升级 v0.4 的快速通道
8	sseStreamToGenerator：SSE 流必须转 AsyncGenerator
9	按需引入优先：Tree Shaking 是你的好朋友
10	不带 on 前缀：事件名是 `submit` 不是 `onSubmit`