收藏备用！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 标签（比如 、），结果这些标签被过滤掉了。
根因：TinyVue 使用 @opentiny/utils 的 XSS 过滤功能，默认白名单比较严格，只允许最基本的 HTML 标签通过。
解决方案：通过 @opentiny/utils 的 xss.setXssOption 方法自定义白名单：
import { xss } from '@opentiny/utils'// 自定义 XSS 白名单
xss.setXssOption({
whiteList: {
b: [], // 允许 标签
i: [], // 允许 标签
a: ['href', 'title', 'target'], // 允许 并指定可用属性
img: ['src', 'alt', 'width', 'height'] // 允许 ![]()
并指定属性
}
})
注意：XSS 白名单配置应该只在确实需要富文本输入的场景下放宽，普通输入框保持严格过滤。安全永远比方便重要——就像你不会为了方便而在大门上不装锁。强烈建议： 只放你确实需要的标签和属性，不要把 script、iframe、on* 事件属性加入白名单。不然你的用户输入就能执行任意 Ja vaScript，那后果就不是“方便”而是“灾难”了。
坑6：多组件库混用命名冲突
项目同时使用了 TinyVue 和另一个组件库（比如 Element Plus），两者的 Modal、Message 等全局服务的 API 名冲突了——调用 Modal.alert() 不知道是哪个库的弹窗。
根因：多个组件库会在 Vue 的全局属性上注册各自的 API，如果命名相同就会冲突。就像两个保安都叫“小李”，你喊“小李开门”时，两个都跑来了，谁先开都不对。
解决方案：用 $TinyModalApiPrefix 自定义 TinyVue 的 API 前缀：
// 在应用入口配置
import { globalConfig } from '@opentiny/vue'globalConfig.$TinyModalApiPrefix = 'Tiny'
配置后，TinyVue 的全局 API 调用方式变为：
// 原来
this.$modal.alert('提示信息')// 配置前缀后
this.$TinyModal.alert('提示信息')
两个保安现在一个叫“小李”，一个叫“老李”——你喊“老李开门”，只有老李响应，不再混淆。
坑7：v-model 报错
在 Vue 3 项目中使用 TinyVue 组件的 v-model 时报错：
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
根因：某些场景下（尤其涉及自定义组件封装时），v-model 的双向绑定机制可能因为组件内部的事件声明方式而报错。Vue 3 的 v-model 本质上是 modelValue + update:modelValue 的语法糖。
解决方案：拆分 v-model 为独立的属性和事件：
<tiny-input v-model="value" />
<tiny-input
:model-value="value"
@update:model-value="value = $event"
/>
两者功能完全一样，只是拆分写法更明确。就像你写 a += 1 报了错，改写成 a = a + 1 就通过了——本质一样，形式不同。
坑8：空文件报错 "At least one template or script is required"
项目中间出现如下报错：
[Vue warn]: Failed to mount component: template or render function not defined.
At least one template or script is required
根因：你的项目中存在一个空的 .vue 文件——既没有 也没有