罗罗编程学习记录
本页内容 展开查看

07.2.4.3 条件编译与多端差异适配

所属:全栈开发面试题库 / 07 端侧与桌面开发 / 07.2 跨平台移动开发 / 07.2.4 uni-app

本节要解决的问题

  • 条件编译到底是编译期裁剪还是运行时分支,为什么它比运行时判断更彻底?
  • #ifdef、#ifndef、#endif 的语义差异,以及在 template、script、style、json 中怎么写?
  • 平台标识有哪些(APP-PLUS、APP-ANDROID、APP-IOS、H5、MP-WEIXIN、MP-ALIPAY 等),如何组合?
  • rpx 的换算机制是什么,为什么设计稿要用 750 宽?
  • 安全区、字体、滚动条、单位差异在各端怎么统一?
  • 生命周期与 API 能力差异在各端有哪些,如何兜底?
  • 如何设计适配层,把差异收敛到一处,避免条件编译散落在业务里?

版本前提:本页平台标识清单以官方文档(uniapp.dcloud.net.cn/tutorial/platform.html)为基线,具体标识名与支持范围随版本更新,标注待确认处需按项目实际版本核对。

覆盖范围

知识域 关键内容
条件编译语法 #ifdef/#ifndef/#endif、平台标识、各文件类型写法
编译期 vs 运行期 裁剪时机、产物体积、调试差异
样式适配 rpx 换算、安全区、单位、字体、滚动条
生命周期差异 应用/页面/组件在各端的时机映射
API 差异与兜底 能力缺失、返回值差异、降级策略
适配层设计 差异收敛、条件编译滥用、踩坑与排查

题号索引

题号区间 主题
001-002 条件编译概念、#ifdef/#ifndef/#endif 语义
003-004 平台标识清单、组合写法
005-007 template/script/style/json 中的条件编译
008 编译期裁剪 vs 运行时判断
009-011 rpx、安全区、单位与字体差异
012-013 生命周期差异、API 能力差异与兜底
014-016 适配层设计、条件编译滥用、典型踩坑
017-018 综合:适配层组织、样式错位排查

07.2.4.3-001 条件编译解决什么问题?

一句话结论

条件编译让同一份源码在构建时按目标端保留或裁剪代码段,是 uni-app 处理"同一功能在不同端实现不同"的核心机制;它在编译期把差异代码从产物中剔除,而不是运行时判断后分支。

概念解释

跨端框架的根本矛盾是:业务希望"一套代码",但各端 API、组件样式、布局规则、权限模型都不同。如果用运行时 if (平台 == 'weixin') 做分支,差异代码会全部打进产物,且运行时判断有分支成本、调试链路长。条件编译把这个判断提前到构建期:构建微信小程序时,非微信代码直接从产物里删掉,产物里只有微信需要的代码。

条件编译的本质是"注释式预处理":用特殊注释包裹差异代码,编译器识别这些注释,按目标端决定保留还是删除。它不是运行时功能,不会在产物里留下判断逻辑。

原理流程

源码(含条件编译注释)
   ↓ 构建目标端 = MP-WEIXIN
编译器识别 #ifdef MP-WEIXIN 块 → 保留
   ↓ 其他端块
#iifdef H5 块 → 删除(不进入产物)
   ↓
产物里只有微信需要的代码

代码或图示

方式 差异代码进入产物 运行时判断 适用
条件编译 否(裁剪) 无 端 API、组件、布局差异
运行时判断 是 有 运行时才知道的分支

常见误区

  • 误区:条件编译是运行时判断;正解:它是编译期裁剪,产物里没有被裁掉的代码。
  • 误区:条件编译能解决所有差异;正解:运行时才能确定的分支(如设备型号、屏幕尺寸)仍需运行时判断。

追问

  • Q:条件编译会增加构建时间吗?A:预处理本身成本很低,主要成本在编译器识别注释,不是构建瓶颈。
  • Q:条件编译后的产物能看到吗?A:能,构建产物目录里各端工程的代码就是裁剪后的结果。

07.2.4.3-002 #ifdef、#ifndef、#endif 的语义是什么?

一句话结论

#ifdef 平台 表示"如果是该平台则保留",#ifndef 平台 表示"如果不是该平台则保留",#endif 表示条件块结束;多平台用 || 分隔(如 #ifdef H5 || MP-WEIXIN)。

概念解释

#ifdef 是 if defined 的缩写:定义了这个平台标识就保留。#ifndef 是 if not defined:不是这个平台就保留。两者都用 #endif 收尾。多平台组合用 ||(或)连接,不能用 &&(与),因为一个构建产物只能对应一个目标端。

