TinyVue开发常见踩坑问题合集

收藏备用！TinyVue 开发高频踩坑问题合集

每个程序员的心里都有一本“踩坑日记”——那些深夜加班到凌晨三点，对着屏幕骂组件库的日子。但冷静下来想想，坑不是组件库故意挖的，而是你和它之间的“沟通障碍”。

今天我把 TinyVue 开发中最高频的踩坑问题整理成合集，方便大家随时查阅。收藏这篇，下次踩坑时先翻翻，说不定省你3小时调试时间。

坑1：无界微前端弹出元素错位

先说说场景：你用无界（wujie）微前端框架加载了 TinyVue 的子应用，结果弹出层（Modal、Tooltip、Dropdown）的位置跑到了屏幕外，或者偏移了好几百像素。

问题出在哪儿？无界微前端会在子应用和主应用之间创造一个 iframe 边界。TinyVue 的弹出组件默认把浮层挂载到当前 window 的 document.body 上——在微前端场景下，这个 body 是 iframe 的 body，而不是主应用的 body。弹出层的位置计算用了 iframe 的坐标系，但渲染却在 iframe 里，视觉上看起来就“漂移”了。

解决办法很简单：

// 在子应用入口配置 viewportWindow
import { globalConfig } from '@opentiny/vue'globalConfig.viewportWindow = window.parent

这行代码告诉 TinyVue：“你在 iframe 里干活，但坐标参照系要用主应用的 window。”这样弹出层的位置计算就会基于主应用的视口，不再漂移。原理就像你在小房间里做投影——投影源在小房间，但投影的目标是大厅的屏幕。你得告诉投影仪“你的目标屏幕在大厅”，不然它会对着小房间的墙壁投影。

坑2：Vitepress 打包报错 ERR_UNSUPPORTED_DIR_IMPORT

在 Vitepress 文档项目中用了 TinyVue 组件，开发时一切正常，但 npm run build 打包时突然报错：

Error: ERR_UNSUPPORTED_DIR_IMPORT
Importing a directory is not supported for ES modules

根因在于 Vitepress 在打包时会尝试将所有依赖 SSR 化（服务端渲染）。TinyVue 的某些内部模块用了目录导入（import from './some-dir'），这在 ESM 规范下是不允许的——必须明确指定文件路径。

解决方案：

// vite.config.js 或 .vitepress/config.js
export default {
  vite: {
    ssr: {
      noExternal: [/@opentiny//]
    }
  }
}

ssr.noExternal 的意思是：不要把这些包当作外部依赖排除，要把它们打包进来。 这样 TinyVue 的目录导入会在打包阶段被 Vite 正确处理，不会触发 ESM 规范报错。如果只写 noExternal: ['@opentiny/vue'] 可能不够——因为 TinyVue 内部有很多子包（@opentiny/vue-renderless、@opentiny/vue-common 等），用正则 /@opentiny// 一网打尽更稳妥。

坑3：change-compat 属性——代码改值了，事件没触发？

你在代码里修改了一个响应式变量的值，期望触发组件的 change 事件做后续处理，结果事件压根没触发。

const formData = reactive({ name: '' })// 在代码中修改值
formData.name = '新名字'
// 期望触发  的 change 事件，但没触发！

问题出在 TinyVue 组件的 change 事件默认只在用户交互时触发（比如用户手动输入、点击选择）。通过代码修改响应式变量属于“程序性行为”，不会触发 change 事件。这是出于性能和逻辑清晰度的考虑——避免代码改值触发连锁反应。

解决方法是给组件添加 change-compat 属性：

<tiny-input
  v-model="formData.name"
  :change-compat="true"
  @change="handleChange"
>tiny-input>

设为 true 后，代码修改值也会触发 change 事件。但要注意——这可能导致不必要的连锁事件触发，只在确实需要的场景下开启。就像你家装了感应灯——人走过自动亮是合理的（用户交互触发），但如果你远程开灯也触发“有人入侵”的警报（代码修改触发），那就是过度反应了。change-compat 就是那个“远程操作也触发警报”的开关——慎用。

坑4：Webpack 富文本依赖无法解析

用了 TinyVue 的富文本编辑器组件，Webpack 打包时报错找不到 quill 相关依赖。

根因：TinyVue 的富文本编辑器基于 Quill.js，而 @opentiny/fluent-editor 包内的 quill 依赖是 ES Module 格式。Webpack 默认不会对 node_modules 中的包做转译（babel-loader 默认 exclude node_modules），导致 ES Module 语法在旧版 Webpack 中无法被解析。

解决方案：

// vue.config.js 或 webpack.config.js
module.exports = {
  transpileDependencies: ['@opentiny/fluent-editor', 'quill']
}

transpileDependencies 让 Webpack 对指定的 node_modules 包也进行 babel 转译，把 ES Module 语法转换成 Webpack 能理解的形式。Vue CLI 项目在 vue.config.js 中直接配置 transpileDependencies；纯 Webpack 项目需要手动在 babel-loader 配置中调整 exclude 规则。这就像你的翻译软件不支持某国语言——不是那国语言有问题，是你的翻译软件需要升级一下语言包。

坑5：XSS 白名单配置

TinyVue 内置了 XSS 过滤，但你需要在某些输入框中允许特定 HTML 标签（比如 、），结果这些标签被过滤掉了。

import { xss } from '@opentiny/utils'// 自定义 XSS 白名单
xss.setXssOption({
  whiteList: {
    b: [],       // 允许  标签
    i: [],       // 允许  标签
    a: ['href', 'title', 'target'], // 允许  并指定可用属性
    img: ['src', 'alt', 'width', 'height'] // 允许  并指定属性
  }
})

// 在应用入口配置
import { globalConfig } from '@opentiny/vue'globalConfig.$TinyModalApiPrefix = 'Tiny'

// 原来
this.$modal.alert('提示信息')// 配置前缀后
this.$TinyModal.alert('提示信息')

v-model cannot be used on this component because it has multiple v-model bindings

Component emitted event "update:modelValue" but it is not declared

<tiny-input v-model="value" />
<tiny-input
  :model-value="value"
  @update:model-value="value = $event"
/>

[Vue warn]: Failed to mount component: template or render function not defined.
At least one template or script is required