# LanERP Web Vue 3 + Vite 迁移方案

> 文档状态：评审稿
>
> 编写日期：2026-08-21
>
> 适用项目：`lanerp_web`
>
> 目标：在保持 PC、移动端、权限、公司切换、审批、工单、库存、地图、打印、微信和 Wujie 子应用功能的前提下，将当前 Vue 2 + Vue CLI 项目迁移到 Vue 3 + Vite。

## 1. 结论与总体策略

当前项目不适合直接把 Vue 2 全量改写成 Vue 3，也不适合同时更换 Vue、路由、状态管理、PC UI、移动端 UI 和所有业务组件。这样会同时改变编译器、运行时、组件 API、样式和业务行为，出现问题后无法判断来源。

推荐采用以下四个阶段：

```text
Vue 2.7 + Vue CLI
        |
        | 只替换构建工具，不改变业务运行时
        v
Vue 2.7 + Vite
        |
        | 使用 Vue 3 兼容构建，先迁移入口、路由和状态基础设施
        v
Vue 3 + @vue/compat + Vite
        |
        | 按业务域清理 Vue 2 语法，替换 Vue 2 专属依赖
        v
Vue 3 原生 + Vite
```

核心决策：

1. 第一阶段保留 Options API，不同时推进 Composition API。
2. 第一阶段保留 Vuex，先升级到 Vuex 4；Pinia 作为后续独立任务。
3. 第一阶段继续使用 Hash History，保持当前 `#/login`、相对部署路径和 Nginx 部署方式。
4. 保留 `web/` 构建输出目录，避免同时修改 Docker 和部署目录约定。
5. 保留 `public/config.js` 运行时配置模式，不把环境配置全部搬到构建时 `.env`。
6. 业务迁移按“登录和布局 -> 工作台 -> 低风险列表 -> 详情和表单 -> 自定义表单”推进。

## 2. 当前项目基线

### 2.1 项目规模

本次本地扫描结果：

| 范围 | 数量或结果 | 说明 |
| --- | ---: | --- |
| 仓库文件扫描 | 2,431 | 包含源码、文档、静态文件和构建相关文件 |
| `src/**/*.vue` | 1,349 | 业务页面和组件主体 |
| `src/**/*.js` | 190 | API、工具、路由、状态和第三方适配 |
| `src/**/*.scss` | 63 | 全局、PC、移动端和业务样式 |
| PC 路由 `path` 声明 | 约 316 | `src/router/pc.js` 静态统计 |
| 移动端路由 `path` 声明 | 约 196 | `src/router/mobile.js` 静态统计 |
| PC 动态 import | 约 184 | 包含历史 Webpack chunk 注释 |
| 移动端动态 import | 约 182 | 包含历史 Webpack chunk 注释 |
| `.sync` 使用文件 | 856 | 组件双向绑定迁移的主要工作量 |
| 旧 slot 语法使用文件 | 638 | `slot-scope`、`slot`、旧 scoped slot |
| `$set` 使用文件 | 436 | Vue 3 需要改成直接赋值 |
| 旧销毁生命周期使用文件 | 264 | `beforeDestroy`、`destroyed` |

高风险组件：

- `src/components/pComponents/CustomFormPc.vue`：约 20,301 行
- `src/components/mComponents/CustomFormMobile.vue`：约 22,848 行
- `src/components/pComponents/systemApprovalDetail.vue`：约 5,085 行
- `src/components/mComponents/systemApprovalDetail.vue`：约 2,584 行
- `src/layout/components/UserInfo.vue`：约 2,107 行

这些组件必须放在迁移后期，不能作为第一批改造对象。

### 2.2 当前技术栈

依据 [package.json](../package.json)、锁文件和当前 `node_modules`：

| 分类 | 当前实现 |
| --- | --- |
| 框架 | Vue 2.7.16，Options API |
| 构建 | Vue CLI 4，Webpack |
| PC UI | Element UI 2.x |
| 移动端 UI | Vant 2.x |
| 复杂表格 | `vxe-table` 3.x、`vxe-pc-ui` 3.x |
| 路由 | Vue Router 3.x |
| 状态 | Vuex 3.x + `vuex-persist` |
| 请求 | Axios 0.19.x |
| 样式 | Sass、全局 SCSS 注入、Scoped SCSS |
| 编辑器 | WangEditor Vue 2 wrapper |
| 拖拽 | `vuedraggable` 2.x |
| 微前端 | `wujie-vue2` |
| 地图 | Leaflet、高德、天地图、华为 Web SDK 等多套能力 |
| 其他插件 | VueTouch、VueGeolocation、VueCropper、微信分享、版本更新提示 |