嵌套是允许的,但嵌套会降低可读性,建议扁平化。注意 #ifndef 容易误用:它不是"排除某平台",而是"在非该平台时保留"。

原理流程

#ifdef MP-WEIXIN
   仅微信保留
#endif

#ifndef MP-WEIXIN
   除微信外都保留(H5/App/其他小程序)
#endif

#ifdef H5 || MP-WEIXIN
   H5 或微信都保留
#endif

代码或图示

写法 语义
#ifdef MP-WEIXIN 仅微信小程序
#ifndef MP-WEIXIN 非微信(H5/App/其他小程序)
#ifdef H5 || MP-WEIXIN H5 或微信
#ifdef APP-PLUS 所有 App(Android + iOS)

常见误区

  • 误区:#ifndef MP-WEIXIN 是"在微信时不保留",用于排除微信;正解:它是"非微信时保留",语义相反但效果类似,注意命名。
  • 误区:多平台用 &&;正解:一个构建只对应一个端,&& 无意义,用 ||。

追问

  • Q:能同时判断"是 App 且是 Android"吗?A:用 #ifdef APP-ANDROID,它比 APP-PLUS 更具体。
  • Q:条件块能写多行吗?A:能,从 #ifdef 到 #endif 之间都是条件范围。

07.2.4.3-003 平台标识有哪些?

一句话结论

常用标识分四类:App 端(APP-PLUS、APP-ANDROID、APP-IOS)、H5(H5)、小程序(MP-WEIXIN、MP-ALIPAY、MP-BAIDU、MP-TOUTIAO、MP-QQ、MP-360)、快应用(QUICKAPP-WEBVIEW-*);完整清单以官方文档为准,标注待确认。

概念解释

APP-PLUS 是 App 端总称(所有 App 构建都带这个标识),APP-ANDROID 与 APP-IOS 是更细的平台标识,用于区分双端。H5 是浏览器端。MP- 前缀是各小程序平台:MP-WEIXIN 微信、MP-ALIPAY 支付宝、MP-BAIDU 百度、MP-TOUTIAO 字节跳动(抖音)、MP-QQ 腾讯 QQ。

注意:一个构建产物只会命中一个标识。构建微信小程序时,#ifdef MP-WEIXIN 命中,#ifdef H5 不命中。如果不确定某标识是否存在,查官方文档"平台支持"页,不要凭记忆写。

还有一个细节是 APP-PLUS 与 APP-ANDROID/APP-IOS 的关系:构建 Android App 时,APP-PLUS 与 APP-ANDROID 同时命中;构建 iOS App 时,APP-PLUS 与 APP-IOS 同时命中。所以"所有 App 通用"用 APP-PLUS,"仅 Android"用 APP-ANDROID,"仅 iOS"用 APP-IOS。

原理流程

构建目标端 → 命中对应标识
   ├─ App Android → APP-PLUS + APP-ANDROID
   ├─ App iOS → APP-PLUS + APP-IOS
   ├─ H5 → H5
   ├─ 微信小程序 → MP-WEIXIN
   └─ 支付宝小程序 → MP-ALIPAY

代码或图示

标识 含义 典型用途
APP-PLUS 所有 App 双端通用
APP-ANDROID Android App Android 特有
APP-IOS iOS App iOS 特有
H5 浏览器 H5 特有
MP-WEIXIN 微信小程序 微信特有
MP-ALIPAY 支付宝小程序 支付宝特有
MP-TOUTIAO 字节跳动小程序 抖音特有

常见误区

  • 误区:APP-PLUS 只指 Android;正解:它是所有 App 的总称,区分双端用 APP-ANDROID/APP-IOS。
  • 误区:一个标识名写错了编译器会报错;正解:写错通常静默不保留,不会报错,要查文档核对。

追问

  • Q:如何查某端是否支持某标识?A:官方文档"条件编译"页有完整标识表,标注待确认的以文档为准。
  • Q:App 端条件编译能区分 Android/iOS 吗?A:能,用 APP-ANDROID/APP-IOS。

07.2.4.3-004 在 template 中怎么写条件编译?

一句话结论

在 template 中用 HTML 注释包裹:<!-- #ifdef 平台 --> 到 <!-- #endif -->,包裹的标签在目标端保留,其他端从模板中删除。

概念解释

template 是 HTML/Vue 模板,条件编译用 HTML 注释语法。包裹的标签在编译时按端保留或删除,不影响 DOM 结构与事件绑定。注意:条件编译块要包裹完整标签,不能只包裹标签的一部分属性(属性级差异用 class 或 style 绑定)。

