当前位置：首页 > news >正文

jQuery 转 Solid 迁移实战：从0到1

news 2026/4/19 6:33:32

一、为什么要写这篇文章

做过 jQuery 转 Vue3 迁移的同学都知道——光看文档是不够的。文档告诉你 API 怎么用，但不会告诉你哪些"习惯性写法"在新框架里会悄悄出错，还不报错。

本文来自真实迁移经历，整理了 6 类高频踩坑场景，每个都附有错误写法 + 报错现象 + 根因分析 + 正确做法，直接拿去对照自查。

二、坑一：响应式数据更新方式不同

// ❌ 错误：用 jQuery 的不可变思维修改 Vue3 响应式对象 // jQuery 中你习惯这样做： setState({ ...user, name: 'new name' }); // 迁移到 Vue3 后照搬展开，响应式丢失： user.value = { ...user.value, name: 'new name' }; // ❌ 触发重新渲染，但 watcher 无法感知深层变化 // ✅ 正确：Vue3 直接修改响应式对象属性 user.value.name = 'new name'; // ✅ Proxy 自动追踪 // 如果需要整体替换，用 Object.assign： Object.assign(user.value, { name: 'new name', age: 30 }); // ✅

根因：Vue3 用 Proxy 代理对象，直接赋值属性才能被依赖追踪系统捕获。'...spread' 会产生一个全新对象绑定，虽然触发更新但破坏了 reactive 深层追踪。

三、坑二：生命周期钩子时序差异

// ❌ 错误：在 Vue3 setup() 里直接读取 DOM（DOM 未挂载） setup() { const el = document.getElementById('chart'); // ❌ 此时 DOM 还没渲染 initChart(el); // 崩溃: Cannot read properties of null } // ✅ 正确：DOM 操作必须放在 onMounted 里 setup() { const chartRef = ref(null); onMounted(() => { initChart(chartRef.value); // ✅ DOM 已挂载 }); onUnmounted(() => { destroyChart(); // ✅ 必须清理，防止内存泄漏 }); return { chartRef }; }

四、坑三：watch 的立即执行与 useEffect 的差异

// jQuery 的 useEffect：依赖变化 + 初始化都执行 useEffect(() => { fetchData(userId); }, [userId]); // 组件挂载时也执行一次 // ❌ 误以为 Vue3 的 watch 同理： watch(userId, (newId) => { fetchData(newId); // ❌ 首次不执行！只在 userId 变化时才触发 }); // ✅ 正确：加 immediate: true 让首次也执行 watch(userId, (newId) => { fetchData(newId); }, { immediate: true }); // ✅ 等价于 jQuery 的 useEffect // 或者用 watchEffect（自动收集依赖，立即执行）： watchEffect(() => { fetchData(userId.value); // ✅ 立即执行 + userId.value 变化时自动重跑 });

五、坑四：类型定义与 Props 校验

// ❌ 错误：直接用 PropTypes 的思维，但 Vue3 不支持 props: { user: PropTypes.shape({ name: String }) // ❌ Vue3 没有 PropTypes } // ✅ 正确：Vue3 用 defineProps + TypeScript 接口 interface UserProps { user: { name: string; age: number; avatar?: string; }; onUpdate?: (id: number) => void; } const props = defineProps<UserProps>(); // 带默认值： const props = withDefaults(defineProps<UserProps>(), { user: () => ({ name: '游客', age: 0 }), });

六、坑五：事件总线 / 全局状态的迁移

// jQuery 习惯用全局 Redux / Context // ❌ 错误：迁移时找不到 Vue3 等价物，用全局变量代替 window.__state = reactive({}); // ❌ 失去了响应式边界，调试困难 // ✅ 正确：用 Pinia（Vue3 官方推荐状态管理） // stores/user.ts export const useUserStore = defineStore('user', () => { const user = ref(null); const isLoggedIn = computed(() => !!user.value); async function login(credentials) { user.value = await api.login(credentials); } function logout() { user.value = null; } return { user, isLoggedIn, login, logout }; }); // 组件中使用 const userStore = useUserStore(); const { user, isLoggedIn } = storeToRefs(userStore); // ✅ 保持响应式

七、坑六：异步组件与 Suspense

// jQuery 懒加载组件 const LazyComponent = lazy(() => import('./HeavyComponent')); // Vue3 等价写法（API 不同！） const LazyComponent = defineAsyncComponent(() => import('./HeavyComponent')); // Vue3 的异步组件支持加载状态和错误状态： const LazyComponent = defineAsyncComponent({ loader: () => import('./HeavyComponent'), loadingComponent: LoadingSpinner, errorComponent: ErrorDisplay, delay: 200, // 200ms 后才显示 loading（防闪烁） timeout: 3000, // 超时时间 });

八、总结 Checklist

场景	jQuery 做法	Vue3 正确做法
对象更新	setState({...obj})	直接修改属性 / Object.assign
DOM 操作	useEffect + ref	onMounted + ref
副作用初始化	useEffect(() => fn, [dep])	watch(dep, fn, {immediate: true})
Props 类型	PropTypes	defineProps()
全局状态	Redux / Context	Pinia defineStore
懒加载组件	React.lazy	defineAsyncComponent
清理资源	return () => cleanup()	onUnmounted(() => cleanup())

