Vue 3.5+持续迭代踩坑记：那些让我熬夜的问题

我们的项目从Vue 3.0升级到3.5已经有大半年了。

升级的时候做了充分的测试，觉得没问题就上线了。上线之后也一切正常，性能还有所提升。但随着项目持续迭代，新功能不断增加，我们遇到了各种各样的问题，有些问题让我熬了好几个通宵才解决。

这篇文章，我想分享一下在Vue 3.5+项目持续迭代过程中遇到的那些坑。从响应式系统、构建工具到性能优化，详细记录每个问题的现象、原因和解决方案，给前端开发者一个真实的参考。

问题一：响应式数据丢失

第一个让我熬夜的问题是响应式数据丢失。

现象是这样的：我们有一个比较复杂的表单，用户填写之后，偶尔会出现数据丢失的情况。就是用户填了一半，切换一下标签页，再切回来，表单里的数据就没了。这个问题是偶发的，很难复现，用户反馈了好几次我们都没找到原因。

后来我花了整整一个周末，加了很多日志，终于复现了这个问题。原因是我们在组件里用了reactive来定义表单数据，然后在某个地方用了解构赋值，把reactive对象解构了。解构之后，数据就失去了响应式，而且在某些情况下会被重置。

比如这样的代码：

const form = reactive({ name: '', email: '' })
const { name, email } = form

这样解构之后，name和email就不是响应式的了。如果你修改name，form里的name不会变。而且在组件重新渲染的时候，解构出来的变量可能会被重置。

解决方案是用toRefs来解构：

const form = reactive({ name: '', email: '' })
const { name, email } = toRefs(form)

这样解构出来的name和email依然是响应式的，修改它们会同步到form里。

这个问题虽然解决了，但给了我一个深刻的教训：在Vue 3里，reactive对象不要随便解构，解构的时候一定要用toRefs或者toRef。这个坑很多人都踩过，包括我。

问题二：watch深度监听的性能问题

第二个问题是watch深度监听导致的性能问题。

我们有一个比较大的列表页面，列表里有很多复杂的对象。为了监听列表的变化，我们用了watch的deep模式：

watch(list, () => {
  // 做一些处理
}, { deep: true })

刚开始列表数据少的时候没问题，但后来数据越来越多，页面就开始卡顿了。特别是在数据更新的时候，页面会有明显的延迟，用户体验很差。

我查了很久，终于发现是deep watch的问题。deep模式下，Vue会递归遍历整个对象，监听每一个属性的变化。当对象很大、嵌套很深的时候，这个遍历的开销非常大，会严重影响性能。

解决方案是尽量避免用deep watch，而是监听具体的属性。比如如果你只关心列表的长度，就只监听list.length。如果你关心某个具体的字段，就只监听那个字段。

如果确实需要深度监听，可以考虑用shallowRef或者shallowReactive来减少监听的深度。或者用computed来派生需要的数据，然后监听computed的值。

比如：

const listLength = computed(() => list.length)
watch(listLength, () => {
  // 做一些处理
})

这样就只监听列表长度的变化，不会递归遍历整个列表，性能会好很多。

这个问题让我意识到，Vue的响应式系统虽然强大，但也不是免费的。在处理大数据的时候，一定要注意性能，避免不必要的深度监听。

问题三：v-for和v-if同时使用

第三个问题是v-for和v-if同时使用导致的bug。

我们有一个列表，需要根据条件过滤显示某些项。最开始我是这样写的：

<div v-for="item in list" v-if="item.visible" :key="item.id">
  {{ item.name }}
</div>

这样写在Vue 2里是可以的，但在Vue 3里，v-if的优先级比v-for高，所以会先判断v-if，这时候item还没有定义，就会报错。

而且，即使不报错，这样写的性能也不好，因为v-for会遍历所有项，然后再用v-if过滤，浪费了很多渲染。

正确的做法是用computed先过滤列表，然后再v-for：

const visibleList = computed(() => list.filter(item => item.visible))

<div v-for="item in visibleList" :key="item.id">
  {{ item.name }}
</div>

这样既避免了v-for和v-if同时使用的问题，又提高了性能，因为过滤是在JavaScript层面做的，不需要渲染不需要的项。

这个问题虽然基础，但在项目迭代过程中，很多人图省事就直接v-for和v-if一起写了，结果就出问题了。在代码审查的时候，一定要注意这个问题。

问题四：组件异步加载的闪烁问题

第四个问题是组件异步加载导致的闪烁问题。

为了优化首屏加载速度，我们把一些不常用的组件改成了异步加载，用defineAsyncComponent。但异步加载的组件，在加载完成之前会显示空白，加载完成之后突然出现，就会有闪烁的感觉，用户体验不好。

最开始我们用了Suspense组件来处理，但Suspense在Vue 3.5里还是实验性功能，而且和我们的路由系统有冲突，经常出问题。

后来我们改用了loading状态，在组件加载的时候显示一个骨架屏或者loading动画，加载完成之后再显示组件。这样就不会有闪烁了，用户体验好了很多。

具体做法是：

const AsyncComponent = defineAsyncComponent({
  loader: () => import('./AsyncComponent.vue'),
  loadingComponent: LoadingComponent,
  delay: 200
})