典型场景:微信小程序需要一个自定义导航栏,H5 用浏览器默认导航;用条件编译把自定义导航组件包起来,H5 端不渲染。

原理流程

<template>
  <view>
    <!-- #ifdef MP-WEIXIN -->
    <custom-navbar />
    <!-- #endif -->
    <content />
  </view>
</template>

代码或图示

写法 作用
<!-- #ifdef MP-WEIXIN --> 仅微信保留
<!-- #ifndef H5 --> 非 H5 保留
<!-- #endif --> 结束

常见误区

  • 误区:条件编译能包裹属性;正解:属性级差异用 :class 或 :style 运行时判断,模板条件编译只包裹完整标签。
  • 误区:条件编译块里能写多个标签;正解:能,但建议整块语义完整,便于阅读。

追问

  • Q:条件编译块里能写 v-if 吗?A:能,两者不冲突,但条件编译是编译期裁剪,v-if 是运行时显示。
  • Q:模板里条件编译会留空节点吗?A:被裁掉的标签完全不进入产物,不留空节点。

07.2.4.3-005 在 script 中怎么写条件编译?

一句话结论

在 script 中用 JS 注释包裹:// #ifdef 平台 到 // #endif,包裹的代码在目标端保留,其他端从 JS 产物中删除。

概念解释

script 是 JS/TS 代码,条件编译用行注释 //。典型场景:微信小程序登录用 wx.login(),App 端用 uni.login() 的 provider 参数,差异在 service 层用条件编译包裹。

注意:条件编译块里的变量、函数在其他端不存在,跨端调用时要确保两端都有对应实现,否则运行时 ReferenceError。

原理流程

// #ifdef MP-WEIXIN
const code = await wx.login()
// #endif
// #ifdef APP-PLUS
const code = await uni.login({ provider: 'weixin' })
// #endif

代码或图示

写法 作用
// #ifdef MP-WEIXIN 仅微信保留
// #ifndef H5 非 H5 保留
// #endif 结束

常见误区

  • 误区:条件编译能在函数中间包裹一段;正解:能,但要保证两端函数签名一致,否则其他端调用时函数不存在。
  • 误区:TS 里条件编译不生效;正解:TS 是编译前预处理,条件编译对 TS 同样生效。

追问

  • Q:条件编译块里 import 能裁剪吗?A:能,import 语句也可以被条件编译包裹,其他端不会引入该模块。
  • Q:如何避免两端函数签名不一致?A:在适配层定义统一接口,内部条件编译分支,业务侧只调统一接口。

07.2.4.3-006 在 style 中怎么写条件编译?

一句话结论

在 style 中用 CSS 注释包裹:/* #ifdef 平台 */ 到 /* #endif */,包裹的样式在目标端保留,其他端从样式产物中删除。

概念解释

style 是 CSS,条件编译用块注释 /* */。典型场景:微信小程序导航栏高度不同,App 端需要安全区,用条件编译写不同 padding。

注意:CSS 选择器与属性级差异也可以用条件编译,但更常见的做法是用 CSS 变量或 class 切换,条件编译只用于"完全不同的样式规则块"。

原理流程

.content {
  padding: 20rpx;
  /* #ifdef APP-PLUS */
  padding-top: 88rpx;
  /* #endif */
}

代码或图示

写法 作用
/* #ifdef MP-WEIXIN */ 仅微信保留
/* #ifndef H5 */ 非 H5 保留
/* #endif */ 结束

常见误区

  • 误区:style 里用 // 注释;正解:CSS 不支持行注释,必须用 /* */。
  • 误区:条件编译能写在 scoped style 里;正解:能,scoped 不影响条件编译。

追问

  • Q:样式差异优先用条件编译还是 CSS 变量?A:小差异用 CSS 变量或 class,大块规则差异用条件编译。
  • Q:App 端安全区样式怎么写?A:用 env(safe-area-inset-bottom) 或条件编译写固定 padding,具体以官方文档为准。

07.2.4.3-007 在 json(pages.json/manifest.json)中怎么写条件编译?

一句话结论

json 文件不支持注释,uni-app 用 /* #ifdef 平台 */ 块注释语法做条件编译,包裹 JSON 片段,构建时按端裁剪;注意逗号位置必须正确。

概念解释

pages.json 与 manifest.json 是 JSON,本身不支持注释。uni-app 提供了一种特殊的注释语法:/* #ifdef MP-WEIXIN */ 包裹 JSON 片段,编译器识别后保留或裁剪。