### 2.3 当前入口和架构边界

主要入口和职责如下：

| 文件 | 当前职责 | 迁移重要性 |
| --- | --- | --- |
| `src/main.js` | Vue 实例、UI 库、全局指令、原型方法、错误监控、动态弹窗、微信分享 | 极高 |
| `src/App.vue` | 根组件、网络状态、微信分享初始化、版本更新提示 | 高 |
| `src/router/index.js` | PC/移动端分流、登录守卫、公司切换、权限守卫、账号禁用 | 极高 |
| `src/router/pc.js` | PC 路由和懒加载页面 | 高 |
| `src/router/mobile.js` | 移动端路由和懒加载页面 | 高 |
| `src/store/index.js` | Vuex、持久化、getter、状态重置 | 极高 |
| `src/api/request.js` | Axios 拦截器、Token、UID、错误提示、请求去重 | 极高 |
| `src/layout/index.vue` | PC 布局、标签页、keep-alive、Wujie reload、工单提醒 | 极高 |
| `src/mLayout/index.vue` | 移动端布局、提醒、版本通知、打卡和地图相关逻辑 | 极高 |
| `public/config.js` | 运行时环境、API、地图、Wujie 子应用地址、默认图片 | 极高 |
| `public/index.html` | 外部脚本、运行时配置脚本、图标和 SDK | 高 |
| `vue.config.js` | Webpack、代理、输出目录、Sass、缓存、版本更新插件 | 第一阶段替换 |

### 2.4 已验证的构建基线

当前 `npm run build` 可以完成生产构建，但本次验证得到 135 条警告。至少包含：

- `src/views/mobile/Purchase/purchase_edit.vue` 引用了 `@/api` 中不存在的 `PurchaseDetail`
- `src/views/mobile/Order/order_detail.vue` 引用了 `@/api` 中不存在的 `getStockLogList`
- 多个 SCSS 文件存在空 `background-image:url()` 和 Flex 兼容性提示
- 超大组件触发 Babel deoptimised 提示

这些问题不一定是 Vue 3 迁移引入的，但必须作为迁移前基线记录。迁移后的构建不能出现新的错误；已有警告需要逐项归类为“修复、保留或豁免”。

## 3. 目标状态

### 3.1 目标技术栈

| 分类 | 目标实现 |
| --- | --- |
| 框架 | Vue 3，先保留 Options API，完成后再渐进使用 Composition API |
| 构建 | Vite |
| PC UI | Element Plus |
| 移动端 UI | Vant 4 |
| 路由 | Vue Router 4 |
| 状态 | 先 Vuex 4，稳定后再评估 Pinia |
| 表格 | 与 Vue 3 兼容的 `vxe-table` 4.x 体系 |
| 拖拽 | `vuedraggable` 4.x 或同等 Vue 3 方案 |
| 微前端 | Wujie Vue 3 wrapper 或 Wujie core API |
| 编辑器 | WangEditor Vue 3 兼容 wrapper |
| 构建输出 | `web/` |
| 部署路径 | `./` |
| 开发端口 | 8888 |
| 路由模式 | Hash History |

### 3.2 目标构建目录

```text
index.html                 # Vite 入口 HTML
vite.config.js             # Vite 配置
public/
  config.js                # 保留运行时配置
  coordtransform_utils.js  # 保留静态脚本
  lib/                     # 保留 linkify 等静态库
src/
  main.js                  # Vue 3 createApp 入口
  router/                  # Vue Router 4
  store/                   # Vuex 4，后续可拆 Pinia
  plugins/                 # 全局插件和 app.config.globalProperties
  utils/                   # 请求、运行时配置、资源和通知适配
web/                       # Vite production 输出
```

## 4. 分阶段迁移路线

## 阶段 0：建立回归基线

### 目标

明确当前版本“什么是正常行为”，并把已有构建警告和运行时问题从迁移问题中分离出来。

### 工作项

