vue-select 迁移至 Vue 3 兼容库：在升级前先替换下拉组件

译注：本文编译自 dev.to 文章《Migrate vue-select to a Vue 3 compatible library》，作者 szwn，原文发布于 2026 年 10 月 7 日。原文链接见文末。

vue-select 的稳定版本（3.20.4）仅支持 Vue 2，其 Vue 3 版本自 2022 年 11 月起一直停留在 4.0.0-beta.6。如果这个组件正是阻碍你升级 Vue 3 的原因之一，你可以在升级之前先把它替换掉：趁项目还停留在 Vue 2.7 时完成替换，之后再升级 Vue，就无需再次改动下拉组件。

本文的迁移示例使用 Vue Pick，它在 Vue 2.7 和 Vue 3 上使用相同的 props 运行。

安装

npm install vue-pick

// main.js，替换原来的 "vue-select/dist/vue-select.css"
import "vue-pick/style.css"

import { VPick } from "vue-pick/vue2" // 在 Vue 2.7 阶段
import { VPick } from "vue-pick"      // 升级之后

当你迁移到 Vue 3 时，唯一需要改动的就是这行导入路径。

检查 v-model 中保存的内容

这一步如果跳过，很容易引发 bug。除非传入 reduce，否则 vue-select 会把整个选项对象放进 v-model。

如果你使用了 reduce，需要用 value-key 指定字段名：

<!-- 之前 -->
<v-select v-model="countryId" :options="countries" :reduce="(c) => c.id" />

<!-- 之后 -->
<v-pick v-model="countryId" :options="countries" value-key="id" searchable clearable />

如果没有使用 reduce，则添加 value-format="object"，让数据结构保持一致：

<v-pick v-model="country" :options="countries" value-key="id" value-format="object" searchable clearable />

重新开启搜索与清除功能

vue-select 默认支持搜索和清除，而 Vue Pick 默认不支持，因此上面两个示例都加上了 searchable clearable。

在 multiple 模式下，Vue Pick 每次选择后仍会保持展开。如果你想要旧版行为，可以添加 :close-on-select="true"。

像 ["Apple", "Banana"] 这样的纯字符串选项需要先转换为对象：

const options = fruits.map((f) => ({ label: f, value: f }))

v-model 中仍然保存纯字符串。

借助 AI 代理完成大部分迁移

完整的 prop、事件与插槽映射见 vue-select 迁移指南。该页面还提供了一段可直接粘贴到 Claude Code、Cursor 或 Copilot 的提示词。它会让代理参考指南的纯文本副本，并在没有匹配项的地方留下 TODO，而不是凭空猜测。

如果你把 vue-select 封装在自己的组件中，请先迁移这个封装组件，所有使用它的页面会一次性完成迁移。

原文链接

https://dev.to/szwn/migrate-vue-select-to-a-vue-3-compatible-library-3m4c