典型场景:微信小程序 tabBar 需要某配置,H5 不需要;用条件编译把 tabBar 的差异字段包起来。关键是 JSON 逗号:被裁掉的字段前面不能有多余逗号,否则 JSON 解析失败。

原理流程

{
  "tabBar": {
    "color": "#999",
    /* #ifdef MP-WEIXIN */
    "backgroundColor": "#fff",
    /* #endif */
    "list": []
  }
}

代码或图示

写法 作用
/* #ifdef MP-WEIXIN */ 仅微信保留
/* #endif */ 结束
逗号位置 关键,否则 JSON 解析失败

常见误区

  • 误区:json 里用 // 注释;正解:JSON 不支持行注释,用 /* */。
  • 误区:条件编译裁掉字段后逗号留着;正解:被裁掉的字段如果后面有逗号,要把逗号也包进条件块,否则 JSON 解析失败。

追问

  • Q:json 条件编译失败怎么排查?A:构建报错或配置不生效,先看 JSON 逗号,再看注释位置。
  • Q:manifest.json 也支持吗?A:支持,语法与 pages.json 一致。

07.2.4.3-008 编译期裁剪与运行时判断怎么取舍?

一句话结论

编译期条件编译用于"端确定、实现完全不同"的差异(API 调用、组件、布局);运行时判断用于"运行时才知道的分支"(设备型号、屏幕尺寸、用户配置);两者互补,不互斥。

概念解释

编译期裁剪的优势是产物干净、无分支成本;劣势是构建时才知道端,不能处理运行时变化。运行时判断的优势是灵活;劣势是差异代码全部打进产物,且有分支成本。

判断标准:如果差异在"构建时目标端"维度上就能确定(如微信 vs H5),用条件编译;如果差异在"运行时设备/环境"维度上(如 iPhone 刘海屏 vs Android 全面屏),用运行时判断(uni.getSystemInfoSync)。

原理流程

差异维度
   ├─ 构建时目标端(微信 vs H5)→ 条件编译
   ├─ 运行时设备(刘海屏 vs 普通屏)→ 运行时判断
   └─ 运行时用户配置(会员 vs 普通)→ 运行时判断

代码或图示

场景 方式
微信登录 vs App 登录 条件编译
不同刘海屏高度 运行时 getSystemInfoSync
不同 API 调用 条件编译
不同设备性能降级 运行时判断

常见误区

  • 误区:所有差异都用条件编译;正解:运行时变化的差异用运行时判断,条件编译只处理构建时端差异。
  • 误区:条件编译能减少产物体积;正解:能,被裁掉的代码不进产物,是它的核心收益。

追问

  • Q:条件编译里能调用运行时 API 吗?A:能,但条件块本身在编译期裁剪,里面的 API 在该端构建时保留。
  • Q:如何避免条件编译与运行时判断混用混乱?A:在适配层明确分层:条件编译处理端差异,运行时判断处理设备差异。

07.2.4.3-009 rpx 的换算机制是什么?

一句话结论

rpx 是响应式像素单位:750rpx = 屏幕宽度,1rpx = 屏幕宽度 / 750;设计稿按 750 宽设计时,px 直接换算成 rpx(1px = 2rpx,按 750 设计稿)。

概念解释

rpx 的设计目标是让"同一套代码在不同宽度屏幕上按比例缩放"。750rpx 对应屏幕宽度,所以 375px 宽的手机上 1rpx = 0.5px,414px 宽的手机上 1rpx ≈ 0.55px。设计稿按 750 宽出图时,设计稿上 1px = 2rpx(因为 750 设计稿对应 750rpx 屏宽)。

关键认知:rpx 是相对宽度单位,不是相对高度。竖屏布局用 rpx 按宽度缩放,横屏或高度敏感场景用 px 或 vh。

实际开发中,设计稿通常按 375pt(iPhone 逻辑分辨率)或 750px(@2x)出图。uni-app 官方推荐设计稿宽度 750,这样设计稿上 1px = 1rpx(因为 750 设计稿对应 750rpx 屏宽);如果设计稿是 375 宽,则 1px = 2rpx。换算工具有 Easy Sass 的 px2rpx 插件,或在构建时配置自动换算。

原理流程

屏幕宽度 W
   ↓
1rpx = W / 750
设计稿 750 宽:设计稿 1px = 2rpx
设计稿 375 宽:设计稿 1px = 1rpx

代码或图示

设计稿宽度 1px 对应 rpx
750 2rpx
375 1rpx
1125(@2x) 4rpx