1. 创建独立迁移分支。
2. 保存当前 `package-lock.json` 和 `web/` 构建产物基线。
3. 执行 `npm run build`、`npm run lint` 和现有业务测试。
4. 记录 PC 和移动端核心路径。
5. 记录浏览器控制台错误、网络请求失败、外部 SDK 加载失败。
6. 建立最小冒烟测试清单，至少覆盖登录、工作台、审批详情和工单详情。

### 验收

- 当前版本可以完成生产构建。
- 能明确区分已有警告和迁移新增错误。
- PC、移动端、登录态和公司切换行为有可复现步骤。

### 回滚边界

此阶段不修改源码和依赖，只允许增加文档、测试脚本或基线记录。

## 阶段 1：Vue 2.7 切换到 Vite

### 目标

只替换构建工具，业务仍运行在 Vue 2.7 上。

### 主要改动

1. 新增根目录 `index.html`，将原 `public/index.html` 的 HTML 内容迁移到 Vite 入口。
2. 新增 `vite.config.js`。
3. 保留 `vue.config.js` 和原脚本，增加 Vite 并行脚本，方便回退。
4. 配置 `@` 指向 `src`。
5. 配置 `base: './'`、`build.outDir: 'web'`、`server.port: 8888`。
6. 迁移 `/api`、`/wxchat`、天地图瓦片代理。
7. 用 `css.preprocessorOptions.scss.additionalData` 替换 Sass 的 `prependData`。
8. 将生产 source map、资源命名和构建版本注入迁移到 Rollup/Vite 配置。
9. 将 `process.env.BASE_URL` 改成统一资源地址方法。
10. 将源码中的 `require('@/assets/...')` 改成静态 import 或资源 URL。
11. 清理 Webpack chunk 注释；动态 import 本身保留。
12. 为版本更新提示寻找 Vite 适配方案，不能继续依赖 Webpack plugin hook。

### 重点文件

- `vue.config.js`
- `public/index.html`
- `public/config.js`
- `src/views/**/KnowledgeBase/**`
- 所有包含 `require('@/assets')` 的组件
- 所有使用 `process.env` 的组件
- `scripts/verify-build-cache-busting.js`
- `Dockerfile`

### Vite 配置映射

| 现有配置 | Vite 对应方式 |
| --- | --- |
| `publicPath: './'` | `base: './'` |
| `outputDir: web` | `build.outDir: 'web'` |
| `devServer.port: 8888` | `server.port: 8888` |
| `devServer.proxy` | `server.proxy` |
| `sass.prependData` | `css.preprocessorOptions.scss.additionalData` |
| `resolve.alias` | `resolve.alias` |
| `productionSourceMap: false` | `build.sourcemap: false` |
| Webpack `splitChunks` | Rollup `manualChunks`，先使用 Vite 默认分包，再按结果优化 |
| Webpack HTML plugin | `transformIndexHtml` 或构建脚本 |

### 验收

- Vue 2 CLI 和 Vue 2 Vite 两套构建均可执行。
- Vite 开发端口、代理、相对路径和 `web/` 输出正确。
- 登录、工作台、PC 路由、移动端路由和至少一个 Wujie 子应用可加载。
- `public/config.js`、地图 SDK、微信 SDK、linkify 和 Office SDK 加载顺序无变化。
- Vite 版本下不存在 `process is not defined`、`require is not defined`、资源 404 和动态 import 失败。

### 回滚边界

任何无法解决的 Vite 构建或静态资源问题，都可以暂时回到 Vue CLI；此阶段不进入 Vue 3 依赖升级。

## 阶段 2：切换 Vue 3 兼容运行时

### 目标

在 Vite 基础上接入 Vue 3 runtime，使用 `@vue/compat` 暂时承接 Vue 2 Options API。

### 依赖方向

```text
vue 2.7       -> vue 3 + @vue/compat
vue-router 3  -> vue-router 4
vuex 3        -> vuex 4
```

### 入口改造

将 [src/main.js](../src/main.js) 拆成以下逻辑边界：

1. `createApp(App)`。
2. 注册 Router、Store、Element/Vant 兼容层和自定义插件。
3. 使用 `app.directive()` 注册全局指令。
4. 使用 `app.config.globalProperties` 暂时承接现有 `$moment`、`$showApprovalDetail`、`$showLogDetail`、`$WechatShare` 等方法。
5. 使用 `app.config.errorHandler` 和 `app.config.warnHandler` 替换 `Vue.config`。
6. 最后 `app.mount('#app')`。

### 路由改造

重点文件：

