在开发圈里摸爬滚打这几年，跨端需求越来越多，我接触过不少从零搭建的小程序，也维护过好几个同时要出 App、小程序和 H5 的项目。手写三套代码的酸爽，经历过的人都懂。后来项目组引入 uni-app，我把常用组件和 API 系统地过了一遍，才发现一套 Vue 语法能省下这么多事情。这篇就把我实际用的最多的组件和 API 挑出来，结合踩过的坑，讲清楚它们怎么用、为什么要这么用，给正准备上 uni-app 的开发者一个可以直接照着参考的路线。

uni-app 是基于 Vue.js 的跨端应用框架，核心价值是一套代码编译到多端，包括 iOS、Android、小程序和 H5。它把各平台的差异尽量封装在框架层，开发者用统一的组件标签和 uni.xx 风格的 API 来写业务逻辑。适合谁？如果你要同时维护小程序和 App，或者团队人手不够、业务又要求多端同步上线，uni-app 是目前投入产出比相当高的选择。当然它也不是万能，重度依赖原生能力的项目要谨慎，后面我会讲清楚边界。

1. 整体思路：为什么选 uni-app，开发前需要想清楚的事

1.1 uni-app 的选型逻辑：它解决的是“维护成本”问题

跨端开发最大的成本不是“写第一版”，而是“改第二版”。我第一次尝试在原生小程序里加一个功能，改完还得同步改 App 端的代码，两边的样式和逻辑还因为平台差异有细微不同，改起来相当痛苦。uni-app 的思路是把 nvue、Vue 组件、条件编译这些机制组合起来，用大部分业务代码共享、少数平台差异用条件编译隔离的方式，把维护成本降下来。

选型时我主要看三个维度：团队技术栈、业务形态、发布节奏。团队熟 Vue，那学习曲线几乎为零；业务主要是表单、列表、详情、个人中心这类常规页面，uni-app 的组件和 API 覆盖得很全；发布节奏要求快，多端同步，那 uni-app 的编译链路能省掉大量重复联调时间。如果你的业务里有很重的实时音视频、复杂动画、深度硬件交互，这些还是建议走原生或者专业方案，框架在这块会有性能和功能上的天花板。

还有一个容易忽略的点：uni-app 的生态。官方插件市场里有人做好的模板、原生插件、组件库，能直接拿过来用。我自己经常会先上插件市场搜一圈，估一下有没有现成方案，再决定要不要自己写。这个动作对排期影响很大，尤其是 App 端原生能力调用，有现成模块能省不少事。

1.2 工程结构、IDE 选择与项目初始化实操

创建 uni-app 项目有两条路：HBuilderX 图形化创建，或者用命令行 vue-cli / vite 创建。我实际工作中大多数人用 HBuilderX，因为它内置了运行、调试、打包到多端的完整工具链，真机预览也方便。但如果你是团队协作、需要接入自己的 CI/CD 流程，那用 CLI 初始化、配合 Git 管理更合适。我自己的偏好是 CLI + Vite + Vue3，原因很简单：构建速度快，依赖可控，代码评审和发布流程跟常规前端项目一致。

工程目录很关键，默认结构至少包含 pages（页面）、static（静态资源）、components（自定义组件）、uni_modules（扩展模块）、manifest.json（应用配置）、pages.json（页面路由与导航配置）、App.vue（应用入口）。刚开始容易搞混的是 manifest.json 和 pages.json，一个管应用级别，一个管页面路由和 tabBar，改错了会出奇奇怪怪的问题，建议第一件事就把这两个文件的字段过一遍。

初始化项目时我一般这样操作：先创建项目跑通一个默认页面，然后把 pages.json 里不需要的示例页面清掉，再配置好 tabBar 的图标和页面路径，最后设置 App.vue 里的全局样式。这个流程虽然简单，但能避免后期页面多了再改 tabBar 导致的路由混乱。还有个小建议：pages.json 里页面 path 首字母必须是大写规范还是小写规范，官方默认是小写开头，保持统一就行，别混用。

注意：CLI 创建的项目和 HBuilderX 创建的项目在部分原生插件集成方式上有差异，确定一种方式就固定用下去，来回切换容易遇到手动配置插件的坑。