常见误区

  • 误区:rpx 是相对高度;正解:它是相对宽度,高度敏感场景用 px 或 vh。
  • 误区:rpx 在所有端都一样;正解:rpx 在各端换算逻辑一致,但各端 WebView 渲染可能有 1px 偏差,需真机核对。

追问

  • Q:字体大小用 rpx 还是 px?A:字体建议用 rpx 保持比例,但小屏手机字会太小,可配合 px 下限。
  • Q:H5 端 rpx 怎么算?A:H5 端按视口宽度换算,与小程序一致。

07.2.4.3-010 安全区(状态栏、底部 Home 条)怎么适配?

一句话结论

App 端与小程序端都有状态栏、底部 Home 条、刘海屏等安全区问题;uni-app 提供 uni.getSystemInfoSync() 获取状态栏高度,样式用 env(safe-area-inset-bottom) 或条件编译写固定 padding。

概念解释

安全区分三类:顶部状态栏(时间、信号)、底部 Home 条(iPhone X 及以后)、刘海/挖孔(顶部摄像头)。App 端 vue 页默认从状态栏下方开始渲染(取决于 pages.json 的 navigationStyle),如果自定义导航需要手动加状态栏高度。

获取方式:uni.getSystemInfoSync().statusBarHeight 拿到状态栏高度(单位 px),在样式里用 padding-top 加。底部安全区用 CSS env(safe-area-inset-bottom),各端支持情况不同,不支持时用固定值兜底。

实际开发中更稳妥的做法是在 onLaunch 时调用一次 uni.getSystemInfoSync(),把 statusBarHeight、safeArea 等信息存到 Pinia store 或全局变量,页面里直接读取,避免每个页面重复调用。自定义导航组件在内部统一处理状态栏高度,业务页面不感知。

原理流程

uni.getSystemInfoSync()
   ├─ statusBarHeight:顶部状态栏高度
   ├─ safeArea:安全区域(top/bottom/left/right)
   └─ 屏幕宽高
样式:padding-top: statusBarHeight + 'px'
      padding-bottom: env(safe-area-inset-bottom)

代码或图示

场景 适配方式
自定义导航 statusBarHeight + 导航高度
底部按钮 env(safe-area-inset-bottom)
刘海屏内容避开 safeArea.top/bottom
H5 端 浏览器顶部有地址栏,需额外处理

常见误区

  • 误区:所有端状态栏高度一致;正解:Android/iOS/小程序各有差异,必须运行时获取。
  • 误区:env(safe-area-inset-bottom) 所有端都支持;正解:小程序与 H5 支持情况不同,需真机核对,不支持时用固定值兜底。

追问

  • Q:pages.json 里怎么配沉浸式?A:navigationStyle: custom 让页面自定义导航,然后手动加状态栏高度。
  • Q:H5 端安全区怎么处理?A:H5 顶部是浏览器地址栏,不是安全区问题,是布局避让问题,用 CSS 或 JS 获取高度。

07.2.4.3-011 单位差异、字体与滚动条怎么统一?

一句话结论

单位差异主要在 rpx(跨端响应式)与 px(固定)之间;字体在各端默认字体不同,滚动条在 H5 与 App 表现不同;统一用 CSS 变量与条件编译处理。

概念解释

rpx 与 px 的取舍:响应式布局用 rpx,固定尺寸(图标、按钮最小高度)用 px。字体:各端默认字体不同(iOS 用系统字体,Android 用 Roboto,小程序有平台字体),跨端统一用 font-family 显式指定,或用系统字体栈。

滚动条:H5 端默认显示滚动条,App 端 vue 页 WebView 默认隐藏或样式不同,小程序端 scroll-view 有滚动条样式配置。需要自定义滚动条时用 CSS ::-webkit-scrollbar 或平台 API。

原理流程

响应式尺寸 → rpx
固定尺寸 → px
字体 → font-family 显式指定
滚动条 → CSS 或平台 API

代码或图示

差异点 处理方式
单位 rpx 响应式,px 固定
字体 font-family 显式指定
滚动条 CSS 或平台 API
边框 1px 各端渲染差异,用 transform scale 或 0.5px

常见误区

  • 误区:所有尺寸都用 rpx;正解:固定尺寸(如图标、按钮最小高度)用 px,避免 rpx 缩放导致不可点。
  • 误区:字体不用指定;正解:各端默认字体不同,显式指定保持一致。

