Vue 转 React 神器 VuReact 来了

什么是 VuReactVuReact发音/vjuːˈriːækt/是一个渐进式 语义驱动 的 Vue 3 → React 18 迁移编译器旨在为 Vue 项目与可控的渐进式迁移提供高效、可靠的开发体验。它不仅执行语法层面的转换更能深入理解 Vue 代码的语义生成符合 React 最佳实践的代码。由编译时转换运行时适配两部分构成。核心策略是“约定优先”——通过明确的编译约定确保转换稳定可靠尤其适合渐进式迁移场景。定位当前阶段VuReact 优先服务于以下场景新项目开发直接按照 VuReact 约定编写 Vue 风格的组件并输出为 React 代码现代语法支持专注于 Vue 3 Composition API 与script setup语法可控渐进迁移支持按目录、模块逐步迁移允许 Vue 与 React 组件在项目中并存开发体验优化为希望享受 Vue 优秀心智模型并编写 React或进行跨框架混合开发的团队提供高效方案暂不优先支持复杂遗留项目期望“零改动一键迁移”的历史代码库混合历史写法包含大量短期内难以统一的传统选项式 API 或非标准模式的工程快速上手本节将引导你完成第一个 VuReact 项目的创建、编译和运行或者选择先查看在线演练。完成后你会明确三件事输入 SFC 在什么约定下可稳定转换编译后目录会长什么样输出 TSX 与原始 SFC 的语义对应关系编译器会自动分析并追加依赖无需手动管理 React hooks 依赖项Step 0准备目录先准备一个最小工程示意my-app/ ├─ src/ │ ├─ components/ │ │ └─ Counter.vue │ ├─ main.ts │ └─ index.css ├─ package.json └─ vureact.config.jsStep 1安装在你的 Vue 项目中安装 VuReact 编译器# 使用 npmnpminstall-Dvureact/compiler-core# 使用 yarnyarnadd-Dvureact/compiler-core# 使用 pnpmpnpmadd-Dvureact/compiler-coreStep 2编写输入 SFCsrc/components/Counter.vuetemplatesectionclasscounter-cardh2{{ props.title || title }}/h2pCount: {{ count }}/pbuttonclickincrement1/buttonbuttonclickmethods.decrease-1/button/section/templatescriptsetuplangts// vr-name: Counter 注用于告诉编译器该生成什么组件名import{computed,ref}fromvue;// 也可以使用宏定义组件名defineOptions({name:Counter});// 定义 propsconstpropsdefineProps{title?:string}();// 定义 emitsconstemitsdefineEmits{(e:change):void;(e:update,value:number):number;}();conststepref(1);constcountref(0);consttitlecomputed(()Counter x${step.value});constincrement(){count.valuestep.value;emits(update,count.value);};constmethods{decrease(){count.value-step.value;},};/scriptstylelanglessscopedborder-color:#ddd;border-radius:8px;padding-base:12px;.counter-card{border:1px solidborder-color;border-radius:border-radius;padding:padding-base;}/styleStep 3配置编译器vureact.config.jsimport{defineConfig}fromvureact/compiler-core;exportdefaultdefineConfig({input:src,// 关键排除 Vue 入口文件避免入口语义冲突exclude:[src/main.ts],output:{workspace:.vureact,outDir:dist,// 教程场景关闭环境初始化便于观察纯编译产物bootstrapVite:false,},format:{enabled:true,// 开启格式化同时这也会增加编译耗时。formatter:prettier,},});Step 4执行编译方式一使用 npx 命令在根目录下运行npx vureact build方式二使用 npm scripts在package.json里添加脚本命令scripts:{watch:vureact watch,build:vureact build}npmrun buildStep 5查看输出目录树编译后目录示意my-app/ ├─ .vureact/ │ ├─ cache/ │ │ └─ _metadata.json │ └─ dist/ │ └─ src/ │ └─ components/ │ ├─ Counter.tsx │ └─ Counter-hash.css ├─ src/ │ └─ ... └─ vureact.config.jsStep 6对照生成结果下面是一个格式化后的典型输出为说明做了轻微简化实际哈希与属性名以本地产物为准import{memo,useCallback,useMemo}fromreact;import{useComputed,useVRef}fromvureact/runtime-core;import./Counter-a1b2c3.css;// 根据 defineProps 和 defineEmits 推导typeICounterType{title?:stringonChange:()void;onUpdate:(value:number)number;}// memo 包裹组件constCountermemo((props:ICounterType){// ref/computed 转换成了对等的适配 APIconststepuseVRef(1);constcountuseVRef(0);consttitleuseComputed(()Counter x${step.value});// 自动分析顶层箭头函数依赖并追加 useCallback 优化constincrementuseCallback((){count.valuestep.value;props.onUpdate?.(count.value);// emits 转换},[count.value,step.value,props.onUpdate]);// 自动分析顶层对象中的依赖并追加 useMemo 优化constmethodsuseMemo(()({decrease(){count.value-step.value;},}),[count.value,step.value],);return(section classNamecounter-carddata-css-a1b2c3h2 data-css-a1b2c3{props.title||title.value}/h2p data-css-a1b2c3Count:{count.value}/pbutton onClick{increment}data-css-a1b2c31/buttonbutton onClick{methods.decrease}data-css-a1b2c3-1/button/section/);});exportdefaultCounter;CSS 文件内容.counter-card[data-css-a1b2c3]{border:1px solid #ddd;border-radius:8px;padding:12px;}关键观察点// vr-name: Counter这段特殊注释定义了组件名defineProps和defineEmits被转换成了 TS 组件类型非纯 UI 展示组件默认会走memo包装ref/computed被转换为 runtime 适配 APIuseVRef/useComputed模板事件回调会生成符合 React 语义的onClick顶层箭头函数自动分析依赖尝试注入useCallback顶层变量声明自动分析依赖尝试注入useMemo对 JSX 中的原ref状态值补上.valueless样式被编译为 css 代码scoped样式会生成带哈希的 css 文件并在元素上标注作用域属性常见失败点没排除 Vue 入口文件如src/main.ts在非顶层调用会被转换为 Hook 的 API模板里出现不可分析表达式并被告警关闭样式预处理且使用scoped导致作用域失效了解更多详情请参阅 VuReact 常见问题解答。生态集成Vue 核心适配包提供 React 版的 Vue 常用内置组件、核心 Composition API 等Vue 路由适配包支持 Vue Router 4.x - React Router DOM 7.9 转换如果确实需要你可以选择 ☣️混合编写以此直接使用 React 生态。 相关资源GitHubhttps://github.com/vureact-js/coreGiteehttps://gitee.com/vureact-js/core官方文档https://vureact.topNPMhttps://www.npmjs.com/package/vureact/compiler-core在线演示https://codesandbox.io/p/github/vureact-js/example-crm-admin-backend/masterVuReact Runtimehttps://runtime.vureact.topVuReact Routerhttps://router.vureact.top如果这款工具对你有帮助欢迎去 GitHub 点个 Star 支持一下持续更新 Vue → React 迁移实战、原理与避坑干货