Mpx 跨端小程序框架：Vue 语法一套代码，编译六个小程序平台加 H5

写一套代码，同时编译成微信、支付宝、抖音、百度、京东这些小程序，顺便还能出 H5 页面——听起来像宣传语，但在小程序开发这个行业里，这是每天都要面对的真实选择题。每个平台一套原生工程，人员翻倍还不说，业务逻辑在三四个技术栈里重复实现，改一个需求要同步四处，迟早出偏差。

Mpx 走的是编译型跨端这条路：你用 Vue 的语法写页面，它的 webpack 插件在编译期把代码转换成各平台的语法，运行时再用一层轻量 runtime 抹平接口差异。源码包不大，成品 zip 只有 3.08MB，1562 个文件，13 个 npm 包加 9 个示例项目，Apache-2.0 协议。

我把 Windows 和 WSL2 两个环境都跑了一遍：依赖安装、小程序端与 Web 端构建、产物比对、浏览器实测。结论先给：框架本身的编译链路是通的，小程序端一次能编译出 wx 和 ali 两份产物；但官方示例工程的依赖声明有不少缺口，按文档直接跑会连环报错——哪几类人适合，写在后面。

它是什么，和 Taro 差在哪

一句话：用 Vue 语法写小程序，一套代码编译到六个小程序平台加 Web 和 React Native。

它和同类框架的差别体现在三个地方：

• 语法体系：Taro 默认 React 语法，Mpx 默认 Vue 语法，且深度绑定 Vue 2.7 的响应式与组合式 API。团队是 Vue 栈的话上手成本低很多。
• 增强能力：Mpx 在框架层内置了数据响应式（@mpxjs/store、pinia 桥接）、分包优化、SSR、国际化、按平台条件编译这些常用件，不用自己东拼西凑。
• 体积感知：它对小程序包体积做了专项优化（size-report 包就是干这个的），对卡在 2MB 主包上限的项目比较友好。

代价也明确：生态和社区规模不如 Taro，遇到冷门问题检索到的资料少；React 栈的团队要转语法，学习成本实打实存在。

我的测试环境

• Windows：Windows 11，Node v24.16.0，npm 11.x，实测目录解压后操作
• Linux：本机 WSL2 Ubuntu，Node v20.19.2，同一份源码包

测试对象选了官方 examples 里的 mpx-todoMVC（最小示例，含 store 与组合式 API），另用渐进式主示例 mpx-progressive 补了 Web 端验证。

安装：Windows

源码包是 npm workspaces 管理的 monorepo，进包根目录装依赖：

npm install --legacy-peer-deps

装完 1591 个包，首次耗时 53 秒。--legacy-peer-deps 不能省，原因见后面的坑。

解压即可完成的零依赖验证，三条命令：

node -e "console.log(require('./框架源码/packages/webpack-plugin/package.json').version)"
node -e "const p=require('./框架源码/packages/core/package.json');console.log(p.name, p.main)"
node -e "const m=require('./框架源码/packages/unocss-plugin/lib/platform.js');console.log('unocss-plugin lib OK', typeof m)"

分别输出 2.11.2、@mpxjs/core src/index.js、unocss-plugin lib OK object，三条都对上，包就是完整的。

构建与验证：Windows

编译小程序双端（微信 wx + 支付宝 ali）：

npm run build

总耗时 121 秒，两平台都 compiled successfully。产物：dist/wx 21 个文件 821KB，dist/ali 24 个文件 1756KB。

Web 端构建要给环境变量传 mode（npm 会吞掉 --mode 参数）：

npm_config_mode=web npm run build

清缓存后 61 秒编译完成，0 error 2 warning，dist/web 3 个文件 1712KB。本地起静态服务托管 dist/web，首页返回 HTTP 200，TodoMVC 的列表渲染、输入新增、计数、过滤全部正常，浏览器控制台 0 个 JS 报错、0 个 4xx/5xx。

构建与验证：WSL2 Linux

同一份 demo 源码复制到 /var/tmp（WSL 的 /tmp 是 tmpfs，会话结束清空，临时目录必须放 /var/tmp）：