💬踩过坑的点赞收藏！关注我，后续持续更新框架迁移避坑系列（React↔Vue3↔Angular 全覆盖）。

三、实战进阶：jQuery 最佳实践

3.1 错误处理与异常设计

在生产环境中，完善的错误处理是系统稳定性的基石。以下是 jQuery 的推荐错误处理模式：

// 全局错误边界（React）/ 全局错误处理（Vue3） // Vue3 全局错误处理 const app = createApp(App); app.config.errorHandler = (err, instance, info) => { // 1. 上报错误到监控系统（Sentry/自建） errorReporter.capture(err, { component: instance?.$options?.name, info, userAgent: navigator.userAgent, url: location.href, }); // 2. 区分错误类型：网络错误 vs 业务错误 vs 未知错误 if (err instanceof NetworkError) { toast.error('网络连接失败，请检查网络'); } else if (err instanceof BusinessError) { toast.warning(err.message); } else { toast.error('系统异常，请稍后重试'); console.error('[未知错误]', err); } }; // 异步错误：Promise.reject 未处理 window.addEventListener('unhandledrejection', (event) => { errorReporter.capture(event.reason, { type: 'unhandledrejection' }); event.preventDefault(); // 阻止默认的控制台报错 });

3.2 性能监控与可观测性

现代系统必须具备三大可观测性：Metrics（指标）、Logs（日志）、Traces（链路追踪）。

// 前端性能监控：Core Web Vitals + 自定义指标 import { onCLS, onFID, onFCP, onLCP, onTTFB } from 'web-vitals'; // 收集 Web Vitals 并上报 function reportWebVitals(metric) { const { name, value, id, delta } = metric; // 发送到自建监控或 Google Analytics fetch('/api/analytics', { method: 'POST', body: JSON.stringify({ name, // CLS/FID/FCP/LCP/TTFB value, // 当前值 delta, // 与上次的差值 id, // 唯一标识 page: location.pathname, timestamp: Date.now(), }), keepalive: true, // 页面关闭时也能发送 }); } onCLS(reportWebVitals); // 累积布局偏移 onFID(reportWebVitals); // 首次输入延迟 onLCP(reportWebVitals); // 最大内容绘制（< 2.5s 为优） onFCP(reportWebVitals); // 首次内容绘制 onTTFB(reportWebVitals); // 首字节时间 // 自定义性能标记 performance.mark('api-start'); const data = await fetch('/api/data'); performance.mark('api-end'); performance.measure('api-latency', 'api-start', 'api-end'); const [measure] = performance.getEntriesByName('api-latency'); console.log('API 耗时:', measure.duration.toFixed(2) + 'ms');

3.3 测试策略：单元测试 + 集成测试

高质量代码离不开完善的测试覆盖。以下是 jQuery 推荐的测试实践：

// Vue3 组件测试（Vitest + Vue Testing Library） import { describe, it, expect, vi } from 'vitest'; import { render, fireEvent, waitFor } from '@testing-library/vue'; import UserCard from './UserCard.vue'; describe('UserCard 组件', () => { it('正确渲染用户信息', () => { const { getByText } = render(UserCard, { props: { name: '张三', email: 'zhang@example.com', role: 'admin' }, }); expect(getByText('张三')).toBeInTheDocument(); expect(getByText('zhang@example.com')).toBeInTheDocument(); expect(getByText('管理员')).toBeInTheDocument(); }); it('点击删除按钮时 emit delete 事件', async () => { const { getByRole, emitted } = render(UserCard, { props: { name: '李四', email: 'li@example.com', role: 'user' }, }); await fireEvent.click(getByRole('button', { name: '删除' })); expect(emitted().delete).toBeTruthy(); expect(emitted().delete[0]).toEqual([{ email: 'li@example.com' }]); }); it('加载状态下显示 Skeleton', () => { const { container } = render(UserCard, { props: { loading: true }, }); expect(container.querySelector('.skeleton')).toBeInTheDocument(); }); }); // Pinia Store 测试 import { setActivePinia, createPinia } from 'pinia'; import { useUserStore } from '@/stores/user'; describe('UserStore', () => { beforeEach(() => setActivePinia(createPinia())); it('login 成功后更新 state', async () => { const store = useUserStore(); vi.spyOn(authApi, 'login').mockResolvedValue({ token: 'mock-token', user: { id: 1, name: '测试用户' }, }); await store.login('test@example.com', 'password'); expect(store.isLoggedIn).toBe(true); expect(store.user?.name).toBe('测试用户'); expect(localStorage.getItem('token')).toBe('mock-token'); }); });

3.4 生产部署清单

上线前必检：

检查项	具体内容	优先级
配置安全	密钥不在代码中，用环境变量或 Vault	P0
错误处理	所有 API 有 fallback，不暴露内部错误	P0
日志规范	结构化 JSON 日志，含 traceId	P0
健康检查	/health 接口，K8s readiness/liveness probe	P0
限流保护	API 网关或应用层限流	P1
监控告警	错误率/响应时间/CPU/内存四大指标	P1
压测验证	上线前跑 10 分钟压测，确认 QPS/延迟	P1
回滚预案	蓝绿部署或金丝雀发布，问题 1 分钟回滚	P1