- `src/router/index.js`
- `src/router/pc.js`
- `src/router/mobile.js`

需要完成：

1. `new VueRouter` 改为 `createRouter`。
2. 继续使用 `createWebHashHistory()`。
3. `beforeEach(to, from, next)` 改为返回式守卫。
4. `router.currentRoute` 改为 `router.currentRoute.value`。
5. `router.replace` 和 `router.push` 的重复导航处理改为 Router 4 方式。
6. 通配路由 `path: '*'` 改为 `/:pathMatch(.*)*`。
7. 保留白名单、Token 判断、公司切换、模块权限和账号禁用逻辑。
8. 将布局中的 `router-view` 改成 Router 4 插槽写法，以兼容 `keep-alive`。

### 状态改造

重点文件：

- `src/store/index.js`
- `src/store/state.js`
- `src/store/actions.js`
- `src/store/mutations.js`
- `src/store/getters.js`（如后续拆出）

处理原则：

1. 先保留现有 state、mutation、action 和 getter 名称。
2. 先升级 Vuex，不在同一阶段迁移 Pinia。
3. 保留 `vuex` localStorage key，避免用户升级后全部退出登录。
4. 保留 `userInfo`、`collapse`、`inventoryProductData`、权限、打印和报销打印等持久化字段。
5. 将 `resetState` 改成 Vuex 4 可维护的初始状态工厂。
6. 对公司切换和权限请求增加重复请求测试。

### 验收

- 登录后刷新页面，用户信息和权限仍然存在。
- 路由守卫仍能阻止未登录、禁用账号和无权限访问。
- PC 标签页和 keep-alive 行为不丢失。
- 移动端路由跳转、返回和审批详情回传正常。

## 阶段 3：迁移全局基础设施和 Vue 2 语法

### 3.1 全局插件和原型

当前 `src/main.js` 中必须逐项迁移：

| 当前能力 | Vue 3 处理方式 |
| --- | --- |
| Element UI 全局注册 | Element Plus app plugin 或按需注册 |
| Vant 全局注册 | Vant 4 app plugin 或按需注册 |
| `Vue.prototype.$moment` | `app.config.globalProperties`，后续改 composable |
| `$showApprovalDetail` | 全局 dialog service 或布局级 DialogHost |
| `$showLogDetail` | 全局 dialog service 或布局级 DialogHost |
| `$WechatShare` | Vue 3 plugin `install(app)` |
| `Vue.directive` | `app.directive` |
| `Vue.extend` 动态弹窗 | `createVNode`/`render` 或 DialogHost |
| `VueTouch` | 原生 touch/pointer 事件或 Vue3 方案 |
| `VueGeolocation` | composable/native API |
| `wujie-vue2` | Vue 3 wrapper 或 core API |

### 3.2 指令

需要改造：

- `src/directives/auth.js`
- `src/directives/dialogDrag.js`
- `src/directives/errorImg.js`
- `src/utils/load_more.js`
- `src/main.js` 中的 `dynamic-decimal-limit` 和 `thousands`

Vue 2 指令钩子映射：

| Vue 2 | Vue 3 |
| --- | --- |
| `bind` | `beforeMount` |
| `inserted` | `mounted` |
| `update` | `updated` |
| `componentUpdated` | `updated` |
| `unbind` | `unmounted` |

`v-auth` 当前通过 `vnode.context.$store` 读取 Vuex，Vue 3 中应通过闭包捕获 store，或使用 `binding.instance.$store` 的兼容方式，不能继续依赖 `vnode.context`。

### 3.3 事件总线

当前 [src/utils/eventBus.js](../src/utils/eventBus.js) 使用 `new Vue()`。推荐先使用 `mitt`，提供兼容适配层：

```js
EventBus.$on = emitter.on
EventBus.$off = emitter.off
EventBus.$emit = emitter.emit
```

这样可以先不修改所有业务调用方，再逐步改成 `on/off/emit`。

### 3.4 动态弹窗

当前入口使用 `Vue.extend`、`$mount`、`$destroy` 手工创建审批和日志详情弹窗。Vue 3 中不应继续复制这套方式。

推荐增加：

```text
src/components/common/dialog-host.vue
src/utils/dialog-service.js
```

由 `App.vue` 或布局统一渲染 DialogHost，服务只负责修改响应式状态。这样可以保留 Promise 返回值、PC 弹窗和移动端路由跳转的差异，同时不再手工管理 Vue 实例生命周期。

