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

fruge365

发布于 2025-12-15 13:43:25

1920

重构旧项目：从 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 };
}