企业官网建设流程全解析

MPX 是一个面向小程序场景的增强型跨端开发框架。它没有重新发明一套 DSL，而是保留原生小程序的写法和工程结构，再在此基础上补充状态管理、组件化、多端编译和性能优化能力。对于已经有微信小程序基础的开发者来说，MPX 的上手成本很低；对于需要同时维护多个小程序端的团队，MPX 能把“一套代码，多渠道发布”的成本控制在可接受范围内。

这篇文章会围绕一条完整的主线展开：先理解 MPX 的定位和工作原理，然后从零创建一个项目，写页面、组件和状态管理，再构建到多个小程序平台，最后处理性能问题和常见报错。读完以后，你可以直接用这套思路搭建一个可运行、可扩展的小程序项目，也能在遇到编译错误或跨端样式问题时快速定位方向。

1. MPX 定位：不是又一个跨端框架，而是小程序的增强层

1.1 为什么有了原生小程序还要用 MPX

原生小程序本身已经具备页面、组件、路由、API 等完整能力，但进入真实业务后，几个问题会很快暴露出来：

第一，小程序没有官方提供跨端复用方案。微信小程序、支付宝小程序、百度小程序、头条小程序虽然 API 相似，但文件结构、生命周期、样式隔离、事件绑定都存在差异。如果每个端都单独维护一套代码，需求变动时成本会成倍增加。

第二，原生语法缺少 Vue 风格的响应式能力。数据和视图的同步依赖开发者手动调用setData，复杂页面中的数据流转、计算属性、监听器都要靠手工维护，代码一多就很容易出现数据不同步的问题。

第三，组件化和状态管理的自由度不够。原生小程序虽然支持自定义组件，但组件间通信在复杂场景下仍然繁琐，全局状态没有统一方案。团队协作时，每个人都有自己的数据管理习惯，最终代码风格很难收敛。

MPX 解决这些问题的思路，是在原生小程序之上做增强。它保留了.wxml风格的模板、Page/Component的组件模型，同时引入了 Vue 生态中已经被验证过的响应式状态管理、计算属性、侦听器、混合（mixins）等能力。开发者仍然可以写原生小程序代码，也可以逐步把工程升级成 MPX 写法，而不是必须一次性重构。

1.2 MPX 和 Taro、uni-app、Remax 的差异

市面上常见的跨端方案大致可以分为两类。

一类是“编译时重写”，代表是 Taro 3 之前的部分版本和 uni-app。这类框架会让开发者使用 React 或 Vue 语法编写代码，然后在编译阶段转换成小程序原生代码。优点是开发体验统一，缺点是当框架对原生小程序能力支持滞后时，遇到不支持的 API 或性能瓶颈会比较难办。

另一类是“运行时适配”，代表是 Remax 和 Taro 3。这类框架在小程序运行时把 React/Vue 的虚拟 DOM 映射到小程序页面，开发体验接近 Web，但运行时层会增加一部分开销，对小程序初始化性能有一定影响。

MPX 走的是相对务实的第三条路：增强原生。它在编译期分析模板，把静态节点和动态绑定区分开，尽量减少setData的数据量，同时保留原生小程序组件的运行时行为。开发者可以直接使用wx:if、wx:for等原生指令，也可以使用类 Vue 的能力。这种方式的下限更有保障：即使 MPX 某个高级特性没有覆盖到，你仍然可以退回原生写法，不至于被框架卡住。

1.3 MPX 的“增强”具体指哪些能力

从工程视角看，MPX 的核心能力可以整理成一张表：

这张表不是让你把原生小程序丢掉，而是说明 MPX 在原生能力之上做了哪些补全。实际项目中，你可以先用原生语法写一个页面，再逐步引入 MPX 的状态管理和组件增强，整个过程是渐进式的。

2. 先把环境跑通：创建项目、目录结构和构建命令

2.1 安装 CLI 和创建项目

MPX 官方提供了脚手架工具，用于快速生成项目。使用前先确认电脑上已经安装了 Node.js 和 npm/yarn。Node.js 版本建议使用长期支持版本，如果你的电脑上安装了多个 Node.js 版本，建议先用nvm切换到指定版本，避免后续依赖安装时报错。

安装脚手架并创建项目的常见命令如下：