### 3.5 模板语法

迁移顺序：

1. `.sync` 改为 `v-model:prop`，子组件改为 `update:prop` 事件。
2. `slot-scope` 改为 `v-slot` 或 `#default`。
3. `slot="footer"` 改为 `#footer`。
4. `$set` 改为直接给对象属性或数组下标赋值。
5. `$delete` 改为 `delete`。
6. `this.$createElement` 改为 `h`。
7. `this.$listeners`、`this.$scopedSlots`、`$children` 等低层 API 逐步移除。

不要直接对全部文件做无审查正则替换。优先使用 AST/codemod 处理简单模式，再人工检查 Element、Vant、vxe 的插槽和双向绑定。

## 阶段 4：替换 Vue 2 专属第三方依赖

### 4.1 依赖替换表

| 当前依赖 | 目标依赖或方案 | 主要兼容风险 |
| --- | --- | --- |
| `element-ui` | `element-plus` | Dialog、Form、Table slot、Message、图标 |
| `vant@2` | `vant@4` | Popup/Dialog `v-model`、Toast/Dialog API、事件名 |
| `vxe-table@3` | `vxe-table@4` | 表格 API、列插槽、渲染器、插件注册 |
| `vxe-pc-ui@3` | 与 vxe 4 匹配的版本 | UI 组件和 renderer 版本必须一致 |
| `@vxe-ui/plugin-render-element` | 对应 vxe 4 renderer | Element Plus 渲染器配置 |
| `vuedraggable@2` | `vuedraggable@4` | `v-model`、事件和 slot 变化 |
| `wujie-vue2` | Vue 3 wrapper/core API | 子应用生命周期和 bus |
| `@wangeditor/editor-for-vue@1` | Vue 3 兼容版本 | Editor、Toolbar、销毁和配置对象 |
| `vue-cropper@0.5` | Vue 3 兼容实现 | 上传、裁剪回调和实例 API |
| `vue-touch` | 原生 touch/pointer 或 Vue3 方案 | 手势阈值和事件兼容 |
| `vue-geolocation-api` | 原生 Geolocation composable | 权限、错误和监听清理 |

### 4.2 处理顺序

1. Element Plus 和 Vant 先建立项目级通知、Dialog、Loading、ImagePreview 适配层。
2. 再迁移普通表单、按钮、弹窗、列表。
3. 再迁移 vxe-table 和复杂渲染器。
4. 再迁移编辑器、裁剪、拖拽和 Wujie。
5. 最后删除 Vue 2 依赖。

`src/api/request.js` 当前直接引入 Element UI 的 `Message` 和 Vant 的 `Toast`，应先抽成 `src/utils/notify.js`，避免请求层被某一个 UI 库绑定。

## 阶段 5：按业务域迁移页面

### 批次 1：启动和布局

- `src/App.vue`
- `src/layout/index.vue`
- `src/mLayout/index.vue`
- `src/layout/components/Header.vue`
- `src/layout/components/Aside.vue`
- `src/layout/components/Menu.vue`
- `src/layout/components/Tag.vue`

验收：登录、布局、菜单、标签页、keep-alive、网络状态和版本提示。

### 批次 2：登录和公司切换

- `src/views/pc/Login/**`
- `src/views/mobile/Login/**`
- `src/views/pc/NoCompany/**`
- `src/views/mobile/NoCompany/**`
- `src/utils/company.js`

验收：登录、邀请、注册公司、忘记密码、绑定、公司 URL 参数切换。

### 批次 3：工作台和低风险列表

- `src/views/pc/WorkBench/**`
- `src/views/mobile/WorkBench/**`
- `src/views/pc/Message/**`
- `src/views/mobile/Message/**`
- `src/views/pc/Work/Notice/**`
- `src/views/mobile/Work/Notice/**`

验收：列表请求、分页、筛选、权限按钮、通知和未读数量。

### 批次 4：审批、工单和订单

- `src/views/pc/Approve/**`
- `src/views/mobile/Approve/**`
- `src/views/pc/WorkOrder/**`
- `src/views/mobile/WorkOrder/**`
- `src/views/pc/Order/**`
- `src/views/mobile/Order/**`

验收：详情、审批动作、转交、评论、附件、回跳和弹窗返回值。

### 批次 5：财务、采购、库存和项目

