开始
什么是 VuReact
VuReact（发音 /vjuːˈriːækt/）是一套面向 Vue 迁移 React 和混合开发的解决方案，兼具 「用 Vue 写 React」 双重能力的编译工具。 它用于将 Vue 3 SFCs・Scripts・Styles 完整转为原生 React 代码（非运行时桥接），覆盖 <script setup> 核心全特性，支持渐进式迁移。
此外，它绝非简单替换语法，而是深入理解 Vue 的语义，输出符合 React 最佳实践、可读且易于维护的代码。我们的目标并非“一键将任意 Vue 代码转为 React”，而是提供一条清晰、可预测、便于分析与维护的迁移路径，帮助团队在可控范围内平稳推进跨框架演进。
VuReact 由三部分协同构成：编译时转换、Runtime（运行时）和 Router（路由适配）：
- 编译时转换：将符合约定的 Vue 代码生成结构清晰、易于维护的 React 代码，并自动注入必要的运行时依赖；
- 运行时（Runtime）：负责语义适配与行为兼容，确保转换后的组件在 React 环境中稳定运行；
- 路由适配（Router）：在需要时提供 Vue Router 风格的路由支持，便于迁移路由逻辑。
三部分协同配合，既保证了转换质量，也提升了运行稳定性与工程落地效率。
解决痛点
VuReact 旨在解决以下典型场景中的开发痛点：
- 技术栈迁移：团队希望采用 React 生态，但已积累 Vue 语法习惯与组件资产，期望平滑过渡而非彻底重学
- 渐进式重构：旧有 Vue 系统需要逐步迁移至 React，避免高风险的一次性重写与业务中断
- 开发体验统一：借助 Vue 的响应式心智模型编写 React 组件，同时免除手动管理依赖项与渲染优化的繁琐
- 生态扩展：丰富跨框架的开发工具链，为多技术栈共存或迁移提供标准化方案
核心挑战在于：若输入代码的语义不可静态分析，编译器便无法稳定生成符合 React Hooks 规则的输出。 因此，VuReact 采取 “约定优先” 的策略：先通过明确的 编译约定 界定可转换的代码范围，再在该范围内实现高效、可靠的转换。
适用场景
推荐使用
- 项目需从 Vue 3 渐进式迁移到 React，但不想从头重写，优先寻找现有解决方案
- 部分开发者以 Vue 为主技术栈，习惯其心智模型，认为 React 的额外负担比 Vue 更重
- 后端开发者不想学习双框架，Vue 上手快、符合直觉，不愿接触 React
- 转换后的 React 需完全脱离 Vue 运行时，避免双框架运行时所带来的性能和体积问题
注意事项
- 优先可控：服务于可控工程场景
- 约定驱动：需要遵守明确的编译约定
- 现代语法：专注于 Vue 3 Composition API 与
<script setup>
可选 ☣️混合编写，Vue 项目直接引入 React 生态能力。
项目定位
这是：
- 一套将 Vue 单文件组件（SFC）及
<script setup>语法转换为 React 代码的编译工具链 - 一个 带约束的编译平台，通过明确的约定保障转换质量与可维护性
- 具备工程化能力的开发工具，能够对不符合约定的输入给出清晰的告警或错误提示，并引导修正
这不是：
- 可处理任意历史代码的“万能迁移魔术师”
- 对非约定写法进行运行时兜底的解释器
- 承诺无需任何调整即可全量迁移旧项目的商业化产品
核心特性
VuReact 提供以下关键能力：
🧠 语义感知：深度理解Vue语法的完整语义结构，包括模板指令、script setup逻辑、组合式API和TypeScript类型等，智能生成符合React最佳实践的代码
⚖️ 渐进迁移：支持从单文件到整个项目的可控渐进迁移，规避一次性大规模转换带来的技术债务和系统风险
🧭 约定驱动：基于明确的语法约定而非启发式规则进行编译，确保转换行为的确定性、可分析性和可维护性，完整支持现代Vue语法
⚛️ 完整特性适配：将响应式 API、生命周期、内置组件、路由等Vue核心特性完整适配到React，编译阶段完全处理scoped、module和样式语言等，实现零运行时开销
⚡ 优秀的开发体验：延续 Vue 心智模型实现无感开发 React；提供 build/watch 双模式 CLI，支持极速增量编译与文件监听，让跨框架开发效率与体验达到原生级别
🌀 创新探索：探索跨框架编译桥模式，允许Vue和React代码在编译层面共存，验证"Vue到React完整编译"的技术可行性
👽 智能编译：涵盖语法转换、模板解析、样式处理、类型保留与工程优化
智能编译特性
- 语法智能转换：将 Vue 3 组合式 API 智能映射为 React Hooks
- 模板智能解析：将 Vue 模板指令智能转换为 JSX
- 样式智能处理：将 Scoped CSS 等智能适配为 React 可运行 CSS 产物
- 类型智能保留：智能迁移 TypeScript 类型系统
- 工程智能优化：智能处理依赖分析、缓存机制与代码优化
快速上手
详细引导教程请参见：快速开始 章节。
安装
在你的 Vue 3 项目下，选择任意方式安装：
npm i -D @vureact/compiler-core创建配置文件
在项目根目录下，创建 vureact.config.ts 文件：
import { defineConfig } from '@vureact/compiler-core';
export default defineConfig({
input: '', // 输入路径，支持单文件或目录
exclude: ['src/main.ts'], // 排除 Vue 入口与不参与编译的文件
output: {
workspace: '.vureact',
outDir: 'react-app',
bootstrapVite: true,
},
onSuccess: async () => {
console.log('编译成功！');
// 这里可以执行额外的操作，比如操作文件系统、调用其他工具等
},
});💡 更多配置项详见： 配置 API
方式一：转换单个 Vue 组件
{
// 单 SFC 试点，需使用 <script setup>
input: './src/your-component.vue',
}方式二：转换整个项目
{
// 支持多级目录递归，输入任意目录即可
// 注意：所有组件必须使用 <script setup>（否则会报错）
input: './src',
}💡 若使用了 Vue Router，请查看 路由适配指南 进行配置。
执行编译转换
npx vureact build自动生成的 .vureact/react-app 目录里，包含了转换后的组件和相关依赖配置等。
项目结构大致示例：
vue-project/
├── .vureact/ # 工作区（编译生成）
│ ├── cache/ # 编译缓存
│ ├── react-app/ # 转换后的 React 工程
│ │ ├── src/ # 转换后的 React 代码
│ │ ├── package.json # React 项目依赖
│ │ ├── vite.config.ts # Vite 配置
│ │
├── src/ # 原始 Vue 代码
├── package.json # 原始项目依赖
└── vureact.config.ts # 配置文件CLI 命令
# 全量/增量编译
npx vureact build
# 开发模式，监听文件变化自动编译
npx vureact watch
# 查看版本
npx vureact -v
# 查看帮助
npx vureact --help👉 build/watch 指南详见：Build 增量编译 | Watch 监听模式
生态集成
- VuReact Runtime：提供轻量级 React 版的 Vue 核心组件 & API
- VuReact Router：基于 React Router DOM 的 Vue Router 风格适配层
可选 ☣️混合编写，Vue 项目直接引入 React 生态能力。