2. 常用组件：视图容器与基础内容组件的使用细节

2.1 view、scroll-view、swiper：三大视图容器的跨端适配要点

view 就是网页里的 div，但在 uni-app 里它有了更明确的定义，包括 hover-class 点击态、flex 布局等。我常用的写法是在 view 上加 hover-class 做点击反馈，比如列表项按下变灰。这里有个小坑：H5 端 hover-class 默认生效，但小程序端需要配置 hover-start-time 和 hover-stay-time 才有预期的点击效果，所以做交互反馈时最好自己定义这些参数。

scroll-view 用于可滚动区域，注意它跟页面级滚动是两回事。横向滚动必须给 scroll-view 一个确定的宽度，内容宽度超过容器才会滚动；纵向滚动则要给确定的高度，否则内容会直接撑开整个页面。早期我吃过亏，以为放进去的内容会自动参与滚动，结果在真机上完全不滚，后来发现是高度没限定。小程序端还有 enable-flex 属性，想要 scroll-view 内部用 flex 布局就得打开，但 H5 端默认就能 flex，这属于典型的跨端样式差异。

swiper 做轮播是最常用的。它的宽高由外部容器决定，swiper-item 默认宽度 100%。我需要提醒的是 swiper 的高度坑：如果轮播内容是图片，建议直接给 swiper 设定高度。用 auto 属性可以按内容自适应，但真机和模拟器上偶尔表现不一致，稳妥方案是拿到图片宽高后计算高度，或者在 onLoad 里读取第一张图的宽高来动态设置 swiper 高度。autoplay 默认是 false，要做自动轮播记得开，同时配好 interval 和 circular。

<swiper :indicator-dots="true" :autoplay="true" :interval="3500" :circular="true" style="height: 400rpx;"> <swiper-item v-for="(item, index) in bannerList" :key="index"> <image :src="item.imageUrl" mode="aspectFill" /> </swiper-item> </swiper>

这段代码是标准的动态 banner 轮播，重点在 mode="aspectFill" 防止图片变形，配合固定高度可以避免页面左右滑动导致的布局抖动。

2.2 text 与 rich-text：文本渲染的跨端差异

text 组件是基础文本容器，默认只支持纯文本。它有几个容易被忽视的属性：selectable 控制是否可选中，decode 是否解码实体字符。做阅读类页面时我一般会加上 selectable，方便用户复制内容；decode 则用于显示 & 这类转义字符。在 App 端和小程序端，text 组件里直接写换行符有时不生效，我自己会配合 CSS 的 word-break 或 white-space 一起使用。

rich-text 是富文本利器，支持 HTML 字符串和节点数组。最常用的场景是文章详情页，后端返回一段 HTML，直接渲染。但要注意，rich-text 在小程序端对部分标签和样式支持不完整，比如视频、音频标签不一定能解析，具体的标签解析能力各端有差异。我试过直接渲染一个包含 table 标签的 HTML，在小程序端样式会错乱，后来统一用后端预处理或前端样式覆盖来解决。另外 rich-text 内部节点不支持事件绑定，想对某段文字做点击跳转，得用节点数组方案自己处理。

<rich-text :nodes="articleContent"></rich-text>

如果后端返回的 HTML 带有大量 inline style，要确认这些样式在目标平台是否被保留。我的习惯是在后端清洗一次 HTML，只保留安全标签和属性，再交给 rich-text 渲染，这样也能顺带处理 XSS 风险。

3. 表单组件的核心玩法：从 input 到 button 的状态管理

3.1 button 组件的基础用法和 open-type 能力

button 是表单和交互的核心。它的基础属性 size、type、plain、disabled、loading，与常规按钮用法一致，但真正体现 uni-app 跨端优势的是 open-type。open-type 可以调用平台原生能力，比如 open-type="contact" 在小程序端打开客服会话，open-type="share" 触发转发，还有 getPhoneNumber、getUserInfo 等。

这里要重点提醒：open-type 的能力在不同平台支持程度不同。contact 和 getPhoneNumber 这类在小程序端是原生能力，非常常用；但在 App 端，部分 open-type 并不支持，需要用其他方式实现。我踩过的坑是，在 App 端直接给 button 加 open-type="contact"，点击没有任何反应。后来查文档才确认该能力本来就是小程序端的。写跨端代码时一定要先确认目标端支不支持，否则白写。