- `src/views/pc/Finance/**`
- `src/views/mobile/Finance/**`
- `src/views/pc/Purchase/**`
- `src/views/mobile/Purchase/**`
- `src/views/pc/InventoryManagement/**`
- `src/views/mobile/InventoryManagement/**`
- `src/views/pc/ProjectManagement/**`
- `src/views/mobile/ProjectManagement/**`

验收：表格、批量操作、导入导出、地图、打印、复杂表单和大数据渲染。

### 批次 6：高风险公共组件

- `CustomFormPc.vue`
- `CustomFormMobile.vue`
- `CustomFormDetailPc.vue`
- `CustomFormDetailMobile.vue`
- `systemApprovalDetail.vue`
- WangEditor、Cropper、Wujie、Gantt 相关组件

这一批次必须建立独立回归数据和截图/录屏，不与普通页面批次混合验收。

## 5. Vite 配置迁移细节

### 5.1 运行时配置

`public/config.js` 应继续作为普通静态脚本在应用代码之前加载。业务代码继续读取：

- `window.BASEURL`
- `window.WXBASEURL`
- `window.STOCK_APP_URL`
- `window.OA_APP_URL`
- `window.PRODUCTCOVER`
- `window.GOODSCOVER`
- 地图 Provider、瓦片和 SDK 配置

构建时变量只用于构建行为，例如构建版本、是否启用 source map，不替代业务运行时配置。

### 5.2 静态资源

当前大量代码使用：

```js
require('@/assets/images/default.jpg')
```

Vite 迁移时建议分两类处理：

1. 组件固定资源：在 `<script>` 顶部静态 import。
2. 业务运行时资源：使用 `new URL('./asset.png', import.meta.url).href` 或统一资源工具。

不要直接把所有资源字符串改成以 `/` 开头的绝对路径，否则 `base: './'` 和子目录部署时会失效。

### 5.3 HTML 和版本缓存

当前 HTML 使用：

```html
<%= htmlWebpackPlugin.options.buildVersion %>
```

Vite 版本应统一使用一个 `buildVersion`，并注入：

- `favicon.svg`
- `config.js`
- `coordtransform_utils.js`
- 更新提示脚本或版本 JSON

`scripts/verify-build-cache-busting.js` 需要改为检查 Vite 输出格式，不能继续假设 Webpack HTML 结构。

## 6. 请求层和错误处理迁移

重点文件：

- `src/api/request.js`
- `src/api/requestManager.js`
- `src/utils/errorLog.js`
- `src/utils/networkStatus.js`

迁移要求：

1. 保留 Authorization、UID、Token 优先从 Store 读取的逻辑。
2. 保留重复请求限制、取消请求和下载 Blob/ArrayBuffer 处理。
3. 保留 401、403、409 和业务 code 的处理行为。
4. 将 Element/Vant 消息调用移到通知适配层。
5. `router` 和 `store` 改成显式依赖，避免模块初始化时从全局实例读取。
6. 错误日志不要把 Axios cancel、Blob 下载和 ResizeObserver benign error 当成业务错误。
7. Vue 3 使用 `app.config.errorHandler` 接入页面错误监控。

## 7. 测试与验收矩阵

### 7.1 构建层

- `npm run build:vite` 成功。
- 产物仍输出到 `web/`。
- `web/index.html`、`config.js`、地图脚本和版本文件存在。
- 资源路径在根域名和子目录部署下均正确。
- Dockerfile 能直接复制 Vite 产物。

### 7.2 路由和权限

- 未登录访问受保护路由会回登录页。
- 登录后访问登录页会重定向。
- 公司 URL 参数能完成待切换公司处理。
- 账号禁用会进入禁用页。
- 模块权限不足不能通过 URL 直达。
- PC 标签页、刷新和 keep-alive 正常。
- 移动端白名单、返回和详情回跳正常。

### 7.3 业务功能

- 登录、注册、邀请、忘记密码、绑定。
- 工作台、消息、公告、待办。
- 审批发起、审批详情、评论、转交、打印。
- 工单新增、编辑、分派、转单、实施、评价。
- 订单、采购、收付款、发票、报销。
- 库存入库、出库、资产、编码、导入导出。
- 地图定位、地址搜索、天地图瓦片、Leaflet 渲染。
- 文件上传、下载、预览、打印和 Office SDK。
- 微信分享、Wujie 子应用和子应用 reload bus。

