uni-app 跨端工程实战：平台差异、适配层与发布验证

把官方资源、开源项目、组件、工具、文章和应用案例转成 H5/小程序/App 的架构、兼容和真机验收方法。

本文围绕 aben1188/awesome-uni-app 做原创工程整理。项目来自 腾讯新闻前端团队 2022 年的 25 个 Awesome 项目推荐；上游 README 固定到 commit 0bfb7e2d099dfba9b40326909a9bfb637b040b8f（2020-11-08）；含约 149 行外链记录，仓库没有 SPDX 许可声明。 下方保留固定版本入口。

仓库内容地图

• 官方资源和特别说明：先确定当前支持的平台、运行时与版本
• 开源项目：比较应用结构、页面组织和多端差异
• 开源组件：检查端能力、样式适配与可访问性
• 工具与文章：构建、调试、发布和性能排查
• 应用案例：观察真实业务如何处理平台差异

怎么读才有收获

上游 README 固定快照发布于 2020-11-08，列出多平台资源、组件、项目和应用案例。把跨端理解为“共享业务 + 宿主适配”：先画能力矩阵，再检查编译器、运行时、权限、路由和发布条件。

跨端不是“同一份代码处处一样”

uni-app 采用编译器与目标运行时协作的模式：同一份 Vue 单文件组件会编译成 H5、小程序或 App 所需的产物，再由各宿主运行时提供视图、导航和平台 API。共享的是业务意图与大部分页面逻辑，不是浏览器 DOM、平台权限、支付能力、文件路径、审核规则和性能预算。跨端项目要把“共用路径”和“平台适配层”同时设计出来。

本篇依据 2020-11-08 的 awesome-uni-app 固定快照，将官方资源、开源项目、组件、工具、文章和应用案例改造成一套工程核验方法。快照中的平台说明和库名很旧；当前平台能力以 DCloud 与各目标平台官方文档为准，不能把旧 README 当作当下支持承诺。

1. 先区分编译器、运行时和宿主能力

“一套代码多端运行”只代表框架能生成多种目标产物，不表示任意插件、第三方 SDK 或业务功能能无改动覆盖每端。H5 可以用浏览器 API，不代表小程序有 window/DOM；原生 App 的文件路径也不能直接当作后端可访问的 URL。

2. 把上游目录变成可执行的评估清单

原 README 的可用内容包括官方资源与特别说明、开源项目、开源组件、开发工具、技术文章和应用案例。读这些目录时按如下问题筛选：

• 官方资源：当前产品是否仍在支持？其平台和运行时版本边界是什么？
• 开源项目：是否给出构建脚本、目标平台、真机截图和复现步骤？
• 开源组件：依赖哪些原生 API？是否处理键盘、safe area、无障碍与窄屏？
• 工具：是调试/打包工具，还是只是资源聚合？升级是否与当前 CLI/HBuilderX 匹配？
• 文章：发布日期、框架版本和平台是否明确？将旧配置迁移到当前版本需要改什么？
• 应用案例：区分“能启动”与真实发布；检查登录、网络、上传、支付、权限和审核链路。

源仓库还含推广、兼职/外包和联系方式内容，这些不是技术文档，也不适合搬进个人知识文章。本篇只整理工程问题，不复制联系人、广告或链接目标正文。

3. 用一张矩阵设计多端产品

这张表不是通用兼容承诺。每一格都应落到目标平台、最低版本、真机型号、功能降级方案和测试责任人。跨端验收不仅看页面能打开，还要验证授权结果、错误码、取消流程、后台恢复与网络中断。

4. 隔离差异，避免条件编译散落全仓

官方条件编译可以处理组件、API、样式、路由配置和整页平台差异；它是编译期切分，不是运行时能力检测。将平台差异集中在 platform/ 或 adapters/，业务层依赖统一接口；只在确实存在宿主能力差异的模块中使用条件编译，并确保各目标裁剪后的代码仍可编译。

export function normalizePlatformError(error = {}) {
  return {
    code: String(error.errCode ?? error.code ?? 'UNKNOWN'),
    message: String(error.errMsg ?? error.message ?? '操作失败'),
  };
}

// 平台模块把各宿主的原始错误先转成稳定契约；
// 页面只处理统一错误类型，不在业务组件里散落平台判断。