npm install -g @mpxjs/cli mpx create my-mpx-project

如果你的项目需要指定模板，CLI 通常会提供交互式选项。没有特殊需求时，选择默认模板即可。

创建完成后进入项目目录并安装依赖：

cd my-mpx-project npm install

这里要注意：MPX 的脚手架版本和核心依赖版本存在对应关系。如果你创建项目后运行npm install报错，先确认 npm 源是否可用，再检查 Node.js 版本是否满足项目要求。不要把报错直接归因于框架本身。

2.2 项目目录结构与核心文件作用

执行完创建命令后，项目里一般会生成类似下面的目录：

src/ pages/ index/ index.mpx app.mpx app.json app.js store/ public/ project.config.json package.json

src目录是源码目录，app.mpx是小程序入口文件，它包含了全局配置、全局样式和 App 生命周期逻辑。app.json是小程序全局配置，比如页面路由、窗口表现、分包结构等。

页面文件后缀是.mpx，一个文件内部可以包含template、script、style三个部分，写法上类似 Vue 单文件组件。例如：

<template> <view class="hello"> <text>{{ message }}</text> </view> </template> <script> import { createPage } from '@mpxjs/core' createPage({ data: { message: 'Hello MPX' } }) </script> <style lang="scss"> .hello { padding: 20px; } </style>

这个文件最终会被 MPX 编译成对应小程序平台可识别的页面文件。对于微信小程序，编译后会在dist/wx目录下生成index.js、index.wxml、index.wxss、index.json。

2.3 理解构建脚本与目标端模式

MPX 项目在package.json中会暴露多个构建命令。常见的脚本名是：

{ "scripts": { "serve": "mpx-cli-service serve --mode wx", "build:wx": "mpx-cli-service build --mode wx", "build:ali": "mpx-cli-service build --mode ali", "build:baidu": "mpx-cli-service build --mode baidu", "build:tt": "mpx-cli-service build --mode tt" } }

其中--mode wx表示构建目标为微信小程序，ali对应支付宝小程序，baidu对应百度小程序，tt对应字节小程序。具体脚本名以你创建的项目为准，但思路是一样的：MPX 通过mode参数决定编译产物写入哪个平台目录。

本地开发一般使用：

npm run serve

默认serve命令会启动开发模式，并在文件变更时自动重新编译。编译后的目录在你指定的模式所对应的目录中，比如dist/wx。微信小程序开发工具导入这个目录，就能看到真实运行效果。

2.4 启动开发者工具完成首次预览

以微信小程序为例，首次预览步骤如下。

打开微信开发者工具，选择“导入项目”，目录选择项目根目录下的dist/wx，AppID 可以先使用测试号。导入后等待编译完成，如果项目根目录存在project.config.json，开发者工具会读取其中的miniprogramRoot配置，自动定位到正确目录。

如果预览时页面空白，最优先检查的不是代码，而是dist/wx目录是否存在，以及开发者工具导入的目录到底对不对。很多新手会误把项目根目录当成小程序的代码目录导入，导致开发者工具无法识别app.json。

注意：开发阶段每次修改源码后都要确认是否已经重新编译，特别是从远程仓库拉取新代码后，不要直接打开旧编译目录立即报错。

3. 页面和组件开发：直接沿用原生语法，再叠加增强语法

3.1 数据绑定、列表渲染和事件处理

MPX 的模板语法与原生小程序基本一致，所以原生小程序开发者可以直接上手。在.mpx文件的template中，数据绑定使用双花括号，列表渲染使用wx:for，条件渲染使用wx:if。

一个简单的商品列表页面：

<template> <view class="goods-list"> <view wx:for="{{goodsList}}" wx:key="id" class="goods-item" > <text>{{ item.name }}</text> <text>{{ item.price }}</text> <button bindtap="onBuy">import { createPage } from '@mpxjs/core' createPage({ data: { price: 100, count: 2 }, computed: { total() { return this.price * this.count } } })

在模板中可以直接引用total：

<view>{{ total }}</view>

当price或count发生变化时，total会自动重新计算，不需要手动调用setData。

侦听器用于监听一个字段的变化，适合做表单联动或异步搜索：