### 7.4 质量门槛

每个迁移批次必须满足：

1. 构建无新增 error。
2. 控制台无新增 Vue 运行时异常。
3. 关键页面无资源 404。
4. 关键接口请求参数和响应处理与基线一致。
5. PC 和移动端至少各有一次真实登录回归。
6. 迁移完成的组件不能继续引入 Vue 2 专属包。

## 8. 风险清单

| 风险 | 影响 | 应对方式 |
| --- | --- | --- |
| Element UI 2 和 Vant 2 依赖 Vue 2 | Vue 3 原生阶段无法继续使用 | compat 过渡，按 UI 域替换 |
| `.sync` 数量大 | 双向绑定行为变化 | 先 compat 警告，再按组件迁移 |
| 旧 slot 语法多 | 表格和表单渲染异常 | 重点检查 Element、Vant、vxe 插槽 |
| `Vue.extend` 动态弹窗 | 弹窗无法显示或缺少 Store | DialogHost + dialog service |
| `$set` 大量存在 | Vue 3 中方法不存在 | 直接赋值，优先改高频公共组件 |
| Wujie 子应用 | 微前端生命周期和 bus 失效 | 单独做子应用回归，不和普通页面混测 |
| 地图 SDK 和外部脚本 | 本地能运行但生产路径失败 | 保留 `public/config.js` 和 HTML 顺序 |
| Vite 相对路径 | 子目录部署资源 404 | 固定 `base: './'` 并做产物检查 |
| 超大自定义表单 | 编译慢、迁移难、回归成本高 | 最后迁移，拆分字段组件后再处理 |
| Vuex 持久化格式变化 | 用户登录态丢失 | 保留 `vuex` key，增加旧数据读取测试 |
| Webpack 更新插件 | 版本提示失效 | Vite 插件或自有 HTML/JSON 注入方案 |

## 9. 第一阶段实际任务清单

第一轮不要升级 Vue 依赖，按以下顺序执行：

1. 新建迁移分支和方案评审记录。
2. 固定当前 `npm run build` 的 warning 清单。
3. 建立 PC、移动端核心冒烟测试。
4. 增加 `vite.config.js` 和根目录 `index.html`。
5. 增加 `dev:vite`、`build:vite`，保留原 CLI 脚本。
6. 迁移 alias、端口、代理、输出目录、Sass 和相对 base。
7. 清理 `process.env.BASE_URL` 和所有静态资源 `require()`。
8. 迁移 build version 和 cache-busting 校验脚本。
9. 用 Vite 验证登录、工作台、移动端入口和一个 Wujie 页面。
10. 对比 CLI 与 Vite 的构建产物、网络请求和路由行为。

阶段 1 完成前，不修改 `vue`、`vue-router`、`vuex`、Element UI、Vant 和业务组件模板。

## 10. 完成定义

只有同时满足以下条件，才可以删除 Vue CLI 和 compat：

- PC 和移动端全部路由可访问。
- 登录、权限、公司切换和账号禁用行为一致。
- 审批、工单、订单、采购、财务、库存、项目核心流程通过回归。
- 地图、文件、打印、微信和 Wujie 通过专项回归。
- 生产构建、Docker、Nginx 和相对路径部署通过验证。
- 代码中不再依赖 `Vue.extend`、`new Vue`、`Vue.prototype`、`Vue.set`、`Vue.delete`。
- 不再依赖 `element-ui`、`vant@2`、`wujie-vue2` 和其他 Vue 2 专属 wrapper。
- compat warning 清单为空，或每一项都有明确豁免说明。
- `npm run build`、lint、业务测试和冒烟测试全部通过。

## 11. 相关代码入口

- [package.json](../package.json)
- [vue.config.js](../vue.config.js)
- [src/main.js](../src/main.js)
- [src/App.vue](../src/App.vue)
- [src/router/index.js](../src/router/index.js)
- [src/router/pc.js](../src/router/pc.js)
- [src/router/mobile.js](../src/router/mobile.js)
- [src/store/index.js](../src/store/index.js)
- [src/api/request.js](../src/api/request.js)
- [src/layout/index.vue](../src/layout/index.vue)
- [src/mLayout/index.vue](../src/mLayout/index.vue)
- [public/index.html](../public/index.html)
- [public/config.js](../public/config.js)
- [Dockerfile](../Dockerfile)