button 的类型也经常被忽视。默认 type="default" 是灰色按钮，type="primary" 才是主色按钮；plain 属性可以让按钮变成描边样式。在表单页面，我一般把主操作按钮设为 disabled 状态控制提交，配合 loading 属性显示加载中，防止重复点击。注意 loading 在 hover-class 上的表现各端不一致，最好自己写个状态样式。

3.2 input 与 textarea：文本输入框双向绑定和关键参数

input 组件推荐用 v-model 做双向绑定，但一些特殊场景，比如需要实时检查字符长度、过滤非法字符时，我会改用 value + @input 的方式自己控制。比如手机号输入框，要求只能输数字，我在 @input 里把非数字替换掉，再赋值回 value，这样可以精确控制。

input 的几个关键参数值得关注。type 决定键盘类型，有 text、number、idcard、digit 等；password 控制密文显示；confirm-type 控制键盘右下角按钮文案，比如搜索场景配 confirm-type="search"，配合 @confirm 事件触发搜索逻辑，体验好很多。cursor-spacing 用于控制键盘弹起时输入框与键盘的距离，这个在真机上很实用，能避免输入框被键盘遮挡。

textarea 跟 input 大部分参数一致，但多了 auto-height（自动增高）、fixed（固定在页面底部）。做评论输入框或意见反馈时，我一般会把 textarea 放在页面底部，配合 fixed 固定，再用 adjust-position 和 cursor-spacing 处理键盘遮罩问题。textarea 在 App 端和小程序端的表现差异主要在于原生组件的层级问题，如果你发现 textarea 盖住了弹窗，建议用 cover-view 或原生子窗体方案。

<textarea v-model="feedbackContent" placeholder="请输入反馈内容" :auto-height="true" :maxlength="200" :cursor-spacing="10" @input="handleInput" />

3.3 checkbox、radio、switch、picker 表单联动和统一取值

表单类页面的数据收集，我用一个 data 对象统一管理。checkbox-group 和 radio-group 的 @change 事件会返回一个数组或字符串，我需要手动映射回业务字段。switch 的 @change 返回的是布尔值，这个相对简单。picker 组件是表单里最灵活也最容易出错的，它有五种模式：selector（单列）、multiSelector（多列）、time、date、region，value 字段根据模式不同传不同结构。

picker 的坑在于 value 参数类型并不总是一致。比如 selector 模式的 value 是索引数字，date 模式的 value 是字符串，region 模式需要传 code。如果直接在 @change 里拿 event.detail.value，你会发现不同模式的返回值类型完全不同，联调时容易踩类型错误。我的解决方法是封装一个通用的 FormPicker 组件，内部根据 mode 做类型转换，对外统一返回业务需要的结构。

// picker 选择器常见处理逻辑 handlePickerChange(e) { const mode = this.pickerMode let value = e.detail.value if (mode === 'selector') { this.formInfo.type = this.options[value].value } else if (mode === 'date') { this.formInfo.date = value } }

这样写的好处是业务层不用感知 picker 内部细节，表单提交时直接从 formInfo 对象取字段，结构干净。

4. 导航组件与媒体组件：打通页面流转和图片视频展示

4.1 navigator 组件与页面路由跳转的使用

navigator 是页面跳转的组件化封装，相当于网页里的 a 标签。url 是必填项，open-type 决定跳转方式。默认 open-type 是 navigate，对应打开新页面，保留当前页面，有层级栈；redirect 是关闭当前页后跳转，不留栈；switchTab 用于跳转 tabBar 页面；reLaunch 是关闭所有页面后打开某页面。

实际上我更习惯用 API 方式 uni.navigateTo、uni.switchTab 等做跳转，因为可以传 success、fail 回调，还能在 then 里继续处理逻辑。但 navigator 组件适合列表页里嵌链接的场景，比如用户协议、消息详情，直接用组件比写事件再调 API 简洁。有一点要注意：tabBar 页面不能用 uni.navigateTo 跳，必须用 uni.switchTab，否则会报错。这个错误我在真机上遇到过多次，第一次遇到时排查半天。