条件编译示意：

// #ifdef MP-WEIXIN
console.info('mini-program-only capability');
// #endif
// #ifdef H5
console.info('browser-only capability');
// #endif

同一文件中的平台宏一旦扩散，会让组合数量迅速增长。尽量通过能力适配器、平台专属文件和配置把差异封装起来；统一接口无法表达的能力，应该显式返回“不支持”并给用户可理解的降级，而不是静默 no-op。

5. 页面生命周期与资源回收

页面从路由入栈到返回、切换 tab、重加载会经历不同生命周期。返回上一页时，页面可能只是重新显示而非重新创建；把请求只写在初次加载钩子里可能读到旧数据。定时器、WebSocket、事件监听、上传任务和页面级订阅要在隐藏、卸载或账号切换时按需求暂停/取消并清理。页面关闭不会自动取消所有网络请求或 timer。

列表页要按真实目标设备检查首屏节点数、图片尺寸、长列表回收、过度 setData/响应式更新和低内存恢复。布局用统一设计 token 和安全区域变量，但不把 rpx 当成万能响应式方案；小屏键盘、横屏、大字模式、刘海和软键盘遮挡都需要真机测试。

6. 网络、登录、上传和权限不是 UI 细节

封装统一请求层，包含 base URL 环境切换、超时/取消、状态码映射、请求 ID、重试规则和安全日志。重试只用于可重试的读操作或有幂等键的写操作；上传进度和取消要通过各平台真实能力验证。客户端做的权限隐藏只改善体验，所有敏感读取、下载、订单和账户操作仍由服务端验证身份与对象权限。

文件上传使用平台选择器拿临时路径后调用对应上传能力；后端重新验证文件内容、用户归属、大小、病毒/解析边界和存储权限。域名白名单、隐私声明、相机/相册授权文案和平台审核规则随平台而变，必须在各家开发者控制台完成，不可从客户端代码推导“已经有授权”。

7. 构建矩阵、发布和回归

至少为 H5、主要小程序目标和 App 建立独立构建任务；不同环境使用明确的 API host、应用标识、签名、隐私配置和源映射策略。产物构建通过后，还要在真实平台开发者工具/真机上检查登录、导航、网络、上传、分享、返回、分包、冷启动和升级。不能用一个 H5 Playwright 通过就宣称所有宿主兼容。

• 构建：锁定 node/CLI/HBuilderX/编译器和插件版本，构建结果可重现。
• 设备：覆盖 iOS/Android 目标版本、低端机、不同屏幕、安全区域和系统字号。
• 平台：至少用平台官方开发者工具做基础冒烟；关键链路做真机验证。
• 合规：检查隐私清单、权限说明、平台域名白名单、应用签名和上架政策。
• 网络：覆盖弱网、断网、请求超时、重复提交、取消、登录过期与服务端错误。
• 回滚：保留上一版包、版本映射、后端兼容窗口和可观测的发布指标。

官方参考

• uni-app 组成和跨端原理
• uni-app 条件编译
• 页面、生命周期与页面栈
• uni.uploadFile 与平台差异
• uni-app package.json 与多端构建配置

快照与使用边界

该上游 README 固定在 commit 0bfb7e2d099dfba9b40326909a9bfb637b040b8f（2020-11-08），含 149 行外链记录和大量旧版平台介绍。GitHub 未声明 SPDX 许可证，仓库根目录没有 LICENSE；本文保留技术主题范围与固定源入口，但不复制 149 条资源描述、宣传内容或第三方文章。平台支持和审核规则会变化，发布前必须对照目标端官方当前文档。

动手路线

1. 做登录、列表、详情、文件上传四条业务流，分别跑 H5、小程序和至少一个 App 目标。
2. 给请求、文件、导航和系统权限建立平台适配契约，并测试不支持能力的显式降级。
3. 在目标端真机覆盖弱网、键盘、安全区域、冷启动、取消操作和账号切换。

使用边界

上游仓库无 SPDX 许可声明且根目录没有 LICENSE；本文不复制其 149 条资源说明、广告/联系方式或第三方文章。平台和工具版本均需按当前 DCloud 与宿主官方文档核验。

原始入口

• 固定版本 README 与仓库入口
• 发现这份资源的原始推荐
• 返回 25 个开源项目专题目录