Vue2 到 Vue3 Element Plus 迁移手册

要解决的迁移痛点

Vue 2 + Element UI 项目向 Vue 3 + Vite + Element Plus 迁移时，会遇到三类典型问题：编译期直接崩溃（如模板中的 this. 导致白屏、<style> 无 lang 时使用 // 注释、Vite/ESM 环境下 require() 未定义）、运行时行为不一致（如 slot-scope 废弃、.sync 修饰符移除、$listeners 和 $vnode 不存在、el-dialog 受控约定变化导致弹框关不掉、el-date-picker 的 value-format 大小写敏感）、API 语义变更（如 el-table 选区改用 getSelectionRows()、el-select 包装组件传参 bug、size="mini" 改为 small、this.$set 移除）。这些问题散落在模板、脚本、样式和第三方组件中，靠人工逐个排查容易遗漏。

技能的核心能力

本手册提供自包含、可独立分享的迁移方案，核心流程分三步：

1. 全量扫描建立清单：在 src/ 根目录执行一组 grep 命令，定位所有命中文件，包括 slot-scope、this.、// 注释、require(、.sync、$listeners、$vnode、mini 等关键词。注意 kebab-case 标签与 PascalCase 导入名不会同时命中，需补充扫描 OrganizationSelect|EmpSelect|ProductSupplierSelect 等包装组件，避免漏掉死 import。
2. 按优先级分批修复：先修会崩/白屏的硬伤（P1-P7、P15），再修组件 API 与数据绑定（P8-P14、P16-P23）。例如 slot-scope 改为 v-slot、.sync 改为 v-model:prop、模板里的 this.xxx 直接写 xxx、require() 改为 import、el-date-picker 的 value-format 用大写 YYYY-MM-DD、自定义 el-select 包装组件替换为原生 el-select + 本地数据数组并删除死 import。
3. 验证清单逐项确认：每改完一批，用 Playwright 或浏览器打开关键页面，确认控制台零报错（无 ReferenceError: require is not defined、this.$vnode is undefined、slot-scope 编译错误）、弹框取消/提交能正常关闭、下拉框宽度不塌陷且传参正确、表格多选和日期选择回显与传参格式正确。

适用边界与注意点

本手册适用于从 Vue 2 + Element UI（webpack / Vue CLI）迁移到 Vue 3 + Vite + Element Plus 的项目，尤其适合排查迁移后运行时问题（白屏、弹框不关闭、下拉框宽度异常或传参错误、控制台报错）和对已迁移代码做坑点审计。不适用于 Vue 2 到 Vue 3 但未使用 Element UI/Plus 的场景，也不覆盖路由守卫、状态管理、CSS 预处理器升级等与 Element Plus 无关的迁移问题。

迁移时遵循三个原则：

• 先扫后改，分批进行：不要一次全改完再验证，每批改完抽几个页面本地 npm run dev 验证。
• 只处理明确点名的三类包装组件：不要改动项目里其它仍在用的 ElementSelect 包装组件（Team / ProductionLine / Machine / Company 等）。
• 文档陈述必须以代码为准：合并文档时先用 grep 核实代码真实状态，尤其"已修复"类断言。