追问

  • Q:1px 边框在各端为什么看起来粗?A:各端屏幕像素密度不同,1px 物理像素 vs 逻辑像素,用 transform scale(0.5) 或 hairline 方案。
  • Q:小程序端滚动条怎么隐藏?A:scroll-view 的 show-scrollbar 属性或 CSS,具体以官方文档为准。

07.2.4.3-012 生命周期在各端有什么差异?

一句话结论

uni-app 的应用生命周期(onLaunch/onShow/onHide)、页面生命周期(onLoad/onShow/onReady/onHide/onUnload)、组件生命周期(Vue 标准)在各端映射到对应平台机制,但时机与触发频率有差异。

概念解释

应用生命周期:onLaunch 在启动时触发一次,onShow 在 App 切前台时触发,onHide 在切后台时触发。各端差异:小程序端 onLaunch 是冷启动,App 端 onLaunch 同样是冷启动,但 H5 端 onLaunch 对应页面加载。

页面生命周期:onLoad 在页面加载时触发(接收参数),onShow 在页面显示时触发,onReady 在页面初次渲染完成时触发,onHide 在页面隐藏时触发,onUnload 在页面卸载时触发。关键差异:tab 页切换时 onShow 触发但 onLoad 不触发;navigateTo 新页面时旧页面 onHide 但不 onUnload。

组件生命周期:Vue 标准(beforeCreate/created/mounted 等),各端一致。

还有一个常见差异是 onReady 与首屏渲染:App 端 vue 页 onReady 触发时机与 WebView 加载完成相关,小程序端 onReady 在首次渲染完成后触发,H5 端 onReady 对应 DOMContentLoaded。首屏数据加载建议在 onLoad 里发请求,不要在 onReady,否则会白屏更久。

原理流程

应用启动:onLaunch → onShow
页面进入:onLoad → onShow → onReady
页面切后台:onHide
页面返回:onShow
页面关闭:onUnload

代码或图示

生命周期 触发时机 各端差异
onLaunch 应用启动一次 冷启动,各端一致
onShow 应用切前台 切后台回前台触发
onHide 应用切后台 切后台触发
onLoad 页面加载(带参数) tab 页只首次触发
onShow 页面显示 tab 页切换也触发
onReady 页面初次渲染完成 只触发一次
onUnload 页面卸载 redirectTo/navigateBack 触发

常见误区

  • 误区:onShow 每次页面进入都触发 onLoad;正解:tab 页切换只触发 onShow,onLoad 只首次。
  • 误区:组件卸载定时器自动停;正解:要在 onUnload/beforeUnmount 里手动 clearInterval。

追问

  • Q:onLoad 里能拿到页面参数吗?A:能,onLoad(options) 接收路由参数。
  • Q:App 切后台再回前台触发什么?A:应用级 onShow,不是页面 onShow。

07.2.4.3-013 API 能力差异与兜底方案怎么做?

一句话结论

同一 uni.xxx API 在各端支持情况不同,返回值与错误码也可能不同;兜底方案是:先查官方平台支持表,不支持的端做条件编译降级或隐藏入口,运行时用 uni.canIUse 或 try-catch 兜底。

概念解释

每个 uni API 在官方文档都有"平台支持"表格,标注 H5/App/各小程序是否支持。不支持的端调用会报错或返回 fail。兜底策略分三层:

  1. 编译期:条件编译,不支持的端不调用该 API;
  2. 运行时:uni.canIUse('xxx') 判断能力是否可用,不可用则降级;
  3. 错误兜底:调用 fail 回调或 try-catch,给用户友好提示。

返回值差异也要注意:同一 API 在不同端的 success/fail 回调参数可能不同,错误码也不同,业务侧不要硬编码错误码。

原理流程

调用 uni.xxx
   ↓
查平台支持表
   ├─ 支持 → 直接调用
   ├─ 不支持 → 条件编译或 canIUse 判断
   └─ 失败 → fail 回调兜底

代码或图示

兜底方式 时机 适用
条件编译 编译期 端完全不支持
uni.canIUse 运行时 同端不同版本差异
fail 回调 运行时 调用失败
try-catch 运行时 同步 API 异常

常见误区

  • 误区:所有端都支持所有 API;正解:每个 API 都有平台支持表,调用前必须查。
  • 误区:硬编码错误码判断;正解:错误码各端不同,用 fail 回调统一处理。

追问

  • Q:uni.canIUse 怎么用?A:uni.canIUse('getSystemInfoSync') 返回布尔,判断 API 是否可用。
  • Q:不支持的 API 怎么降级?A:隐藏入口、用替代 API、或给用户"暂不支持"提示。

07.2.4.3-014 如何设计多端适配层?