createPage({ data: { keyword: '' }, watch: { keyword(val, oldVal) { console.log('keyword changed:', oldVal, '->', val) this.search(val) } }, methods: { search(keyword) { // 执行搜索逻辑 } } })

计算属性和侦听器确实能减少很多样板代码，但不要因此把所有逻辑都塞进去。计算属性应该保持无副作用，侦听器里不要执行太重的同步操作，否则页面渲染和事件响应都会受影响。

3.3 自定义组件的写法与数据传递

MPX 中的自定义组件同样使用.mpx文件，对外暴露属性，对内维护自己的状态。一个简单的计数器组件：

<!-- components/counter.mpx --> <template> <view> <text>{{ value }}</text> <button bindtap="onIncrement">+1</button> </view> </template> <script> import { createComponent } from '@mpxjs/core' createComponent({ properties: { value: { type: Number, value: 0 } }, methods: { onIncrement() { this.triggerEvent('increment', { value: this.value + 1 }) } } }) </script>

在页面里引用组件时，需要先在app.json或页面 JSON 中注册组件路径。如果你使用的是 MPX 的增强能力，也可以直接在页面模板中通过 import 方式引入，具体写法以项目模板配置为准。

父页面接收子组件事件时，使用bind:increment：

<counter value="{{currentValue}}" bind:increment="onIncrement" />

组件化的价值在于隔离和复用。建议一个组件只负责一个明确功能，不要在组件内部直接修改父级传入的value，而是通过事件告知父级修改。这样数据流清晰，排查问题时也更简单。

3.4 条件编译：让同一份代码适配多端差异

多端项目中，不同平台的 API、组件、样式都会有小差异。MPX 提供了条件编译能力，可以在源码中标记哪段代码只属于某个平台。

模板中的条件编译写法：

<!-- #ifdef MP-WEIXIN --> <view>只在微信小程序中渲染</view> <!-- #endif --> <!-- #ifndef MP-WEIXIN --> <view>除了微信小程序之外渲染</view> <!-- #endif -->

JS 中的条件编译写法：

// #ifdef MP-ALIPAY console.log('支付宝小程序环境') // #endif

样式中的条件编译：

/* #ifdef MP-WEIXIN */ .hint { color: #ff6f00; } /* #endif */

条件编译要谨慎使用。合理场景是：某平台只支持一个特殊 API，或者某个 UI 表现有明显差异。滥用条件编译会让代码在多个平台之间出现分叉，维护成本反而上升。建议把差异收敛到独立模块中，页面上尽量少出现平台分支。

4. 状态管理和内置能力：复杂业务下的组织形式

4.1 状态管理要解决什么问题

小程序页面之间是路由隔离的，页面间的共享数据通常需要通过跳转参数、全局变量或存储来传递。业务简单时问题不大，但一旦涉及登录信息、购物车、用户偏好、多页面联动，就会面临两个麻烦：

一是数据来源不统一。每个页面都要从接口或存储中读取数据，并且要保持同步，很容易出现 A 页面修改了数据，B 页面还是旧数据。

二是更新链路不清晰。数据发生变化时，所有依赖它的页面都应该被通知，但原生小程序没有现成的机制。

MPX 提供了createStore来管理全局状态。它采用类似 Vuex 的结构，把状态放在state中，通过mutations同步修改，通过actions处理异步逻辑。这样数据变更的链路有迹可循。

4.2 Store 的定义与使用

创建一个 store 文件，例如src/store/index.js：

import { createStore } from '@mpxjs/core' const store = createStore({ state: { userInfo: null, count: 0 }, getters: { isLogin(state) { return !!state.userInfo } }, mutations: { setUserInfo(state, userInfo) { state.userInfo = userInfo }, increment(state, amount = 1) { state.count += amount } }, actions: { async login(ctx, payload) { const userInfo = await fetchUser(payload) ctx.commit('setUserInfo', userInfo) return userInfo } } }) export default store

getters相当于 store 的计算属性，mutations是唯一允许修改state的地方，actions内部可以执行异步操作，最后提交 mutation。

页面或组件中可以通过this.$store访问 store 实例：

import { createPage } from '@mpxjs/core' createPage({ computed: { isLogin() { return this.$store.getters.isLogin } }, methods: { onLogin() { this.$store.dispatch('login', { username: 'admin', password: '123456' }) } } })

模板中也可以直接引用：

<view wx:if="{{ isLogin }}">已登录</view> <view wx:else>未登录</view>

4.3 页面间通信和全局数据同步

多个页面同时消费 store 里的同一个状态时，只要页面通过计算属性访问，状态变更后页面会自动更新。这解决了全局数据同步的问题。

但要注意一个常见错误：不要在页面里直接修改store.state中的对象，比如写this.$store.state.userInfo = xxx。这样虽然能生效，但会让数据变更难以追踪。推荐做法是定义对应的 mutation，通过commit触发。

如果页面和组件之间需要传递复杂数据，优先使用组件属性加事件，而不是直接把每个页面都塞进 store。只有跨页面共享的数据才应该放 store。

4.4 常用内置能力：请求、路由、存储

MPX 没有强行封装所有 API，而是提供了一些实用工具。比如mpx.request可以在多个平台统一发起网络请求：

import mpx from '@mpxjs/core' mpx.request({ url: 'https://api.example.com/goods', method: 'GET', data: { page: 1 } }).then(res => { console.log(res.data) }).catch(err => { console.error(err) })

路由能力通常仍依赖各小程序平台的原生 API，比如wx.navigateTo在支付宝小程序中对应my.navigateTo。MPX 可以通过条件编译或统一封装来解决，建议团队内部封装一个navigateTo工具函数，把平台差异收敛到一个文件里。

本地存储可以使用平台的 Storage API，也可以封装一层storage工具。缓存 key 的命名要规范，避免不同业务之间互相覆盖。例如统一前缀mpx_，并加上业务模块名。

5. 多端构建的细节：从微信到支付宝、百度、字节

5.1 一个项目构建多种小程序

MPX 的多端构建过程，可以理解为“一次编译，多端产出”。编译时根据mode参数，生成对应平台的小程序代码。

常见脚本：

npm run build:wx npm run build:ali npm run build:baidu npm run build:tt

每次构建后，检查对应dist目录。微信在dist/wx，支付宝在dist/ali。然后把对应目录导入到各平台的开发者工具中。

开发环境和生产环境的区别也比较明显：

生产构建前，一定要检查接口地址、AppID、分包配置和域名白名单，避免把测试环境配置发布上线。

5.2 不同端的差异点与适配写法

虽然 MPX 会处理大部分编译差异，但仍有几个地方需要开发者自己处理：

第一，页面生命周期和 API 差异。微信小程序的onPullDownRefresh、onReachBottom在支付宝小程序中可能对应不同名称或不同行为。MPX 通常会把通用生命周期做映射，但业务上对刷新、加载更多的处理逻辑仍然需要验证。

第二，组件标签差异。比如微信中的button在支付宝中仍然存在，但open-type的能力范围不同。涉及登录、支付等原生能力时，要分别查看各平台文档。

第三，样式兼容性。各小程序平台的基础样式不完全一致，字体大小、边框、圆角、scroll-view 行为都可能不同。建议在公共样式中统一重置，涉及平台特有样式时使用条件编译。

第四，存储和网络能力。不同平台的 storage 容量、同步异步 API 可能有差异，网络请求的 header 限制、超时设置也不一致。建议封装统一的 storage 和 request 模块。

一个稳妥的做法是：先以微信小程序为主完成开发，再逐个平台验证。条件编译覆盖的平台差异要记录在项目文档中，避免后续开发人员不知道某个分支为什么存在。

5.3 构建产物如何验证

多端项目不能只看微信端跑通就认为全部端都正常。每个平台都要做一轮基础验证。

验证清单可以这样设计：

不要等到发版前才去验证多端。建议在开发早期，每完成一个功能模块就在所有目标平台上跑一遍基础流程，越早发现适配问题，修改成本越低。

5.4 多端输出时的常见陷阱

一个很容易踩的坑是直接使用平台专有 API 而没有做兼容。比如wx.getUserProfile在非微信平台不存在，运行时会直接报错。解决办法是把平台 API 调用封装成公共函数，内部使用条件编译或运行时能力判断。

另一个坑是构建产物目录不一致。团队成员可能在本地构建出了不同平台的目录，提交代码时如果误提交dist目录，会产生大量冲突。推荐在.gitignore中忽略所有dist目录。

还有一个坑是资源引用路径。多端构建后，图片、字体等静态资源的路径可能会被改写。如果某个平台出现图片加载失败，优先检查构建后 JSON 和 WXML 中的路径，而不是直接在源码中找问题。

6. 性能和工程化：真实项目里更容易踩坑的部分

6.1 模板静态化和渲染性能

小程序性能瓶颈通常集中在首屏渲染和频繁setData。MPX 在编译阶段会尝试把模板中的静态部分标记出来，减少小程序运行时的 diff 范围。

对开发者来说，需要关注动态绑定的粒度。以下写法会在数据更新时带来更多开销：

<view>{{ user.name }} - {{ user.age }} - {{ user.address.city }}</view>

如果只有user.name会变化，其余字段不参与渲染，建议把模板拆细，让每个动态绑定范围更小，或者使用计算属性缓存。

另一个常见做法是避免在模板中直接调用方法：

<text>{{ formatTime(item.createTime) }}</text>

每次渲染都会重新执行formatTime。如果列表很长，性能会明显下降。建议在数据源进入页面时先完成格式化，模板只负责展示。

6.2 分包、按需加载和资源体积

小程序包体积有限制，MPX 项目同样需要做好分包。把独立业务模块拆成分包，登录页、首页等核心页面放在主包，低频页面放在分包。

MPX 的分包配置与原生小程序类似，在app.json中配置subpackages字段。编译时，MPX 会根据入口文件依赖关系，尽量把只被分包引用的代码和资源打进对应分包。

静态资源也要控制体积。图片优先使用压缩后的资源，能放到 CDN 的不要打到包里。代码中建议开启压缩，并对公共模块做合理的 tree shaking。如果构建后包体积仍然很大，可以用构建工具分析依赖，定位是哪个模块引入了大量代码。

6.3 图片、接口缓存和启动耗时

首屏加载时，图片往往是最大瓶颈。建议采用以下策略：

• 首屏只加载必要的图片，非首屏图片使用懒加载。
• 使用 CDN 且图片格式尽量采用压缩率更高的格式。
• 对图片设置合理的宽高，避免小程序根据实际尺寸反复计算。
• 小图标可以合并成雪碧图，或者使用 base64 内嵌在样式中。

接口请求方面，对不经常变化的数据要设置缓存。可以使用 storage 做简单缓存，但要注意缓存过期策略。比如每次请求前先判断缓存时间，超过五分钟就重新拉取。

启动耗时还和 JS 逻辑执行有关。不要在 App 的onLaunch中执行太多同步操作，尽量延迟非关键的初始化逻辑。第三方 SDK 的初始化也应该错峰执行，避免阻塞首屏。

6.4 代码规范与可维护性清单

MPX 项目在多人协作时，建议维护一份可执行清单，核心内容包括：

这些规范不需要一次性强制执行，但建议在代码审查时逐项检查。项目越大，这类工程约束越能降低返工成本。

7. 常见问题排查：配置、编译、白屏、适配问题

7.1 编译期报错

现象：执行npm run serve或npm run build:wx时，终端抛出类似Module not found: Can't resolve '@mpxjs/webpack-plugin'的异常。

可能原因：

• 依赖没有安装完整，node_modules缺失。
• 安装依赖时使用了不同的包管理器，锁文件不一致。
• Node.js 版本和当前 MPX 版本不兼容。

检查方式：

npm ls @mpxjs/webpack-plugin node -v

处理建议：删除node_modules和package-lock.json（或yarn.lock），重新执行npm install。如果仍然报错，检查项目模板要求的 Node.js 版本，并通过nvm切换。

7.2 开发阶段页面白屏

现象：微信开发者工具能打开项目，但页面空白，控制台提示Page is not found或Component is not found。

常见原因：

• 编译产物不是最新代码，开发者工具加载的是旧目录。
• app.json中注册的页面路径与真实文件路径不一致。
• 页面 JS 执行错误，生命周期函数或数据初始化抛异常。

处理顺序：

1. 确认执行的是正确的构建命令，检查dist目录最后修改时间。
2. 打开开发者工具的“编译模式”为普通编译，重新编译。
3. 查看 Console 中的错误堆栈，优先定位 JS 异常。
4. 检查dist/wx/app.json中的 pages 字段和相关页面文件是否真实存在。

建议在源码入口处加一个简单的生命周期日志，确认页面确实执行了onLoad：

onLoad() { console.log('[page-index] onLoad') }

日志能打印就说明路由正常，问题多半在数据请求或渲染阶段。

7.3 条件编译不生效

现象：在template或 JS 中写了#ifdef MP-WEIXIN，但构建到微信端时，被标记为其他端的代码仍然出现。

可能原因：

• 条件编译注释写在了错误位置。
• 目标端标识名写错，比如把MP-WEIXIN写成了MP-WECHAT，但项目配置里使用的标识并不相同。
• 代码被某个插件或其他编译工具提前处理，注释被移除。

检查方式：

grep -rn "MP-WEIXIN" src

运行后看注释关键字是否存在于源码中，以及关键字大小写是否正确。然后检查构建产物：

grep -rn "只在支付宝端渲染" dist/wx

如果dist/wx中仍存在该文本，说明条件编译没有被正确识别。

处理建议：参考当前项目脚手架内置的.mpx模板写法，确认官方使用的条件注释格式。不要凭记忆使用可能错误的注释格式。

7.4 多端构建产物差异

现象：同样一段样式，在微信端正常，在支付宝端错位。

可能原因：

• 不同平台对 CSS 属性支持不一致。
• 默认样式不同，比如button在微信和支付宝中按钮边框存在差异。
• 使用了平台特有布局属性，没有在目标平台做兼容。

处理建议：先用开发者工具的样式面板比较两个端点计算样式，优先修复默认样式差异。可以统一引入一个reset样式，在公共样式里重置button、view text等标签的默认间距。

对于真正无法统一的差异，使用条件编译把差异样式单独写在对应平台分支中。最后一定要在真实设备或开发者工具的多端模拟环境中验证，不能只改源码不验证产物。

7.5 错误排查速查表

8. 从学习到生产：扩展方向和练习建议

8.1 当前项目可以继续深入的方向

完成一个基础 MPX 项目后，你可以沿着以下方向深入：

第一，深入学习编译器原理。了解 MPX 如何把.mpx文件转换成各平台小程序代码，为什么模板静态化能提升性能，这能帮助你在遇到诡异编译问题时更快定位。

第二，研究插件和自定义构建能力。MPX 支持在构建流程中扩展自定义能力。如果你的团队有特殊需求，比如生成独立的 UI 组件包、自动上传 sourcemap、多语言切换，可以通过自定义构建插件实现。

第三，建立组件库。把业务中的通用组件逐步沉淀成内部组件库，并不一定需要完全抽象成公共库，可以先从项目内的components目录规范开始，再逐步抽离。

第四，结合小程序云开发或自建后端。将登录、权限、支付、数据存储与 MPX 项目打通，形成完整业务闭环。

8.2 发布前的检查清单

上线前建议逐项确认：

发布不是把代码上传到平台后台就结束。实际线上环境出现问题时，你还需要能快速定位。因此建议在项目中集成错误上报和日志采集，至少要在关键操作和异常分支中埋点。

8.3 新手最容易忽略的三件事

第一件是“不要只学框架，不学原生”。MPX 是基于原生小程序增强的，很多问题最终都要回到原生小程序的能力边界去判断。遇到模板渲染异常或组件更新失败时，原生小程序的调试工具、生命周期日志、setData数据量检查仍然是最可靠的排查路径。

第二件是“不要一开始就强行封装”。项目初期为了快速验证业务，直接使用原生写法没有问题。等到业务复杂度上来了，再逐步引入 store、组件集中管理、多端条件编译。过早抽象会带来大量无谓的架构代码，反而不利于项目演进。

第三件是“不要把多端当成万能”。跨端方案解决的是大部分通用场景，但小程序平台的支付、登录、分享、地图等能力仍然需要各平台单独适配。多端是降低维护成本的手段，不是消除平台差异的魔法。

学习 MPX 最有效的方式，是拿一个真实的小业务去练手，比如一个带登录、商品列表、购物车和订单页面的电商 Demo。在这个小项目中把页面、组件、store、请求封装、多端构建完整跑通，你就能理解 MPX 的每一个能力应该在什么场景使用，以及哪些地方需要继续保持原生写法。这样进入生产项目时，你看到的就不再是零散的 API，而是一条清晰的技术链路。