Vue 3 踩坑录：`.sync` 在 `setup()` 里失效？—— 一次搞懂 v-model 升级与替代方案
Vue 3 踩坑录：.sync在setup()里失效？—— 一次搞懂 v-model 升级与替代方案
一、问题现象
当你在 Vue 3 的<script setup>中写下：
<MyComp :title.sync="pageTitle" />控制台立刻弹出警告：
The
.syncmodifier is not supported in setup() function.
翻译：Vue 3 的setup语法糖里不再提供.sync，请使用新的v-model语法。
二、为什么.sync被移除？
- 语法冗余：
.sync本质是v-bind+ 自定义事件，易与v-model混淆。 - 统一模型：Vue 3 将所有双向绑定归并为
v-model，支持多个、自定义名称，更直观。 - setup 简化：
<script setup>编译时直接生成v-model调用，.sync不再被编译。
三、升级路线图（对照表）
| Vue 2 写法 | Vue 3 等价（setup） |
|---|---|
:title.sync="val" | v-model:title="val" |
@update:title="val = $event" | 自动由v-model触发 |
多个.sync | 多个v-model |
四、代码改造示例
1. 子组件：用defineEmits抛出事件
<!-- MyComp.vue --> <script setup> const props = defineProps({ title: String }) const emit = defineEmits(['update:title']) function onInput(e) { emit('update:title', e.target.value) } </script> <template> <input :value="title" @input="onInput" /> </template>2. 父组件：新语法v-model:title
<script setup> import { ref } from 'vue' const pageTitle = ref('Vue 3') </script> <template> <!-- ✅ 新语法 --> <MyComp v-model:title="pageTitle" /> <p>{{ pageTitle }}</p> </template>五、多个双向绑定（多v-model）
<!-- 子组件 --> defineEmits(['update:title', 'update:count']) <!-- 父组件 --> <MyComp v-model:title="pageTitle" v-model:count="pageCount" />六、兼容性方案（临时）
若必须保持.sync（老库迁移）：
- 使用选项式 API（无
<script setup>）； - 或通过custom directive手动实现
.sync行为（不推荐）。
七、一键检查清单
- 全部
:xxx.sync改为v-model:xxx - 子组件抛出
update:xxx事件 - 多个双向绑定用多
v-model - ESLint 规则
vue/no-deprecated-sync-modifier开启
八、一句话总结
.sync已成历史，v-model才是未来。
把:xxx.sync改成v-model:xxx，一次性拥抱 Vue 3 统一、简洁的双向绑定模型！
最后问候亲爱的朋友们，并邀请你们阅读我的全新著作
📚 《Vue.js 3企业级项目开发实战（微课视频版》