navigator 还有一个隐藏参数 delta，只在 open-type="navigateBack" 时有效，表示返回层级。比如 A 到 B 到 C，在 C 页面想回 A，可以在 navigator 或 navigateBack 里把 delta 设为 2。写页面时我习惯把返回层级直接写在事件里，避免用户多次点击后层级混乱。

4.2 image 组件的跨端适配与性能优化

image 组件是媒体展示的主力，它的 mode 属性决定图片缩放裁剪模式。我实际开发中超过一半场景用 mode="aspectFill"，配合固定宽高实现封面图效果，图片不变形也不会露白。详情页大图用 mode="widthFix"，宽度固定、高度自动，适合内容图。

懒加载 lazy-load 属性在小程序端有效，页面图片多时务必开启。App 端图片缓存逻辑跟小程序端不太一样，有时候图片更新了真机还显示旧图，常见解决方法是把缓存参数拼到 URL 后面，或者使用 image 组件的重新加载机制。还有 webp 支持的坑，Android 端对不同 webp 格式的支持不完全统一，静态资源压缩建议直接输出常规 jpg/png，或者用兼容性好的 webp 格式。

<image class="goods-image" :src="goodsInfo.mainImage" mode="widthFix" :lazy-load="true" @click="previewImage(goodsInfo.mainImage)" />

这段代码配合 uni.previewImage 预览大图，是商品详情的标准写法。previewImage 接收 urls 数组和当前索引，能实现相册式轮播预览，多图场景体验很好。

4.3 video 组件的跨端表现差异

video 组件在 uni-app 里的使用复杂度略高，不同平台表现差异也比较明显。基本属性包括 src、controls、autoplay、loop、object-fit、poster。做课程类项目时，我一般用 custom 控制控件，结合 @play、@pause、@ended 事件维护播放状态。

最常踩的坑是 video 在 App 端和小程序端对同层渲染的支持不同，导致部分样式在真机上失效。比如播放器上面盖一个自定义标题栏，在小程序端可能被原生组件遮挡，必须用 cover-view 或者选择合适的渲染模式。autoplay 在各端的自动播放策略也不一样，H5 端受浏览器自动播放限制，小程序端相对宽松，App 端则需要看系统版本。开发时不要指望同样的代码在三个端表现完全一致，视频相关的交互建议真机多测几轮。

5. 常用 API：网络请求与数据缓存的正确姿势

5.1 uni.request 的封装、拦截器与常见请求错误

uni.request 是最常用的 API，但我不建议直接在业务代码里裸调，原因有三点：第一，每次都要写完整 url，更换接口域名时改动量大；第二，无法统一处理 Token 刷新和错误提示；第三，并发请求、请求取消等场景缺少统一出口。我的做法是封装一个 request 模块，基于 Promise，统一管理请求头、超时时间和错误响应。

封装的基本结构包含：baseURL 常量、请求头注入（比如 Authorization）、响应拦截器（判断 code 是否为 0）、错误消息统一 toast。这里有个小程序端的硬性限制：必须配置合法域名，否则请求直接失败，调试时可以勾选开发环境不校验合法域名，但上线前一定记得把域名加到白名单里，不然用户真机会白屏。

// 简化版的请求封装 const request = (url, method = 'GET', data = {}) => { return new Promise((resolve, reject) => { uni.request({ url: 'https://api.example.com' + url, method, data, timeout: 10000, header: { 'Authorization': 'Bearer ' + uni.getStorageSync('token'), 'Content-Type': 'application/json' }, success: (res) => { if (res.statusCode === 200 && res.data.code === 0) { resolve(res.data.data) } else { uni.showToast({ title: res.data.msg || '请求失败', icon: 'none' }) reject(res.data) } }, fail: (err) => { uni.showToast({ title: '网络异常，请稍后重试', icon: 'none' }) reject(err) } }) }) }

timeout 参数一定设置，默认情况下部分端请求可能长时间无响应，用户体验很差。如果接口偶尔慢，可以适当调大 timeout 到 15 秒，但不要无限大，避免接口故障时用户等待过久。