npm i --legacy-peer-deps   # 1639 包，7 分钟
npm run build              # wx：退出码 0，61 秒，20 个文件
npm run build              # ali：退出码 0，62 秒，18 个文件

跨平台产物比对结论：结构一致、字节不一致。文件结构两边完全相同（app.js/app.json/bundle.js、2 个自定义组件、2 个页面、wxs/sjs 各 1），但文件名哈希不同（app8dc5c3ce 对 app1780ebdb），app.js 的 MD5 也不同，Windows 产物还多一个根目录 project.config.json。对「构建是否可复现」有硬性要求的团队要注意这一点。

界面长什么样

以下截图来自 dist/web 构建产物经本地静态服务托管后的无头浏览器实拍，桌面 1400 宽整页、手机 390 宽两倍缩放：

首页，TodoMVC 的完整初始状态，列表、输入框、过滤条与计数齐备：

回车新增一条待办，输入直接生效，无刷新渲染：

再加一条，右侧计数同步更新为 2 items left，响应式数据链路正常：

390 宽手机视口下的首页，布局自动收成单列，控件无溢出：

一个真实的坑：示例工程依赖声明不全

这是整个实测里最费时间的一段，报错是一连串的：

Error: Cannot find module 'webpack/lib/dependencies/ModuleDependency'
TypeError: (0, vue.observable) is not a function

根因和修法，按顺序：

• webpack 版本漂移：demo 写 ^5.72.0，实际装成 5.112 后 @mpxjs/webpack-plugin 引用的内部路径不存在。锁死 5.72.0。
• peer 冲突：插件声明要 webpack ^5.83.1，与 5.72.0 冲突，所以要 --legacy-peer-deps。
• 示例引用源码树相对路径：build/getRules.js 指向 ../../packages/babel-plugin-inject-page-event-function，示例目录里不存在，要改成指向源码树的 babel-plugin-inject-page-events。
• 依赖缺口：demo 还缺 @mpxjs/store、vue-demi、vue 2.7、vue-i18n-bridge、vue-router@3.5.4、vue-template-compiler，要手动补装。
• vue 2.7 的 ESM 产物不导出 observable：mpx core 的 web 入口从 'vue' 导入 observable 会直接炸，需在 vue 的 ESM 产物里补导出，并删 .cache 强制重编。

修完之后构建链路就顺了。这个坑对「只跑官方示例」的人是劝退级的，对要接入自有工程的人反而价值大——它把依赖边界摸清楚了。

接入自己的项目：三步

第一步，装依赖

新建工程或在示例基础上改，把 @mpxjs/core 与 @mpxjs/webpack-plugin 接进 package.json，依赖统一从源码树的 packages 目录以 file: 方式或 npm 安装，版本对齐 2.11.2。

第二步，配构建

webpack 配置里挂 @mpxjs/webpack-plugin，config 的 supportedModes 里写清楚目标平台（wx、ali、tt、swan、jd、qq、web），要哪个端写哪个端。上面那个 web 端的坑记得避开：mode 参数用环境变量传。

第三步，编译与预览

npm run build

产物落在本工程的 dist 目录，用微信开发者工具导入 dist/wx 预览；切平台改 supportedModes 重新编译即可。

这几类人适合，这几类不适合

适合：

• 团队技术栈是 Vue 2.x，存量 Vue 组件想搬进小程序
• 要同时覆盖三个以上小程序平台，且在意主包体积
• 想要分包、SSR、国际化这些能力开箱即用，不想自己搭

不适合：

• React 栈团队：转语法成本高，选 Taro 更顺
• 想跑通官方示例就立刻开工的人：示例工程依赖声明不全，得先过一遍上面那个坑
• 极度看重社区规模和第三方组件库的：Mpx 生态比 Taro、uni-app 都小

常见问题

源码获取

建议先转存到自己网盘再下载。手机上打开链接点右下角「保存到网盘」，回头在夸克 App 的「我的网盘」里解压使用。