结论先行:uni-app 的条件编译是编译期机制,不是运行期判断。用注释形式的 #ifdef / #ifndef 把平台差异代码隔离在适配层,业务层保持平台无关,就能用一套代码稳定发布微信小程序、支付宝小程序、H5 与 App。关键纪律有三条:平台标识写对、差异代码集中管理、静态资源按平台目录隔离。配合统一的后端 SDK(如 apifm-uniapp),多端项目的维护成本可以压到接近单端。
一、条件编译的工作原理
uni-app 在编译阶段扫描代码中的特殊注释,按目标平台保留或剔除代码块。也就是说,打包微信小程序时,H5 专属代码根本不会进入产物,既不占包体积,也不存在运行期分支开销。这与在代码里写 if 判断平台有本质区别:后者所有平台的代码都会被打进包里。
基本语法是注释包裹:
// #ifdef MP-WEIXIN
console.log('这段只在微信小程序里存在')
// #endif
// #ifndef H5
console.log('除了 H5 之外的平台都会保留')
// #endif多个平台用两个竖线表示「或」:// #ifdef MP-WEIXIN || MP-ALIPAY。注意这是编译期符号,不是 JS 的逻辑或,写在普通表达式里无效。
二、常用平台标识速查
| 标识 | 目标平台 |
|---|---|
| MP-WEIXIN | 微信小程序 |
| MP-ALIPAY | 支付宝小程序 |
| MP-TOUTIAO | 抖音小程序 |
| MP-QQ | QQ 小程序 |
| H5 | Web / H5 |
| APP-PLUS | App(HTML5+ 运行时) |
| APP-HARMONY | 鸿蒙 App(以官方文档为准) |
| MP | 所有小程序平台 |
模板与样式同样支持条件编译,只是注释形式不同:模板用 <!-- #ifdef H5 --> 包裹,CSS 用 /* #ifdef APP-PLUS */ 包裹。pages.json 里也可以按平台写差异化配置,例如各端导航栏样式。
三、实战:支付能力的多端适配
支付是差异最典型的能力:微信小程序走 uni.requestPayment,支付宝小程序走 uni.tradePay,App 端走原生支付模块,H5 端通常跳转收银台。正确姿势不是把四种写法散落在页面里,而是封装一个平台适配层:
// utils/pay.js
export function pay(orderInfo) {
// #ifdef MP-WEIXIN
return uni.requestPayment({
provider: 'wxpay',
timeStamp: orderInfo.timeStamp,
nonceStr: orderInfo.nonceStr,
package: orderInfo.packageValue,
signType: orderInfo.signType,
paySign: orderInfo.paySign
})
// #endif
// #ifdef MP-ALIPAY
return uni.tradePay({ tradeNO: orderInfo.tradeNO })
// #endif
// #ifdef H5
window.location.href = orderInfo.cashierUrl
return Promise.resolve()
// #endif
}业务页面只调用 pay(orderInfo),完全不感知平台。登录、分享、文件选择等能力同理。团队应约定:所有 #ifdef 只允许出现在 utils 或 platform 目录,页面里出现条件编译视为代码评审不通过。
四、静态资源与配置的多端隔离
除了代码,资源也要隔离。uni-app 支持 static 目录下按平台建子目录,例如 static/mp-weixin 里的图片只在微信小程序打包时保留,避免把各端的启动图、图标全塞进每个产物。pages.json 中可以用条件编译为不同端配置不同的 tabBar 与页面集合,比如 H5 端多一个下载引导页,小程序端去掉外链页面。
分包策略也要按端处理:微信小程序主包有体积上限,订单、个人中心等低频模块拆进分包并配置预加载;H5 端则更关注首屏资源体积与路由懒加载。同一套 pages.json 通过条件编译即可表达两种策略。
五、用 apifm-uniapp 统一多端数据层
条件编译解决的是「端能力差异」,而用户、商品、订单这些业务数据应该全端一致。这一层可以直接交给现成 SDK:api工厂提供的 apifm-uniapp 覆盖微信/支付宝/抖音小程序、H5 与 App,初始化后各端调用同名方法即可:
import WXAPI from 'apifm-uniapp'
WXAPI.init('你的专属子域名')
const res = await WXAPI.goodsList({ page: 1, pageSize: 10 })
if (res.code === 0) {
this.goods = res.data
}所有接口统一返回 code、data、msg,code 为 0 表示成功。因为后台是同一套(api工厂,https://www.it120.cc/),小程序里下的订单,H5 与 App 登录同一账号就能看到,天然实现「一套数据多端复用」。SDK 的完整方法列表见官方文档(https://www.it120.cc/sdk/index.html),开源示例 uni-app-mall 可以直接当多端商城脚手架用。
六、多端发布前的检查清单
最后给一份可直接执行的清单:一是全局搜索 #ifdef,确认没有拼错的标识(拼错不会报错,代码会被静默剔除,这是最隐蔽的坑);二是每端真机过一遍登录、支付、分享三条主链路,H5 端额外验证微信内置浏览器的授权登录;三是检查各端包体积,小程序超限时优先拆分包而不是删功能;四是确认后端接口域名已加入各小程序平台的合法域名列表,H5 端处理好跨域;五是把平台差异集中在适配层后,为每个适配函数补上各端的冒烟测试。做到这五条,一套代码四端发布才算真正可维护。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。