一句话结论

适配层把"端差异"收敛到统一接口后面:业务层调 auth.login(),适配层内部按端条件编译调微信登录/App 登录;业务代码不感知端差异,差异只存在于适配层。

概念解释

典型适配层分三类:服务适配(登录、支付、分享)、组件适配(跨端一致组件)、样式适配(统一设计 token)。

服务适配:定义 auth.ts 暴露 login()、getUserInfo(),内部 #ifdef 调各端 API。业务组件只 import { login } from '@/service/auth',不写条件编译。

组件适配:把跨端表现不一致的组件(如自定义导航、列表、弹窗)封装成统一组件,内部处理端差异。

样式适配:用 CSS 变量统一设计 token(颜色、间距、圆角),各端覆盖变量值。

还有一个常见做法是"能力检测层":定义一个 platform.ts 模块,导出 isWeixin、isApp、isH5 常量(基于条件编译),业务组件需要时引入判断,但这种运行时判断仍要谨慎使用,优先用条件编译在编译期裁剪。

原理流程

业务层:import { login } from '@/service/auth'
适配层:auth.login()
   ↓
#ifdef MP-WEIXIN → wx.login()
#ifdef APP-PLUS → uni.login()
#ifdef H5 → 自定义登录

代码或图示

适配层类型 职责 示例
服务适配 登录/支付/分享 auth.ts
组件适配 跨端一致组件 custom-navbar
样式适配 设计 token CSS 变量

常见误区

  • 误区:业务代码里到处写条件编译;正解:差异收敛到适配层,业务侧零端判断。
  • 误区:适配层只做服务;正解:组件与样式差异也要收敛。

追问

  • Q:适配层放在哪个目录?A:项目 src/adapter/ 或 src/service/,按职责分文件。
  • Q:如何避免适配层变成大杂烩?A:按领域分文件(auth/pay/share/storage),每个文件职责单一。

07.2.4.3-015 条件编译滥用带来什么问题?

一句话结论

条件编译散落在业务代码各处会导致:可读性差(看不出某段代码在哪端生效)、维护成本高(改一个功能要改多个端分支)、测试覆盖难(每个端都要回归)、新增端时要改所有散落点。

概念解释

典型滥用场景:一个组件里写 5 处 #ifdef,一个 service 里每个方法都写条件编译,业务页面里直接 uni.xxx 然后包条件编译。后果是:新人接手看不懂,改一个功能要在 4 个端分支里同步,测试时每个端都要回归一遍。

正确做法是"差异收敛":条件编译只出现在适配层,业务代码零端判断。如果发现业务页面里有条件编译,说明该差异应该被抽象到适配层。

原理流程

滥用:业务页面 → 直接 #ifdef → 多处散落
正确:业务页面 → 适配层接口 → 适配层内部 #ifdef

代码或图示

滥用信号 后果
业务页面有 #ifdef 可读性差
一个组件多处 #ifdef 维护难
改功能要改多个端分支 测试成本高
新增端要改所有散落点 扩展成本高

常见误区

  • 误区:条件编译越多越灵活;正解:条件编译是技术债,越多越难维护。
  • 误区:小项目可以不收敛;正解:小项目从一开始就该收敛,否则长大更难收拾。

追问

  • Q:如何判断条件编译是否滥用?A:业务代码(页面、组件)里出现 #ifdef 就是滥用,应该收敛到适配层。
  • Q:适配层有条件编译正常吗?A:正常,适配层就是为了收敛差异。

07.2.4.3-016 条件编译的典型踩坑有哪些?

一句话结论

常见踩坑:平台标识名写错(静默不生效)、json 条件编译逗号位置错(JSON 解析失败)、条件编译块里的变量在其他端不存在(ReferenceError)、嵌套过深难读、混淆编译期与运行时判断。

概念解释

一是标识名写错:如写成 #ifdef WEIXIN 而不是 #ifdef MP-WEIXIN,编译器不报错但代码不保留,难排查。二是 json 逗号:被裁掉的字段后面逗号留着,JSON 解析失败。三是变量作用域:条件编译块里定义的变量在其他端不存在,其他端引用时 ReferenceError。

四是嵌套:#ifdef 套 #ifdef,可读性差,建议扁平化。五是混淆编译期与运行时:用条件编译处理运行时设备差异,导致其他端没有该分支。

原理流程

踩坑排查:
   代码不生效 → 查标识名拼写
   JSON 报错 → 查逗号
   ReferenceError → 查条件块变量
   样式错位 → 查条件编译是否裁掉该端

代码或图示