5.2 数据缓存 API：setStorage、getStorage 与缓存管理

本地缓存是提升用户体验的重要一环。uni.setStorage 和 uni.getStorage 用于异步缓存，uni.setStorageSync 和 uni.getStorageSync 是同步版本。业务里大多用同步版本，简单直接。存复杂对象时框架会自动序列化，取出来直接是对象，不需要手动 JSON.parse。

缓存管理的重点是 key 命名规范和过期策略。我用统一前缀，比如 user_info_、cart_list_，方便清理时批量处理。uni-app 没有原生过期机制，需要自己在缓存数据里带时间戳，读取时判断是否过期。这个方案我一直在用，相当于给缓存加了一层有效期控制。

// 带过期时间的缓存封装 const CACHE_PREFIX = 'myapp_' function setCache(key, value, expireSeconds = 3600) { const data = { value, expireTime: Date.now() + expireSeconds * 1000 } uni.setStorageSync(CACHE_PREFIX + key, data) } function getCache(key) { const data = uni.getStorageSync(CACHE_PREFIX + key) if (!data) return null if (Date.now() > data.expireTime) { uni.removeStorageSync(CACHE_PREFIX + key) return null } return data.value }

App 端与小程序端的存储上限一般为 10MB 左右，不要把大图片、视频存进缓存。真要缓存资源，建议只存 URL，配合图片加载本身的本地缓存机制来处理。

6. 路由与交互反馈 API：让页面流转和用户提示更顺手

6.1 页面路由 API：navigateTo、redirectTo、switchTab、reLaunch 的适用场景

页面路由是 uni-app 跨端的核心能力之一。uni.navigateTo 和 uni.redirectTo 用于打开普通页面，switchTab 和 reLaunch 用于处理 tabBar 页面。四种方式区别在于页面栈行为不同。

• uni.navigateTo：保留当前页面，新页面入栈，可返回。
• uni.redirectTo：关闭当前页面，新页面替换当前页，不可返回上一页。
• uni.switchTab：跳转到 tabBar 页面，关闭所有非 tabBar 页面。
• uni.reLaunch：关闭所有页面，打开新页面，可以打开任意页面。

我来说说实际使用心得。列表进详情用 navigateTo，因为详情返回列表是常规操作；支付完成后用 redirectTo 或 reLaunch 跳结果页，防止用户按返回又回到支付页；切换 tabBar 只用 switchTab；从分享链接进入可能用 reLaunch，同时带上参数初始化整个页面栈。

用 getCurrentPages() 可以获取当前页面栈实例，拿到参数去做判断。我一般在 onLoad 里判断页面参数，再决定是否修改导航栏标题，这个配合路由跳转很实用。还有一点：页面实例存在内存里，如果页面层级过深（小程序默认限制为十层），继续 navigateTo 会失败，所以深层功能要考虑 reLaunch 清理栈。

6.2 交互反馈：showToast、showModal、showLoading 的正确使用方式

uni.showToast 是最常见的轻提示。icon 只支持 success、error、none 三种，网络错误、业务错误提示用 icon: 'none'，成功反馈用 success。showToast 有 duration 属性控制展示时长，但我发现不同端的 toast 消失回调稳定性不同，要做“toast 结束后跳转页面”的场景，建议用 setTimeout 配合 duration 来控制。

uni.showModal 适合需要用户确认的场景，比如清空购物车、退出登录。它的 success 回调里 detail.confirm 和 detail.cancel 分别表示点击了哪个按钮。showLoading 是全屏加载提示，主要用于页面初始化请求、表单提交等场景。注意 showLoading 和 hideLoading 必须成对出现，我在 A 页面 showLoading 后没有 hide，跳到 B 页面发现 loading 还在，实际是全局单例导致的。

uni.showLoading({ title: '加载中' }) // 请求结束后 uni.hideLoading()

还有一种常见需求：页面初始化时展示 loading，数据返回后卸掉 loading。这里要小心请求并发场景，如果两个请求都 showLoading，其中一个先 hide 了，另一个还在加载，loading 会被提前关掉。解决方案是计数器，所有请求完成后再 hideLoading。

6.3 下拉刷新与页面滚动的完整实现

