告别Prop Drilling：React 18与Vue 3项目迁移至Zustand与Pinia的工程化实践

1. 问题背景：当Context成为性能瓶颈

我们的主项目是一个基于React 18 + TypeScript的运维管理后台，另一个是Vue 3 + Element Plus的电商数据看板。两个项目初期都依赖Context/Props进行状态传递，但随着业务膨胀，问题逐渐暴露：

• 重渲染失控：某个全局筛选条件的变更，通过Context触发所有消费组件重渲染。React DevTools Profiler显示，单次筛选操作平均触发214次组件更新，其中63%是无用的。
• 代码不可维护：一个组件Props最多时达到23个，其中仅5个是自身业务所需，其余均为透传。Vue项目更甚，provide/inject的key散落各处，重构时无人敢动。
• 调试困难：Context的value变化无法追踪来源，我们不得不打大量console.log。

我们决定彻底迁移。经过选型，最终圈定Zustand（React）和Pinia（Vue）。原因很直接：API简洁、支持异步、有中间件、且与框架解耦，最关键的是它们的订阅机制能做到精准渲染——谁订阅了谁才更新。

2. 环境与版本：迁移前必须对齐的依赖

为了保证迁移的平滑，我们锁定了以下版本（截至2024年3月稳定版）：

// React项目 package.json 关键依赖
{
  "react": "^18.2.0",
  "zustand": "^4.5.0",
  "react-redux": "^9.0.0" // 仅作对比，未采用
}

// Vue项目 package.json 关键依赖
{
  "vue": "^3.4.0",
  "pinia": "^2.1.7",
  "vuex": "^4.1.0" // 仅作对比，未采用
}

注意：Zustand的v4版本对TypeScript支持极佳，且引入了useShallow钩子，配合create的subscribeWithSelector中间件可以做到细粒度订阅。Pinia的v2版本完全兼容Vue 3的Composition API，且天然支持storeToRefs。

3. 方案设计：从Context到Store的映射策略

我们遵循以下原则进行设计：

1. 状态分类：将原Context中的状态分为三类——UI状态（弹窗开关、折叠面板）、服务端状态（用户信息、权限列表）、临时状态（表单草稿）。
2. Store拆分：按业务域拆分为多个Store，而非一个全局大Store。例如用户Store、权限Store、筛选条件Store。
3. 保留局部Props：对于某个组件树内部的私有状态，继续使用useState或ref，不强行提升。

React迁移核心代码（Zustand）：

// stores/useUserStore.ts
import { create } from 'zustand';
import { devtools } from 'zustand/middleware';

interface UserState {
  userInfo: { id: number; name: string; role: string } | null;
  permissions: string[];
  fetchUser: (id: number) => Promise;
}

export const useUserStore = create()(
  devtools(
    (set) => ({
      userInfo: null,
      permissions: [],
      fetchUser: async (id) => {
        const res = await fetch(`/api/user/${id}`);
        const data = await res.json();
        set({ userInfo: data, permissions: data.permissions });
      },
    }),
    { name: 'UserStore' } // devtools中间件，方便Redux DevTools调试
  )
);

// 组件中精准订阅，避免无谓渲染
const userInfo = useUserStore((state) => state.userInfo);
const permissions = useUserStore((state) => state.permissions);

Vue迁移核心代码（Pinia）：

// stores/filter.ts
import { defineStore } from 'pinia';

export const useFilterStore = defineStore('filter', {
  state: () => ({
    keyword: '',
    dateRange: [null, null] as [Date | null, Date | null],
  }),
  getters: {
    hasFilter: (state) => state.keyword !== '' || state.dateRange[0] !== null,
  },
  actions: {
    setKeyword(keyword: string) {
      this.keyword = keyword;
      // 这里可以添加防抖或日志中间件
    },
  },
});

// 组件中使用 storeToRefs 保持响应性但避免解构丢失
import { storeToRefs } from 'pinia';
const filterStore = useFilterStore();
const { keyword, dateRange } = storeToRefs(filterStore);

4. 核心实现：三步完成迁移与优雅降级

第一步：并行运行与灰度切换。我们通过环境变量VITE_USE_NEW_STORE来控制。在旧Context组件中，我们将value改为从新Store读取，实现桥接。

第二步：批量替换Props透传。对于React项目，使用`包裹顶层，但内部组件全部改为从Store直接取值。对于Vue，直接删除provide，在需要的组件中useFilterStore()`。

第三步：删除幽灵代码。迁移后，我们清理了约2000行Props类型定义和透传逻辑。同时，在Zustand中利用combine中间件实现持久化，替代了原先手写的localStorage逻辑。

踩坑记录：

• Zustand的create泛型：v4中必须显式声明State类型，否则set方法推断错误。
• Pinia的Store命名冲突：多个Store时，如果state字段名相同，storeToRefs不会冲突，但Vue Devtools中会混淆。务必给每个Store设置独立的id。
• React 18的并发特性：Zustand的useStore在React 18的startTransition中表现正常，但useSyncExternalStore的getSnapshot必须返回缓存引用，否则会导致无限循环。我们通过shallow比较对象解决了此问题。

5. 性能变化：数据会说话

迁移完成后，我们对两个项目做了严格的性能对比（基于Chrome 120的Performance面板，取10次平均值）：

一个直观的体验：之前切换筛选条件时，页面有肉眼可见的白屏闪烁，现在几乎是即时响应。

6. 总结与建议

如果只是几个组件共享状态，继续用Props/Context完全没问题，不要为了用而用。但当你遇到以下三个信号，就该考虑引入了：

1. Props层级超过3层，且中间层不消费该状态。
2. 相同状态被超过5个组件订阅，且状态变更频繁。
3. 团队协作时，新人无法理解状态流向。

Zustand和Pinia都不是重武器，它们轻量到可以随时局部引入，不必像Redux那样大规模重构。建议从最小的业务域开始试点，两周内完全切换，然后再铺开。

最后放一句我们团队复盘时的话：“状态管理不是越重越好，而是越精准越好。能精确到组件粒度的订阅，就绝不用广播式的通知。”希望这篇记录对你有用，欢迎在评论区交流踩坑经验。