重构旧项目：从 jQuery 迁移到 Vue 3 的分步方案与避坑指南

在许多历史项目中，jQuery 承担了选择器、事件、AJAX、动画与插件生态的核心角色。随着组件化、响应式与工程化的发展，迁移到 Vue 3 能显著提升可维护性与性能。本文给出一套渐进式方案与避坑清单，帮助在保业务稳定的前提下完成迁移。

为什么迁移

• 组件化与响应式：减少跨文件 DOM 操作与隐式状态共享。
• 工程化与类型化：更好的构建、静态检查、测试与可观测性。
• 性能与体验：虚拟 DOM、差分更新、代码分割与按需加载。
• 生态与可持续：围绕 Vue 3 的工具与社区更加完善。

迁移前评估

• 页面类型：纯表单、数据列表、图表、富文本、复杂交互。
• jQuery 插件依赖：select2、datepicker、datatables、validation 等。
• 全局变量与工具：$ 的使用范围、$.ajax 包装、事件总线习惯。
• 路由形态：是否已有 hash 路由，是否需要 SEO 与 SSR。
• 构建与发布：是否已使用 webpack，是否有多入口与遗留脚本。

迁移策略选择

• 渐进式共存：先在局部引入 Vue 3，逐页或逐模块替换。
• Big Bang 重写：新仓库全面重建，适合规模可控、耦合较弱的项目。
• 推荐渐进式：风险低，易于灰度发布与回滚。

渐进式路线图

1. 基础设施

• 构建：Vite 或 Webpack，目标 ES2018+。
• 质量：ESLint、Prettier、TypeScript（可选）。
• 测试：Vitest 或 Jest，组件测试优先。
• 依赖：vue@3、pinia、vue-router、axios。

2. 接入 Vue 3

• 在 jQuery 页面中预留挂载点，例如 <div id="app-root"></div>。
• 通过脚本在目标区域 createApp 并 mount。

3. DOM 管理权交接

• 将一个页面中的“功能岛”替换为 Vue 组件（如过滤器、列表、弹窗）。
• 保留 jQuery 插件，外包裹 Vue 组件或指令，统一生命周期。

4. 数据层统一

• 抽象 AJAX 为 services，统一错误处理、重试、取消与鉴权。
• 引入 pinia 管理全局状态，避免跨组件隐式数据共享。

5. 路由迁移

• 先在单页内部使用 vue-router 接管子路由。
• 与历史 hash 路由共存，逐步替换入口页面。

6. 表单与校验

• 采用受控组件与校验库（如 vee-validate、yup）。
• 统一错误提示与交互反馈。

7. 构建与发布

• 代码分割与按需加载，拆分旧页面与新组件。
• 灰度发布与开关控制，保留回退路径。

共存技巧

在 Vue 中包裹 jQuery 插件（指令）

import $ from 'jquery';

export const jqSelect2 = {
  mounted(el, binding) {
    $(el).select2(binding.value || {});
  },
  beforeUnmount(el) {
    $(el).select2('destroy');
  }
};

在组件中使用：

<template>
  <select v-jq-select2="opts"><option value="1">A</option></select>
  <select v-jq-select2><option value="2">B</option></select>
  <select v-jq-select2><option value="3">C</option></select>
  <select v-jq-select2><option value="4">D</option></select>
</template>

<script setup>
import { jqSelect2 as vJqSelect2 } from './directives/jqSelect2';
const opts = { minimumResultsForSearch: 5 };
</script>

在 jQuery 页面中嵌入 Vue 子应用

import { createApp } from 'vue';
import Widget from './Widget.vue';

const el = document.getElementById('app-root');
const app = createApp(Widget, { initData: window.__BOOT__ });
app.mount(el);

function dispose() {
  app.unmount();
}

事件桥接

// Vue 侧
function emitEvent(name, detail) {
  window.dispatchEvent(new CustomEvent(name, { detail }));
}

// jQuery 侧
$(window).on('app:event', (e, payload) => {
  // 处理 payload
});

服务与请求迁移

将 $.ajax 迁移为 fetch/axios，统一超时、取消、重试与错误码。

import axios from 'axios';

const api = axios.create({ baseURL: '/api', timeout: 8000 });

api.interceptors.response.use(
  r => r,
  async e => {
    const status = e.response?.status;
    if (status >= 500) {
      await new Promise(r => setTimeout(r, 300));
      return api.request(e.config);
    }
    return Promise.reject(e);
  }
);

export async function getList(params) {
  const c = new AbortController();
  const p = api.get('/list', { params, signal: c.signal });
  return { promise: p, cancel: () => c.abort() };
}

状态与副作用

在 Vue 3 中使用 Composition API 管理状态与副作用。

import { ref, watchEffect, onMounted, onBeforeUnmount } from 'vue';

export function useListService() {
  const list = ref([]);
  const loading = ref(false);
  let cancel = () => {};

  async function load(params) {
    loading.value = true;
    const { promise, cancel: c } = getList(params);
    cancel = c;
    try {
      const res = await promise;
      list.value = res.data.items;
    } finally {
      loading.value = false;
    }
  }

  onBeforeUnmount(() => cancel());
  return { list, loading, load };
}

常见坑与对策

• 双向 DOM 操作冲突：避免在 Vue 管理的节点上使用 jQuery 修改结构或内容。
• 生命周期泄漏：销毁时确保移除 jQuery 事件与插件实例。
• 样式覆盖与层级：统一样式命名空间，避免全局选择器覆盖组件样式。
• 非响应式数据：避免直接修改对象属性而不通过 ref/reactive。
• 插件兼容性：老旧插件可能依赖 jQuery 版本，需锁定版本并评估替代。
• 路由与刷新：历史路由与 vue-router 共存时，统一入口与回退策略。
• 构建冲突：确保只保留一个打包器管理目标页面的脚本与样式。

性能与可观测性

• 按需加载：路由级与组件级分割。
• 虚拟列表与懒加载：对长列表与重组件管理渲染成本。
• 埋点与日志：记录首屏、交互时延、错误码与请求量。

验收与回退

• 灰度发布：通过开关按用户或页面范围启用新版本。
• 指标门槛：设定性能与错误阈值，自动回退策略。
• 回滚预案：保留旧入口与静态资源，快速降级。

迁移检查清单

• 是否完成关键模块的组件化替代。
• jQuery 插件是否以指令或组件封装并清理生命周期。
• 服务层是否统一到 axios/fetch 并具备取消与重试。
• 全局状态是否迁移到 Pinia 并移除隐式共享。
• 路由是否由 vue-router 接管并与历史路由协调。
• 构建与发布是否支持代码分割与灰度回退。
• 埋点与日志是否覆盖关键路径。

总结

从 jQuery 迁移到 Vue 3 的核心在于渐进式共存与有序交接。通过组件化替换、数据层统一、路由与构建升级，并用指令或包装组件托管 jQuery 插件生命周期，可以在最小风险下逐步完成迁移。配合灰度发布、指标监控与回滚预案，确保迁移过程可控与可恢复。