下拉刷新有两个方案：页面级下拉刷新的方式是 pages.json 里配置 enablePullDownRefresh，然后在页面 onPullDownRefresh 生命周期里处理刷新逻辑，数据更新完成后调用 uni.stopPullDownRefresh 停止动画。这个方案简单，但样式不可控，只能使用框架默认的下拉样式。

另一种是在 scroll-view 里做自定义下拉刷新，使用 refresher-enabled、refresher-triggered 属性，配合 @refresherrefresh 事件实现。自定义刷新可以做很多样式定制。不过 scroll-view 的下拉刷新在小程序端和 App 端表现不完全一致，需要分别测试。

onPullDownRefresh() { this.loadPageData().then(() => { uni.stopPullDownRefresh() }) }

onReachBottom 是列表触底加载的页面级事件，配合 scroll-view 的 @scrolltolower 可以按需选用。注意页面级 onReachBottom 跟页面滚动是否到达底部有关，如果页面里内嵌了一个全屏 scroll-view，页面的 onReachBottom 可能不触发，这种场景我一般直接用 scroll-view 的事件。

7. 条件编译与跨端适配案例：让一套代码优雅应对多端差异

7.1 条件编译的语法与应用场景

条件编译是 uni-app 独有的代码处理机制，核心作用是在编译阶段保留或剔除指定平台的代码块。它的语法以注释为基础，支持 JS、模板、CSS 三种文件类型。

// #ifdef H5 console.log('只在 H5 平台输出') // #endif // #ifndef MP-WEIXIN console.log('除了微信小程序外，其他平台执行') // #endif

<!-- #ifdef H5 --> <view class="h5-tip">H5 专享内容</view> <!-- #endif --> <!-- #ifdef MP-WEIXIN --> <view class="mp-tip">小程序专享内容</view> <!-- #endif -->

/* #ifdef APP-PLUS */ .navigation-style { padding-top: var(--status-bar-height); } /* #endif */

条件编译最常见的应用是处理状态栏和安全区，还有不同平台的按键交互。比如 H5 端没有状态栏，小程序端有胶囊按钮，App 端又有刘海屏，写一套逻辑在这三个端上表现完全不同。我在每个页面的导航栏相关代码里都会用条件编译，把各端的渲染策略分开。这样做的好处是代码在构建时就已经过滤，不会把别的端代码打包进去，避免运行时报错。

7.2 常见跨端差异：单位、安全区、键盘与底部横条

跨端适配绕不开单位选择。rpx 是 uni-app 内置的响应式单位，以 750rpx 为设计稿宽度换算。小程序端 rpx 计算基准是屏幕宽度 750rpx，App 端也类似，H5 端会有一定差异。我的习惯是页面布局宽度全部用 rpx，纯文字大小用 rpx，组件内联样式少见。涉及 1px 边框、细线分割，用 CSS 的像素单位配合 transform 缩放处理更精确。

iPhone 底部横条（Home Indicator）和小程序胶囊悬浮窗对布局的影响，建议通过 page-meta 或 safe-area-inset-bottom 解决。我给底部按钮容器加 padding-bottom: var(--safe-area-inset-bottom)，在各端都能正确避开物理安全区域。键盘弹起的问题主要体现在输入框被遮挡，除了之前说的 cursor-spacing，也可以用 adjust-position 自动调整位置，但 App 端的表现跟小程序端不完全一致，建议真机实测。

提示：遇到跨端样式不一致，先想是不是布局结构问题，再想是不是单位换算问题。少用绝对定位，多用 flex 和百分比，能减少很多端差异。

7.3 跨端 API 兼容性检查清单

开发前把 API 兼容性列个清单，可以省下不少排查时间。以我常用的几个 API 为例：

这个清单根据自己的项目逐步维护。实际开发中，我在每个功能点旁边记录各端测试结果和 fallback 方案，上线前照着清单逐项过，能减少真机环境的意外问题。

8. 常见问题排查与开发避坑实录

8.1 高频问题速查：从请求失败到页面跳转失效

下面这些是我在项目中实测遇到、并在邮件群里被反复询问的问题，做成速查表方便对照。