defineAsyncComponent支持配置loadingComponent，在加载的时候显示loading组件。delay参数是延迟显示loading的时间，如果组件在200ms内加载完成，就不显示loading，避免快速加载时的闪烁。

这个方案比Suspense稳定得多，而且配置简单，推荐大家使用。

问题五：Pinia状态持久化的坑

第五个问题是Pinia状态持久化的坑。

我们用Pinia来管理状态，并且用了pinia-plugin-persistedstate插件来持久化状态。这样用户刷新页面之后，状态还能保留。

但有一次，我们改了state的结构，加了一个新字段，结果老用户刷新页面之后就报错了。原因是持久化的数据还是旧的结构，没有新字段，代码里访问新字段的时候就报错了。

这个问题在开发环境很难发现，因为开发环境经常清缓存。但在生产环境，老用户的本地存储里还是旧数据，就会出问题。

解决方案是给持久化的状态做版本控制，或者在初始化的时候做兼容处理。比如：

const state = () => ({
  version: 2,
  newField: 'default value'
})

actions: {
  init() {
    if (this.version < 2) {
      this.newField = 'default value'
      this.version = 2
    }
  }
}

在应用启动的时候调用init方法，检查版本，如果是旧版本就做迁移。这样老用户的数据也能正常使用。

这个问题虽然不大，但很容易被忽略。在做状态持久化的时候，一定要考虑数据结构变化的兼容性。

问题六：Vite构建的内存溢出

第六个问题是Vite构建的时候内存溢出。

项目越来越大之后，我们用Vite构建生产版本的时候，经常会出现内存溢出的错误，构建失败。最开始我们以为是代码的问题，查了很久才发现是Node.js的默认内存不够用。

Vite在构建大型项目的时候，会消耗很多内存。Node.js默认的内存上限是1.5GB左右，对于大型项目来说可能不够。

解决方案是增加Node.js的内存上限：

node --max-old-space-size=4096 node_modules/vite/bin/vite.js build

或者在package.json里配置：

{
  "scripts": {
    "build": "node --max-old-space-size=4096 node_modules/vite/bin/vite.js build"
  }
}

把内存上限增加到4GB，构建就不会内存溢出了。

另外，还可以通过优化构建配置来减少内存消耗，比如用rollup的manualChunks来拆分代码，用terser来压缩代码，用visualizer来分析包体积。这些优化不仅能减少构建时的内存消耗，还能提升运行时的性能。

问题七：TypeScript类型推导失败

第七个问题是TypeScript类型推导失败。

Vue 3.5对TypeScript的支持更好了，但在某些复杂场景下，类型推导还是会失败。比如我们有一个复杂的泛型组件，props的类型推导经常出问题，导致编辑器里全是红色的波浪线。

最开始我们以为是代码的问题，改了很多次类型定义都没用。后来查了Vue的issue，发现这是Vue 3.5的一个已知问题，在某些复杂的泛型场景下类型推导会失败。

解决方案是显式声明类型，不要依赖自动推导。比如：

const props = defineProps<{
  list: Item[]
  visible: boolean
}>()

而不是用复杂的泛型和条件类型。虽然这样写起来稍微麻烦一点，但类型更清晰，也不会出现推导失败的问题。

另外，及时更新Vue和TypeScript的版本也很重要。Vue团队一直在改进类型推导，新版本往往会修复很多类型问题。

经验总结

踩了这么多坑，我总结了几条经验。

第一，升级版本之后不要掉以轻心。大版本升级的时候做了测试不代表就没问题了，随着项目迭代，新的问题会不断出现。要持续关注官方的issue和更新日志，及时了解已知问题和解决方案。

第二，基础问题要重视。很多坑都是基础问题，比如reactive解构、v-for和v-if同时使用。这些问题虽然基础，但在大型项目里很容易被忽略，而且一旦出现就很难排查。要在代码规范和代码审查里把这些问题卡住。

第三，性能问题要提前考虑。不要等项目大了、卡了才去优化，要在开发的时候就注意性能。比如避免不必要的深度监听，合理使用computed，异步加载组件，这些小细节加起来，对性能的影响很大。

第四，工具链要稳定。Vite、Pinia、TypeScript这些工具，虽然很好用，但也有各自的坑。要了解它们的原理和限制，遇到问题的时候才能快速定位和解决。

第五，文档和社区很重要。遇到问题的时候，先查官方文档，再查GitHub issue，很多问题别人已经遇到过并且解决了。不要自己闷头查，善用社区资源能节省很多时间。

写在最后

Vue 3.5是一个很好的版本，性能更强，功能更丰富，开发体验更好。但它不是完美的，在项目持续迭代的过程中，还是会遇到各种各样的问题。

这些问题虽然让我熬了很多夜，但也让我对Vue的理解更深了。每解决一个问题，都是一次成长。

如果你也在用Vue 3.5+，希望这篇文章能帮你避开一些坑。如果你也遇到过其他的坑，欢迎在评论区分享，大家一起学习进步。

最后用一句话来结束这篇文章："踩坑不可怕，可怕的是踩了坑不总结。"

愿每一个前端开发者，都能在踩坑中成长，写出更好的代码。