踩坑 表现 排查
标识名错 代码不生效 查官方标识表
JSON 逗号 构建失败 查条件块前后逗号
变量未定义 ReferenceError 查其他端是否有同名变量
嵌套过深 难读 扁平化

常见误区

  • 误区:条件编译写错编译器会报错;正解:标识名错通常静默不生效,要靠测试发现。
  • 误区:条件编译块里定义的函数其他端能用;正解:其他端没有该函数,要在两端都定义或用统一接口。

追问

  • Q:如何避免标识名写错?A:把常用标识定义成常量或注释,团队统一查文档。
  • Q:条件编译块里 import 其他端不存在的模块怎么办?A:把 import 也包进条件编译,或在适配层统一引入。

07.2.4.3-017 综合题:业务方要做"一套代码四端跑",怎么组织适配层?

一句话结论

按四步组织:列端差异清单(API/组件/样式/权限)、建适配层目录(service/adapter/component)、把条件编译收敛到适配层、业务代码零端判断;最后每端真机回归。

概念解释

第一步列差异清单:把所有端差异点列出来(登录、支付、分享、导航、列表、弹窗、权限)。第二步建目录:src/adapter/ 下按领域分文件(auth.ts、pay.ts、share.ts、navbar.vue)。第三步收敛:把每个差异点的条件编译写在适配层,业务侧调统一接口。第四步回归:每端真机跑核心链路。

关键原则:业务代码(页面、业务组件)里不出现 #ifdef,所有端差异在适配层。如果业务里出现条件编译,说明该差异应该被抽象。

原理流程

1. 列差异清单(登录/支付/分享/导航/列表/权限)
2. 建适配层目录
3. 收敛条件编译到适配层
4. 业务侧调统一接口
5. 每端真机回归

代码或图示

步骤 产出
差异清单 端差异点列表
适配层 adapter/auth.ts、adapter/pay.ts
业务调用 业务页面 import 统一接口
回归 四端真机跑核心链路

常见误区

  • 一上来就写业务,差异后期补;正解:先列差异清单与适配层,再写业务。
  • 业务代码里有条件编译;正解:那是适配层没收敛干净,重构掉。

追问

  • Q:适配层太重怎么办?A:按领域分文件,只收敛高频差异,低频差异用条件编译兜底。
  • Q:如何验收适配层?A:grep 业务代码里 #ifdef,出现就是没收敛干净。

07.2.4.3-018 综合题:某端样式错位,怎么排查?

一句话结论

按五步排查:先确认是哪一端错位(H5/App/某小程序),再看是布局错(rpx 换算)还是组件错(平台渲染差异),再看条件编译是否裁掉了该端样式,最后真机核对与设计稿。

概念解释

排查顺序:一是确认端:只 H5 错还是所有端错?只 H5 错是浏览器差异,所有端错是设计稿理解错。二是确认类型:布局错(位置、大小)还是组件错(按钮、弹窗样式)?三是查条件编译:是否某端样式被裁掉了。四是查单位:rpx 在该端换算是否正确,1px 边框是否 hairline 问题。五是真机核对:模拟器与真机可能不同,必须真机看。

常见原因:rpx 在不同宽度屏幕换算偏差、1px 边框在不同像素密度手机上表现不同、条件编译裁掉了该端样式、组件在各端默认样式不同。

原理流程

样式错位
   ↓
1. 哪端错? ── 仅 H5 → 浏览器差异
   │         所有端 → 设计稿理解错
   ↓
2. 布局错 or 组件错?
   ↓
3. 条件编译是否裁掉该端样式?
   ↓
4. rpx 换算 / 1px 边框 / 字体
   ↓
5. 真机核对

代码或图示

症状 可能原因 处置
仅 H5 错位 浏览器差异 CSS 兼容写法
所有端错位 设计稿理解错 核对设计稿
1px 边框粗 像素密度 hairline 方案
rpx 缩放偏差 屏宽差异 用 px 固定关键尺寸
组件样式不同 平台默认样式 条件编译覆盖

常见误区

  • 只看模拟器不看真机;正解:模拟器与真机渲染不同,必须真机核对。
  • 样式错位就改 CSS;正解:先查条件编译是否裁掉了该端样式。

追问

  • Q:如何快速定位是 rpx 还是组件问题?A:把该元素固定 px 看是否对齐,对齐就是 rpx 换算问题,不对齐就是组件渲染差异。
  • Q:H5 端样式与 App 端差异大怎么办?A:H5 有浏览器默认样式(如按钮、input),用 reset CSS 或条件编译覆盖。