排查步骤我的习惯是分三步走：先在开发者工具里跑，再本地真机预览，最后发布体验版或测试包复现。跨端问题一定要带着目标端排查，别只盯着代码看。

8.2 真机测试与调试的独门经验

条件允许的话，真机调试比模拟器靠谱太多。开发者工具模拟环境与真机存在不少差异，尤其涉及键盘、相机、GPS、存储这些能力时，模拟器很难还原真实情况。我自己在项目排期里会专门留出真机调试时间，特别是新页面首版完成之后，先跑一遍各端真机，再继续写后续功能。

App 端的真机调试我一般用 HBuilderX 的“运行到手机或模拟器”，配合系统日志定位问题。这种调试能看到原生错误日志，比如某个 API 调用的底层 crash。小程序端则使用真机调试通道，辅助 vConsole 查看网络请求和 storage。H5 端直接用浏览器 devtools 就行，没有太多平台差异。

8.3 条件编译写法和样式污染避坑

条件编译写起来简单，但容易因为注释标记写错导致代码被错误裁剪。比如 // #ifdef 必须顶格写，注释结束符 // #endif 不能丢，否则编译器可能报错或产生无法预料的编译结果。我早期犯过一个错：在 CSS 里用了 /* #ifdef H5 */，但忘记写结束注释，结果发现整个页面样式混乱，排查了很久才发现是条件编译把 H5 样式带到了其他端。

条件编译还有文件级裁剪：文件名类似 index.h5.vue 的组件只在 H5 端编译，这个机制在做纯 H5 特例页面时很有用。但要用对场景，别把业务逻辑拆分太多文件，否则维护成本会上升。

样式污染问题同样要留意。全局 App.vue 里定义的样式会影响所有页面，如果给页面根节点写了固定背景色，跳转时可能背景切换延迟。我的习惯是每个页面根节点加一个唯一 class，样式作用域尽量用 scoped，全局样式只放基础样式变量和公共类。

8.4 关于安全区、键盘遮挡和 scroll-view 的避坑建议

再分享三个实打实的避坑点。先说安全区：iPhoneX 系列底部的小横条很容易被忽略，页面底部按钮会被遮住。我用 safe-area-inset-bottom 变量配合 padding 解决，小程序端还可以在 page-meta 里配置页面内容属性。测试时记得切换到全屏和普通模式分别看看。

再说键盘遮挡。表单页里 input 和 textarea 被键盘遮挡，真机上很常见。cursor-spacing 和 adjust-position 可以缓解，但有时候输入框在页面靠上位置反而没问题，靠底部就会被遮。我的经验是：输入框尽量放在可视区域内，配合页面 scrollTo 或者滚动定位到输入框位置，从而避开键盘。

scroll-view 踩过的坑也不少。嵌套滚动时，内外两个滚动方向要错开，比如外层纵向滚动，内层横向滚动，否则手势判定容易失效。我做过一个 tab 切换 + 列表触底加载的页面，外层用 scroll-view 滚竖向，里层 tab 内容横向滑动，就遇到过手势冲突，需要给内层设置 disable 或调整滚动方向才稳定。

开发完一轮 uni-app 后的体会

写了这么多，最后说说个人感受。uni-app 的组件和 API 覆盖面确实广，日常开发里九成需求不用跨出框架的边界，但它并不能完全抹平各端的差异。我们团队现在会养一份“端差异笔记”，每遇到一个平台表现不同的属性或 API，就记进去，下次开发前翻一翻，很多坑就不会重复踩。

给新上手的朋友一个具体建议：别一上来就追求复杂的架构封装，先把 pages.json、常用组件和 uni.request 用熟，跑通一个真实页面（比如商品列表到详情加购物车），整个框架的节奏感就出来了。有条件的话，每个页面都在开发者工具和一台真机上同时验证，你会发现很多问题的出现规律，排查起来越来越快。

再分享一个小技巧：开发时把 console.log 统一封装成自定义方法，在生产环境里可以一键关掉。uni-app 本身没有内置的日志开关，但封装一层之后，逻辑和调试信息都能按需输出，排查线上问题会很方便。这个习惯我从最开始就坚持了下来，现在几十个页面跑来跑去，日志定位依然清晰。