尧图网站建设 
做前端的人这两年应该没少被“多端适配”这件事折磨过。上个月我接到一个外包需求客户张嘴就是要“iOS、安卓、微信小程序、支付宝小程序、抖音小程序最好H5也来一套”。说实话换做几年前我听到这种话只想摔杯子但最近一年多我主力用uni-app干活心态已经稳了很多一套Vue代码编译到五个端虽然不能说完全零成本但至少不用给每个平台重写一套业务逻辑。今天这篇东西就是写给那些刚接触uni-app、被“跨端”这个概念吸引但又不知道从哪里下手的同学把我从装环境到写出第一个能跑的登录功能的全过程事无巨细地拆给你们看。这篇教程没有任何花架子就是一份我能给的最详细的“抄作业”指南覆盖环境搭建、项目结构、页面开发、组件写法、数据请求以及大家搜得最多的用户登录实现。看完你至少能知道uni-app到底是个什么东西、它凭什么能一套代码跑五个平台、我自己写项目时应该先做什么后做什么以及哪些地方容易踩坑。1. 为什么说uni-app是前端多端开发的“最优解”之一1.1 从一次真实的需求评审说起去年年底我帮朋友公司做一个社区团购小程序技术选型的时候团队里吵了一架。原生派说小程序就该用小程序的写法保证性能Vue派说我们已经有一套PC后台是Vue写的不想再学一套新东西还有人说要不直接上Taro反正都是React系。最后拍板用了uni-app原因特别朴素团队里没有人会原生小程序开发但人人都会Vue上手成本是最低的。而且这个项目后续确实需要App端uni-app直接把这条路也铺好了。这个经历其实说明了一个核心问题跨端框架解决的不是“技术炫不炫”的问题而是“业务代码能不能最大化复用”的经营问题。你想想如果五个端各写一套意味着五套登录逻辑、五套商品列表、五套订单状态机每改一个需求要在五个地方同步改光维护成本就能把利润吃光。而uni-app的编译思路是你只维护一份源码由框架帮你翻译成各个平台的原生代码。1.2 uni-app的编译原理一套代码为什么能跑五个平台很多人第一次听说“一套代码多端编译”时会觉得玄乎是不是搞了个WebView套壳其实不是。uni-app底层的做法是在编译阶段把你的.vue单文件组件分别编译成目标平台能识别的代码。举个例子你在代码里写了一个view标签编译到微信小程序时它会被转换成view微信原生就有这个组件编译到App端时它会被转换成原生渲染引擎能识别的视图节点。事件系统也是同理——你在代码里写的click编译到小程序时变成bindtap编译到App时变成原生点击事件。这些转换工作全部发生在编译期运行时只是执行编译产物。所以“一次编写处处运行”这句话准确说是“一次编写处处编译”。这也解释了为什么uni-app强调部分平台特有API要用条件编译处理因为底层渲染引擎和API能力确实有差异框架能做80%的抹平剩下20%需要开发者自己声明。1.3 它适合什么项目又不适合什么项目以我这段时间的实操感受uni-app最适合的场景是业务逻辑复杂、界面交互一般、需要快速覆盖多平台的商用项目。比如电商、社区、工具类应用这些项目的特点是“重业务、轻渲染”跨端复用的收益非常明显。但如果你要做的是重度动画类应用比如互动游戏、依赖大量原生性能的场景比如视频剪辑、实时音视频处理、或者某个平台极致的交互体验我就不建议用uni-app硬扛了。不是说它做不了而是你为了跨端妥协的东西可能比收益还多。前端技术选型没有银弹认清边界比盲目吹捧重要。拿我自己来说现在接项目的第一反应都是先问客户需要哪几个端。如果只需要微信小程序说实话原生或uni-app都行但只要提到App或H5uni-app基本就是我的默认选项了。2. 开发环境搭建与第一个项目的创建2.1 工具选择HBuilderX还是CLI方式我的建议uni-app提供了两套开发姿势一套是用官方IDE叫HBuilderX另一套是用CLI命令行工具基于vue-cli创建工程。我给你的建议非常直接新手用HBuilderX老手用CLI。为什么这么说HBuilderX最大的优势是开箱即用。你不需要自己配置Node环境、不需要手动安装依赖、不需要关心编译插件的版本匹配下载解压就能跑项目。这对第一天接触uni-app的人极其友好。而且它内置了模拟器调试、真机同步、代码提示等一系列功能能把你从环境配置的泥潭里捞出来。CLI方式的好处是工程化更标准、更方便接入你们已有的CI/CD流程也能自由定制webpack配置。但代价是你得自己管理一大堆npm包版本什么dcloudio/vue-cli-plugin-uni、dcloudio/uni-app这些版本之间还有兼容性讲究小白很容易在这里卡一整天。我的建议路径是先用HBuilderX把项目跑通等你对uni-app的项目结构、编译流程有概念了再决定要不要把工程迁移到CLI方式。我自己现在的正式项目用的是CLI方式因为要配合公司的GitLab CI做自动打包但对新手来说第一目标永远是“尽快看到东西跑起来”。2.2 用HBuilderX创建项目的完整过程去DCloud官网下载HBuilderX目前是免费的有标准版和App开发版直接下App开发版就行功能最全。这里有个细节HBuilderX是基于Eclipse内核的所以刚打开时会感觉有点“老派”别被它的界面劝退实际用起来很顺手。安装好之后创建项目的路径是文件 - 新建 - 项目在弹出的窗口里选择“uni-app”模板。你会看到有好几个模板选项默认模板、空模板、Hello uni-app模板等。我的建议是选默认模板因为它带上了一个基础的pages目录和tabBar配置能让你快速看到一个完整项目的骨架空模板什么都不带适合你已经完全理解结构之后自己去搭。再往下看每个模板都标了“Vue2”或“Vue3”的标签。现在新建项目直接选Vue3版本就好。原因有两个一是Vue3是当前主流生态和组件库都在往这边迁移二是uni-app官方对Vue3的支持已经非常成熟了。别选Vue2了那是上一个时代的东西学新不学旧。创建完成后你会在左侧的资源管理器中看到一个标准的uni-app工程结构下一步我们先不急着写代码先把这个项目跑起来看看长什么样。2.3 项目目录结构逐项解读拿到一个uni-app项目你可能会盯着目录发呆。我来给你逐个解释每个文件或目录是干什么用的这是入门路上最关键的一步。├── pages/ # 页面目录每个页面是一个.vue文件 │ ├── index/index.vue │ └── ... ├── static/ # 静态资源目录图片、字体等 ├── App.vue # 应用入口文件生命周期在这里 ├── main.js # Vue初始化入口 ├── manifest.json # 应用配置文件appid、权限、SDK配置都在这里 ├── pages.json # 全局配置路由、导航栏、tabBar、窗口样式 ├── uni.scss # 全局样式变量能被所有scss引用 └── index.html # H5端的模板文件一般不用动这里我重点说一下pages.json它是uni-app项目里最核心的配置文件。你在pages数组里声明的每一个页面路径就决定了这个应用有哪些路由globalStyle字段管全局导航栏样式tabBar字段配底部导航栏。很多人刚写uni-app时长记不住这个文件报“页面路径不存在”的错十有八九就是注册了页面但忘了在pages.json里声明。再提醒一句pages.json里排第一位的页面就是应用的启动首页。我之前有次想让一个引导页作为首页折腾半天没生效最后发现是因为首页压根不看你文件名只看pages数组里的顺序。2.4 把项目跑起来浏览器、微信小程序、手机App默认模板创建之后你可以直接在HBuilderX顶部菜单栏点“运行”。这里有几个运行目标运行到浏览器最快点一下就在Chrome里打开H5端适合开发时快速验证UI。运行到小程序模拟器需要你先在微信开发者工具里开启“服务端口”具体位置在微信开发者工具的设置 - 安全设置 - 服务端口HBuilderX会自动把编译产物推过去。运行到手机或模拟器手机连USB线打开USB调试HBuilderX真机运行功能会直接把App打到手机上首次跑会比较慢因为要编原生壳。第一次运行到微信小程序模拟器时有个细节容易卡人HBuilderX弹出提示“调用微信开发者工具失败”多半是因为你微信开发者工具的安装路径没有被自动识别。解决方法是在微信开发者工具的设置 - 安全设置里确认服务端口已开启然后在HBuilderX的运行菜单里找到“运行到小程序模拟器 - 运行设置”手动配置微信开发者工具路径。这是新人最常见的第一个坎提前跟你打招呼你就不会慌。我第一次配置这个的时候前前后后折腾了快四十分钟踩完之后恨不得把每一步都写出来贴在屏幕上。3. 页面开发与组件书写最像Vue又最不像Vue的地方3.1 页面生命周期onLoad、onShow与created的区别如果你是从纯Vue转过来的这里是最容易产生迷惑的地方。uni-app的页面生命周期是在Vue生命周期之上又封装了一层两者同时存在但触发时机不一样。Vue标准的created和mounted在uni-app里依然有效但你要记住created只代表Vue实例创建完成不代表页面视图已经准备好了。而uni-app特有的onLoad、onShow、onReady这些才是真正对应平台页面的生命周期。几个关键点onLoad页面首次加载时触发一次可以在这里接收上个页面传来的参数。onShow页面每次显示时都会触发。注意是每次从后台切回前台也触发。这个特性非常实用比如页面需要实时刷新数据时很多人会把请求放在onShow而不是onLoad。onReady页面初次渲染完成此时可以开始操作DOM相关逻辑。我在实际开发中的习惯是把一次性的初始数据请求放onLoad把需要保持新鲜的数据刷新放onShow。比如一个购物车页面从商品详情页跳转回来你肯定希望购物车数量是重新算过的这时候放onShow就对了。还有个新手必踩的坑onLoad接收的参数是页面路由跳转时通过url带过来的query参数而且这些参数是字符串类型。你从列表页跳详情页传了一个id: 123到详情页接收到的其实是123做判断前最好先转成数字。3.2 模板语法数据绑定、条件渲染、列表渲染uni-app的模板语法基本就是Vue的模板语法写过Vue的人看到{{ }}和v-for会非常亲切。但有几个跨端注意事项很值得说道说道。数据绑定直接写{{ message }}事件绑定用click这些都和Vue一模一样。列表渲染用v-for但这里有个重要的细节uni-app编译到小程序时v-for竟然不支持在template上加key这听起来很反直觉但我确实遇到过。我的规避方案是v-for循环直接写在实际渲染的标签上然后给key绑定一个唯一值。如果你循环的内容需要包一层template来做条件判断就容易在小程序端出警告最好拆成计算属性先过滤再渲染。条件渲染就是v-if和v-show这两个在小程序端的差异要注意v-show在小程序里并不是所有场景都生效的因为小程序没有真正的DOM节点display控制而是靠wx:if来做的。所以uni-app在编译时会把v-show做一层转换遇到复杂组件时偶尔会有样式残留。我的建议是轻量场景用v-show重量或带组件场景直接用v-if省得排查样式bug。再说一个写模板时容易忽略的性能点v-for的循环体里如果每个子项都是一个独立组件尽量把props传值控制为简单数据。因为小程序端的组件通讯开销比H5端大得多传一个很深的对象每个字段都参与diff列表一长卡顿就来了。我做过一个商品列表一开始传整个商品对象进去页面滚起来帧率明显不行后来改成只传id和必要字段在子组件里再按id去取详情体感顺畅了很多。3.3 组件系统与easycom规范不用注册也能用的魔法uni-app的组件分为两种官方内置组件和自定义组件。内置组件像view、text、image、input这些直接写就能用不用import。自定义组件上uni-app有一个特别爽的机制叫easycom。简单说只要你的组件文件放在components/组件名/组件名.vue这个路径下页面里直接写组件标签就能用连import都不用写。这个机制默认开启而且官方组件库uni-ui也是按这个规范组织的。举个例子你做一个search-bar组件放的位置是components/ └── search-bar/ └── search-bar.vue然后在任意页面的模板里直接写search-bar searchhandleSearch/search-bar不需要在script里import也不需要components: {}注册。这就是easycom的约定优于配置。这个设计省掉了很多重复代码强烈建议你们组件都按这个目录规范放。需要注意的是easycom的目录匹配是有规则的默认只扫描components/组件名/组件名.vue这种“文件夹和文件同名”的结构。如果你的组件命名不合规页面上就静默不渲染这时候排查半天也不知道怎么回事。所以记住这条命名规范能省很多无意义的Debug时间。3.4 样式写法和rpx单位的换算逻辑uni-app支持scss、less、stylus这些预处理器推荐用scss因为uni.scss里内置了一批变量可以全局引用。样式写在style langscss里就能生效。然后是rpx单位这是uni-app中最具特色的东西。它的设计原则是手机屏幕的宽度永远是750rpx也就是你把设计稿宽度定为750px然后所有尺寸直接照抄设计稿的px值改成rpx就行。比如设计稿上按钮宽度是300px你写width: 300rpx不管手机屏幕是320px宽还是414px宽这个按钮都会按比例缩放到屏宽的40%。这个单位的换算逻辑是rpx (屏幕宽度/750) * 设计稿px值。所以iPhone 6/7/8这种375px的屏幕1rpx等于0.5px而在414px的iPhone Plus上1rpx约等于0.552px。听着有点绕但你只需要记住一件事拿到750宽的设计稿px值直接填rpx值永远不出错。还有几个样式上的跨端坑要跟你提前说小程序端不支持*通配符选择器所以不能写* { margin: 0; padding: 0 }这种全局重置要么在App.vue里用page选择器设置要么用官方推荐的import引入一份reset。小程序端对position: fixed支持良好但position: sticky在部分安卓WebView上会失效别在关键布局上依赖它。字体图标定义在App.vue里全局生效但如果你在组件里直接引用了外部字体文件记得路径要用/static/这种别名写法别用相对路径避免打包后引用失效。4. 事件处理、数据通讯与网络请求的核心写法4.1 事件绑定与传参的几种写法uni-app事件绑定的语法是事件名handler跟Vue一致。但有一个区别会让从Vue转过来的人愣一下在模板里不能直接写clickhandle(123)这种带括号的传参吗能是能但要小心事件对象。Vue里你写handle(123)第二个参数可以手动加$event来拿事件对象在uni-app里同样支持这种写法view clickhandleTap(123, $event)点击/view但在小程序端$event拿到的不是浏览器的event对象而是小程序的event对象里面的字段结构不一样。比如获取当前点击元素的datasetH5端是event.currentTarget.dataset小程序端也是这部分倒是统一的。真正要小心的是如果你在小程序端想获取表单值通常推荐用数据双向绑定而不是依赖事件对象去捞。组件自定义事件传参会更简单子组件里写this.$emit(someEvent, payload)父组件some-eventhandler。注意事件名定义时是驼峰someEvent模板监听时用短横线some-eventVue会自动做大小写转换。但uni-app编译到小程序时偶尔会有事件名匹配问题我的经验是自定义事件名统一用短横线命名也就是子组件this.$emit(some-event, data)父组件some-eventhandler这样最稳。4.2 页面间通讯URL传参、globalData和事件总线页面间的数据传递在uni-app里有好几种方式每种都有自己的适用场景。方式一路由URL传参。这是最常用的方式。跳转时写在url上uni.navigateTo({ url: /pages/detail/detail?id123nameapple })接收页面在onLoad(options)里取onLoad(options) { this.id options.id this.name options.name }这种方式简单直接但缺点很明显传复杂对象很痛苦要么序列化成JSON字符串再encode要么拆成多个字段——但URL长度在小程序端是有上限的别拿它传大段数据。方式二globalData。在App.vue里可以声明一个globalData对象任何页面都能通过getApp().globalData访问。适合存用户信息、全局配置这种横跨多个页面的数据。// App.vue script export default { globalData: { userInfo: null, hasLogin: false } } /script方式三事件总线EventBus。用一个空的Vue实例来挂载自定义事件。比如// utils/eventBus.js import Vue from vue export const eventBus new Vue()页面A触发import { eventBus } from /utils/eventBus.js eventBus.$emit(cart-updated, { count: 5 })页面B监听import { eventBus } from /utils/eventBus.js onLoad() { eventBus.$on(cart-updated, (data) { console.log(购物车更新了, data) }) }这个方案适合跨任意页面通信只要注意在页面卸载时$off掉事件不然会内存泄漏。我在一个项目里就是忘记解绑导致页面反复进出时监听器越积越多最后事件触发了五六遍调查了大半天。如果用Vue3版本方式三可以换成mitt库但如果你还没特别熟悉那用Vue2事件总线先顶着也行逻辑是完全一样的。4.3 uni.request请求封装与拦截器思路在uni-app里发请求最底层的是uni.request这相当于浏览器里的fetch。但项目里没人会直接裸用因为你需要统一处理baseURL、请求头、token注入、错误码提示这些横切关注点。我一般的做法是封装一个request.js模块。下面给出一个最精简但功能完整的封装示例附带es6的Promise// utils/request.js const BASE_URL https://api.example.com function request(options) { return new Promise((resolve, reject) { const token uni.getStorageSync(token) uni.request({ url: BASE_URL options.url, method: options.method || GET, data: options.data || {}, header: { Content-Type: application/json, Authorization: token ? Bearer ${token} : }, success: (res) { // 约定后端返回格式{ code: 200, data: ..., message: ... } if (res.statusCode 401) { // token失效跳到登录页 uni.removeStorageSync(token) uni.reLaunch({ url: /pages/login/login }) reject(res.data) return } if (res.data.code 200) { resolve(res.data.data) } else { uni.showToast({ title: res.data.message || 请求失败, icon: none }) reject(res.data) } }, fail: (err) { uni.showToast({ title: 网络异常请稍后重试, icon: none }) reject(err) } }) }) } export default { get(url, data) { return request({ url, method: GET, data }) }, post(url, data) { return request({ url, method: POST, data }) } }这个封装有几个细节值得说uni.getStorageSync是同步取本地缓存相比uni.getStorage的异步回调在请求封装这种场景下更省事不用担心回调时序。Bearertoken的写法是个惯例后端一般也是这么写的你如果后端约定的前缀不一样改成对应的就行。statusCode 401时统一清理token并跳转登录页这个逻辑放在request层是最高效的做一次全局生效不用每个页面自己判断。然后你可以在业务里这样用import request from /utils/request.js async fetchGoodsList() { const data await request.get(/goods/list, { page: 1 }) this.goodsList data.list }如果你想做到拦截器效果uni.addInterceptor这个API在Vue3版本里可以用但兼容性在小程序端偶尔有版本差异。我的建议是先用上面这种Promise封装在success回调里做统一处理这是最底层也最稳的方案。5. 用户登录功能实战从获取code到全局登录态管理5.1 登录方案对比为什么小程序登录通常是code换openid这个主题是搜索热词榜上的常客说明大家都卡在这里。我先帮你把登录方案的逻辑理清楚。目前主流的uni-app登录方式大致分三类账号密码登录用户输入手机号/邮箱密码请求后端换取token。最简单但需要用户注册转化率低一点。第三方授权登录微信、支付宝、苹果等平台的OAuth授权。在App端通常唤起SDK授权在小程序端则是通过uni.login获取code。手机号快捷登录在微信小程序里利用微信的getPhoneNumber能力直接获取用户绑定的手机号配合code实现“无感注册”体验最好。在微信小程序场景下最核心的流程就是code换openid小程序的uni.login会返回一个临时凭证code你把code传给后端后端拿着code去微信服务器换取该用户的openid和session_key。openid是用户在你这个小程序下的唯一标识不是微信号也不是手机号但足以用来建立你自己的用户体系。为什么前端不能直接拿到openid这是微信的安全设计code是一次性的、有效期短只有后端配合appid和appsecret才能换到用户身份。所以流程上前端永远只碰code不碰敏感的身份数据。5.2 完整登录流程拆解前端这样写就对了下面我按最常用的“微信小程序一键登录”给你拆解完整的代码实现。第一步编写登录页。一个最简单的登录按钮绑定一个点击事件template view classlogin-container button typeprimary clickhandleWxLogin微信一键登录/button /view /template第二步点击后调用uni.login获取code。methods: { async handleWxLogin() { // 先调uni.login拿code const loginRes await this.getWxCode() if (!loginRes.code) { uni.showToast({ title: 获取登录凭证失败, icon: none }) return } // 把code传给后端 const userInfo await request.post(/auth/wxlogin, { code: loginRes.code }) // 后端返回token和用户信息 uni.setStorageSync(token, userInfo.token) getApp().globalData.userInfo userInfo.user getApp().globalData.hasLogin true uni.showToast({ title: 登录成功, icon: success }) uni.switchTab({ url: /pages/index/index }) }, getWxCode() { return new Promise((resolve) { uni.login({ provider: weixin, success: (res) resolve(res), fail: () resolve({ code: }) }) }) } }这里说明三点为什么这么写一是uni.login不传provider时默认就是微信登录但我习惯显式写上语义更清楚。二是uni.login本身是回调风格我用Promise包一层配合async/await让代码更线性避免回调嵌套。三是登录成功之后的操作是有顺序讲究的先存储token、再更新globalData、最后跳转顺序反了可能导致目标页面先去读用户信息读到空。第三步区分“已注册用户”和“新用户”。这个逻辑主要在后端。一般做法是后端拿到code换到openid后去user表里查一下有没有这个openid的记录。如果有直接生成token返回登录成功如果没有说明是新用户可以先自动创建一个“匿名账号”返回一个isNewUser标记前端根据这个标记决定是否引导用户去完善昵称头像。前端这段逻辑可以这样接if (userInfo.isNewUser) { // 弹出资料完善引导 uni.navigateTo({ url: /pages/profile-setup/profile-setup }) } else { uni.switchTab({ url: /pages/index/index }) }5.3 token的存储、携带与过期处理登录成功后token怎么存、怎么带、过期了怎么处理这三个问题贯穿你整个uni-app开发过程。存储位置用uni.setStorageSync(token, token)存在本地缓存里。不要把它放进Vuex或globalData当唯一存储——因为这两者都是内存态App一旦重启就没了。唯一可靠的就是本地缓存。Vuex或globalData可以放一份副本方便读取但真正的“数据源”必须是storage。携带方式就像我在4.3节写的request封装一样每次请求在header里加上Authorization: Bearer ${token}。写到一个公共位置不要每个页面手动加。过期处理一般有两种做法。第一种是“被动处理”就是我们之前说的请求返回401时统一清理token、跳登录页。第二种是“主动刷新”在token快过期时用refresh_token去换新的这个更复杂适合对用户体验要求高的项目。新手阶段先把401被动处理做好就足够了。还有一个细节容易踩坑uni.setStorageSync存进去的是字符串如果你存一个对象取出来时要自己JSON.parse。很多人存userInfo时忘了序列化取出来发现是[object Object]排查半天才发现问题。我的习惯是所有要存入storage的数据统一用一个封装的storage.js内部自己处理序列化反序列化这样就不会出这个错。5.4 登录状态检测与页面拦截很多页面要求用户登录后才能访问比如订单列表、个人中心、结算页。你不可能在每个页面都写一遍“没登录就跳登录页”的判断那样太啰嗦了。合理的做法是抽一个公共方法。我推荐在App.vue的onLaunch里先初始化登录状态// App.vue onLaunch() { const token uni.getStorageSync(token) this.globalData.hasLogin !!token }然后在需要登录的页面的onShow里统一判断onShow() { if (!getApp().globalData.hasLogin) { uni.navigateTo({ url: /pages/login/login }) return } // 继续执行本页逻辑 }如果你用的是Vue3版本uni-app还提供了路由拦截器uni.addInterceptor可以拦截navigateTo、switchTab这些路由跳转API在拦截器里统一判断登录状态。这个方案更全局、更优雅。下面给个示例// main.js 或单独的文件 uni.addInterceptor(navigateTo, { invoke(args) { const token uni.getStorageSync(token) const needLogin [/pages/order/list, /pages/user/profile] if (!token needLogin.some(path args.url.startsWith(path))) { uni.navigateTo({ url: /pages/login/login }) return false // 返回false中断跳转 } return true } })注意uni.addInterceptor这个API在小程序端覆盖得比较全但在App端个别情况可能有兼容问题所以生产环境要测试一下再用。我自己公司项目里就是因为线上App有台安卓机老机型拦截不生效最后退回最笨的“页面里判断”方案虽然丑但稳。6. 我替你先踩过的坑6.1 条件编译处理平台差异的正规姿势前面我反复提到条件编译因为这是跨端开发里绕不开的必修课。uni-app定义了官方注释语法用#ifdef和#ifndef来区分平台。前端写法!-- #ifdef MP-WEIXIN -- view只在微信小程序显示/view !-- #endif -- !-- #ifndef MP-WEIXIN -- view除了微信小程序其他端都显示/view !-- #endif --JS写法// #ifdef H5 console.log(只在H5端执行) // #endif样式写法/* #ifdef MP-WEIXIN */ .button { margin-bottom: 20rpx; } /* #endif */为什么要特意讲这个因为我见过太多人遇到“在微信小程序正常、App端样式崩了”的问题第一反应是去写各种样式覆盖或者加!important最后越改越乱。正确姿势就是用条件编译把有差异的那几行代码隔离出来明确告诉编译器“这段代码只服务某个平台”。平台代码比较多常驻这几个MP-WEIXIN微信小程序、APP-PLUSApp含安卓iOS、H5浏览器、MP-ALIPAY支付宝小程序。写之前先搞清目标平台标识别写错了。6.2 兼容性坑从input组件到vue版本差异说到跨端兼容性我印象最深的是input组件的坑。在小程序端input的样式默认是不受外部控制的你给它加height、padding经常不生效因为原生组件有自己的默认样式。正确做法是给input外面包一个view所有尺寸和边框样式都施加在外层view上input内部只设置height: 100%。还有一个特容易踩的是输入框聚焦时页面被顶起的问题。在小程序里键盘弹起时页面会自动上推如果你在input下面放了一个固定定位的按钮就会出现按钮盖住输入框的诡异现象。这种问题排查起来比写代码还累因为不同机型表现还不一样。我的建议是登录页这种简单交互页布局尽量用flex纵向排列别用fixed按钮老老实实跟着内容走。再说Vue版本差异。Vue2和Vue3在uni-app里写起来大部分一样但有几个重大差异要知道Vue.prototype.$xxx改成app.config.globalProperties.xxx全局属性挂载方式变了。filter过滤器在Vue3里没了要用计算属性或方法替代。this.$children在Vue3里也不推荐了组件间通信多用provide/inject或者状态管理。如果你之前只接触过Vue2刚切到uni-app的Vue3模板时可能会有点水土不服但只要记住“uni-app是以Vue语法为基础的再封装”遇到不认识的API先查一下它是Vue的、还是uni-app的大部分问题都能自答。6.3 性能问题的几个常见来源别看入门教程大多在讲“怎么跑起来”但项目上线后真正磨人的是性能。我把自己遇到的典型性能问题总结一下你们提前避开能省很多力气。第一页面体积过大。一次把所有组件、数据都塞进一个页面而且用v-for渲染几百条数据又不加v-if控制渲染条件页面打开会很卡。解决思路长列表用分页第三方组件按需加载别把所有UI库全量引入。第二乱用uni.getStorageSync做大数据读取。这个操作虽然是同步API但底层IO是耗时操作。每个页面启动都去读一遍大对象缓存页面切换就会觉得“慢半拍”。我的做法是用内存缓存globalData做读缓存storage只负责持久化每次App启动时读一次到globalData后面用内存数据。第三图片不处理。小程序端对图片体积敏感一张2MB的图片能在首页拖慢好几秒。现在后端一般都有图床或CDN务必让后端压缩好再给你前端代码里也要用lazy-load属性让图片懒加载image src/static/cover.png lazy-load/imagelazy-load是小程序端image自带的属性电商列表页必开。6.4 一点心态建议学uni-app或者说学任何跨端框架最忌讳的就是“神化它”。它确实能帮你一套代码覆盖多端但你要接受一个事实每个端都有自己的脾性你不可能完全忽略平台差异。跨端框架提供的是“80%的复用能力”剩下20%还是需要你用条件编译和平台专属代码去补。我见过不少同学抱着“一套代码全平台跑”的理想开始最后被各种兼容性问题劝退回到原生开发。其实不是uni-app不好而是预期管理没做好。跨端开发的核心能力不是“会写Vue”而是“知道差异在哪、能用条件编译把差异隔离干净”。这门功夫练出来你用哪个跨端框架都吃饭香。写在最后如果你从头读到这里那我可以很负责任地说你已经把uni-app从“听说过”推进到了“能上手”的阶段。再给你一个重新出发的路径建议先用今天的内容搭出第一个项目跑通浏览器和微信小程序两个端然后把登录功能完整做一遍最后再去看官方文档里组件和API的部分——文档不需要从头啃用到什么查什么效率最高。我个人做这个框架最大的体会就是工具是死的人是活的。跨端开发的关键永远不是你背了多少API而是你对业务结构的理解、对数据流的把握。uni-app把编码成本降下来了但判断成本不会凭空消失——每个平台用户体验的取舍、每个特殊场景的兜底策略都需要你基于对业务的理解来拍板。把这些想明白了跨端开发对你来说就不是什么难事。 uni-app跨端开发实战：从环境搭建到用户登录全流程
做前端的人这两年应该没少被“多端适配”这件事折磨过。上个月我接到一个外包需求客户张嘴就是要“iOS、安卓、微信小程序、支付宝小程序、抖音小程序最好H5也来一套”。说实话换做几年前我听到这种话只想摔杯子但最近一年多我主力用uni-app干活心态已经稳了很多一套Vue代码编译到五个端虽然不能说完全零成本但至少不用给每个平台重写一套业务逻辑。今天这篇东西就是写给那些刚接触uni-app、被“跨端”这个概念吸引但又不知道从哪里下手的同学把我从装环境到写出第一个能跑的登录功能的全过程事无巨细地拆给你们看。这篇教程没有任何花架子就是一份我能给的最详细的“抄作业”指南覆盖环境搭建、项目结构、页面开发、组件写法、数据请求以及大家搜得最多的用户登录实现。看完你至少能知道uni-app到底是个什么东西、它凭什么能一套代码跑五个平台、我自己写项目时应该先做什么后做什么以及哪些地方容易踩坑。1. 为什么说uni-app是前端多端开发的“最优解”之一1.1 从一次真实的需求评审说起去年年底我帮朋友公司做一个社区团购小程序技术选型的时候团队里吵了一架。原生派说小程序就该用小程序的写法保证性能Vue派说我们已经有一套PC后台是Vue写的不想再学一套新东西还有人说要不直接上Taro反正都是React系。最后拍板用了uni-app原因特别朴素团队里没有人会原生小程序开发但人人都会Vue上手成本是最低的。而且这个项目后续确实需要App端uni-app直接把这条路也铺好了。这个经历其实说明了一个核心问题跨端框架解决的不是“技术炫不炫”的问题而是“业务代码能不能最大化复用”的经营问题。你想想如果五个端各写一套意味着五套登录逻辑、五套商品列表、五套订单状态机每改一个需求要在五个地方同步改光维护成本就能把利润吃光。而uni-app的编译思路是你只维护一份源码由框架帮你翻译成各个平台的原生代码。1.2 uni-app的编译原理一套代码为什么能跑五个平台很多人第一次听说“一套代码多端编译”时会觉得玄乎是不是搞了个WebView套壳其实不是。uni-app底层的做法是在编译阶段把你的.vue单文件组件分别编译成目标平台能识别的代码。举个例子你在代码里写了一个view标签编译到微信小程序时它会被转换成view微信原生就有这个组件编译到App端时它会被转换成原生渲染引擎能识别的视图节点。事件系统也是同理——你在代码里写的click编译到小程序时变成bindtap编译到App时变成原生点击事件。这些转换工作全部发生在编译期运行时只是执行编译产物。所以“一次编写处处运行”这句话准确说是“一次编写处处编译”。这也解释了为什么uni-app强调部分平台特有API要用条件编译处理因为底层渲染引擎和API能力确实有差异框架能做80%的抹平剩下20%需要开发者自己声明。1.3 它适合什么项目又不适合什么项目以我这段时间的实操感受uni-app最适合的场景是业务逻辑复杂、界面交互一般、需要快速覆盖多平台的商用项目。比如电商、社区、工具类应用这些项目的特点是“重业务、轻渲染”跨端复用的收益非常明显。但如果你要做的是重度动画类应用比如互动游戏、依赖大量原生性能的场景比如视频剪辑、实时音视频处理、或者某个平台极致的交互体验我就不建议用uni-app硬扛了。不是说它做不了而是你为了跨端妥协的东西可能比收益还多。前端技术选型没有银弹认清边界比盲目吹捧重要。拿我自己来说现在接项目的第一反应都是先问客户需要哪几个端。如果只需要微信小程序说实话原生或uni-app都行但只要提到App或H5uni-app基本就是我的默认选项了。2. 开发环境搭建与第一个项目的创建2.1 工具选择HBuilderX还是CLI方式我的建议uni-app提供了两套开发姿势一套是用官方IDE叫HBuilderX另一套是用CLI命令行工具基于vue-cli创建工程。我给你的建议非常直接新手用HBuilderX老手用CLI。为什么这么说HBuilderX最大的优势是开箱即用。你不需要自己配置Node环境、不需要手动安装依赖、不需要关心编译插件的版本匹配下载解压就能跑项目。这对第一天接触uni-app的人极其友好。而且它内置了模拟器调试、真机同步、代码提示等一系列功能能把你从环境配置的泥潭里捞出来。CLI方式的好处是工程化更标准、更方便接入你们已有的CI/CD流程也能自由定制webpack配置。但代价是你得自己管理一大堆npm包版本什么dcloudio/vue-cli-plugin-uni、dcloudio/uni-app这些版本之间还有兼容性讲究小白很容易在这里卡一整天。我的建议路径是先用HBuilderX把项目跑通等你对uni-app的项目结构、编译流程有概念了再决定要不要把工程迁移到CLI方式。我自己现在的正式项目用的是CLI方式因为要配合公司的GitLab CI做自动打包但对新手来说第一目标永远是“尽快看到东西跑起来”。2.2 用HBuilderX创建项目的完整过程去DCloud官网下载HBuilderX目前是免费的有标准版和App开发版直接下App开发版就行功能最全。这里有个细节HBuilderX是基于Eclipse内核的所以刚打开时会感觉有点“老派”别被它的界面劝退实际用起来很顺手。安装好之后创建项目的路径是文件 - 新建 - 项目在弹出的窗口里选择“uni-app”模板。你会看到有好几个模板选项默认模板、空模板、Hello uni-app模板等。我的建议是选默认模板因为它带上了一个基础的pages目录和tabBar配置能让你快速看到一个完整项目的骨架空模板什么都不带适合你已经完全理解结构之后自己去搭。再往下看每个模板都标了“Vue2”或“Vue3”的标签。现在新建项目直接选Vue3版本就好。原因有两个一是Vue3是当前主流生态和组件库都在往这边迁移二是uni-app官方对Vue3的支持已经非常成熟了。别选Vue2了那是上一个时代的东西学新不学旧。创建完成后你会在左侧的资源管理器中看到一个标准的uni-app工程结构下一步我们先不急着写代码先把这个项目跑起来看看长什么样。2.3 项目目录结构逐项解读拿到一个uni-app项目你可能会盯着目录发呆。我来给你逐个解释每个文件或目录是干什么用的这是入门路上最关键的一步。├── pages/ # 页面目录每个页面是一个.vue文件 │ ├── index/index.vue │ └── ... ├── static/ # 静态资源目录图片、字体等 ├── App.vue # 应用入口文件生命周期在这里 ├── main.js # Vue初始化入口 ├── manifest.json # 应用配置文件appid、权限、SDK配置都在这里 ├── pages.json # 全局配置路由、导航栏、tabBar、窗口样式 ├── uni.scss # 全局样式变量能被所有scss引用 └── index.html # H5端的模板文件一般不用动这里我重点说一下pages.json它是uni-app项目里最核心的配置文件。你在pages数组里声明的每一个页面路径就决定了这个应用有哪些路由globalStyle字段管全局导航栏样式tabBar字段配底部导航栏。很多人刚写uni-app时长记不住这个文件报“页面路径不存在”的错十有八九就是注册了页面但忘了在pages.json里声明。再提醒一句pages.json里排第一位的页面就是应用的启动首页。我之前有次想让一个引导页作为首页折腾半天没生效最后发现是因为首页压根不看你文件名只看pages数组里的顺序。2.4 把项目跑起来浏览器、微信小程序、手机App默认模板创建之后你可以直接在HBuilderX顶部菜单栏点“运行”。这里有几个运行目标运行到浏览器最快点一下就在Chrome里打开H5端适合开发时快速验证UI。运行到小程序模拟器需要你先在微信开发者工具里开启“服务端口”具体位置在微信开发者工具的设置 - 安全设置 - 服务端口HBuilderX会自动把编译产物推过去。运行到手机或模拟器手机连USB线打开USB调试HBuilderX真机运行功能会直接把App打到手机上首次跑会比较慢因为要编原生壳。第一次运行到微信小程序模拟器时有个细节容易卡人HBuilderX弹出提示“调用微信开发者工具失败”多半是因为你微信开发者工具的安装路径没有被自动识别。解决方法是在微信开发者工具的设置 - 安全设置里确认服务端口已开启然后在HBuilderX的运行菜单里找到“运行到小程序模拟器 - 运行设置”手动配置微信开发者工具路径。这是新人最常见的第一个坎提前跟你打招呼你就不会慌。我第一次配置这个的时候前前后后折腾了快四十分钟踩完之后恨不得把每一步都写出来贴在屏幕上。3. 页面开发与组件书写最像Vue又最不像Vue的地方3.1 页面生命周期onLoad、onShow与created的区别如果你是从纯Vue转过来的这里是最容易产生迷惑的地方。uni-app的页面生命周期是在Vue生命周期之上又封装了一层两者同时存在但触发时机不一样。Vue标准的created和mounted在uni-app里依然有效但你要记住created只代表Vue实例创建完成不代表页面视图已经准备好了。而uni-app特有的onLoad、onShow、onReady这些才是真正对应平台页面的生命周期。几个关键点onLoad页面首次加载时触发一次可以在这里接收上个页面传来的参数。onShow页面每次显示时都会触发。注意是每次从后台切回前台也触发。这个特性非常实用比如页面需要实时刷新数据时很多人会把请求放在onShow而不是onLoad。onReady页面初次渲染完成此时可以开始操作DOM相关逻辑。我在实际开发中的习惯是把一次性的初始数据请求放onLoad把需要保持新鲜的数据刷新放onShow。比如一个购物车页面从商品详情页跳转回来你肯定希望购物车数量是重新算过的这时候放onShow就对了。还有个新手必踩的坑onLoad接收的参数是页面路由跳转时通过url带过来的query参数而且这些参数是字符串类型。你从列表页跳详情页传了一个id: 123到详情页接收到的其实是123做判断前最好先转成数字。3.2 模板语法数据绑定、条件渲染、列表渲染uni-app的模板语法基本就是Vue的模板语法写过Vue的人看到{{ }}和v-for会非常亲切。但有几个跨端注意事项很值得说道说道。数据绑定直接写{{ message }}事件绑定用click这些都和Vue一模一样。列表渲染用v-for但这里有个重要的细节uni-app编译到小程序时v-for竟然不支持在template上加key这听起来很反直觉但我确实遇到过。我的规避方案是v-for循环直接写在实际渲染的标签上然后给key绑定一个唯一值。如果你循环的内容需要包一层template来做条件判断就容易在小程序端出警告最好拆成计算属性先过滤再渲染。条件渲染就是v-if和v-show这两个在小程序端的差异要注意v-show在小程序里并不是所有场景都生效的因为小程序没有真正的DOM节点display控制而是靠wx:if来做的。所以uni-app在编译时会把v-show做一层转换遇到复杂组件时偶尔会有样式残留。我的建议是轻量场景用v-show重量或带组件场景直接用v-if省得排查样式bug。再说一个写模板时容易忽略的性能点v-for的循环体里如果每个子项都是一个独立组件尽量把props传值控制为简单数据。因为小程序端的组件通讯开销比H5端大得多传一个很深的对象每个字段都参与diff列表一长卡顿就来了。我做过一个商品列表一开始传整个商品对象进去页面滚起来帧率明显不行后来改成只传id和必要字段在子组件里再按id去取详情体感顺畅了很多。3.3 组件系统与easycom规范不用注册也能用的魔法uni-app的组件分为两种官方内置组件和自定义组件。内置组件像view、text、image、input这些直接写就能用不用import。自定义组件上uni-app有一个特别爽的机制叫easycom。简单说只要你的组件文件放在components/组件名/组件名.vue这个路径下页面里直接写组件标签就能用连import都不用写。这个机制默认开启而且官方组件库uni-ui也是按这个规范组织的。举个例子你做一个search-bar组件放的位置是components/ └── search-bar/ └── search-bar.vue然后在任意页面的模板里直接写search-bar searchhandleSearch/search-bar不需要在script里import也不需要components: {}注册。这就是easycom的约定优于配置。这个设计省掉了很多重复代码强烈建议你们组件都按这个目录规范放。需要注意的是easycom的目录匹配是有规则的默认只扫描components/组件名/组件名.vue这种“文件夹和文件同名”的结构。如果你的组件命名不合规页面上就静默不渲染这时候排查半天也不知道怎么回事。所以记住这条命名规范能省很多无意义的Debug时间。3.4 样式写法和rpx单位的换算逻辑uni-app支持scss、less、stylus这些预处理器推荐用scss因为uni.scss里内置了一批变量可以全局引用。样式写在style langscss里就能生效。然后是rpx单位这是uni-app中最具特色的东西。它的设计原则是手机屏幕的宽度永远是750rpx也就是你把设计稿宽度定为750px然后所有尺寸直接照抄设计稿的px值改成rpx就行。比如设计稿上按钮宽度是300px你写width: 300rpx不管手机屏幕是320px宽还是414px宽这个按钮都会按比例缩放到屏宽的40%。这个单位的换算逻辑是rpx (屏幕宽度/750) * 设计稿px值。所以iPhone 6/7/8这种375px的屏幕1rpx等于0.5px而在414px的iPhone Plus上1rpx约等于0.552px。听着有点绕但你只需要记住一件事拿到750宽的设计稿px值直接填rpx值永远不出错。还有几个样式上的跨端坑要跟你提前说小程序端不支持*通配符选择器所以不能写* { margin: 0; padding: 0 }这种全局重置要么在App.vue里用page选择器设置要么用官方推荐的import引入一份reset。小程序端对position: fixed支持良好但position: sticky在部分安卓WebView上会失效别在关键布局上依赖它。字体图标定义在App.vue里全局生效但如果你在组件里直接引用了外部字体文件记得路径要用/static/这种别名写法别用相对路径避免打包后引用失效。4. 事件处理、数据通讯与网络请求的核心写法4.1 事件绑定与传参的几种写法uni-app事件绑定的语法是事件名handler跟Vue一致。但有一个区别会让从Vue转过来的人愣一下在模板里不能直接写clickhandle(123)这种带括号的传参吗能是能但要小心事件对象。Vue里你写handle(123)第二个参数可以手动加$event来拿事件对象在uni-app里同样支持这种写法view clickhandleTap(123, $event)点击/view但在小程序端$event拿到的不是浏览器的event对象而是小程序的event对象里面的字段结构不一样。比如获取当前点击元素的datasetH5端是event.currentTarget.dataset小程序端也是这部分倒是统一的。真正要小心的是如果你在小程序端想获取表单值通常推荐用数据双向绑定而不是依赖事件对象去捞。组件自定义事件传参会更简单子组件里写this.$emit(someEvent, payload)父组件some-eventhandler。注意事件名定义时是驼峰someEvent模板监听时用短横线some-eventVue会自动做大小写转换。但uni-app编译到小程序时偶尔会有事件名匹配问题我的经验是自定义事件名统一用短横线命名也就是子组件this.$emit(some-event, data)父组件some-eventhandler这样最稳。4.2 页面间通讯URL传参、globalData和事件总线页面间的数据传递在uni-app里有好几种方式每种都有自己的适用场景。方式一路由URL传参。这是最常用的方式。跳转时写在url上uni.navigateTo({ url: /pages/detail/detail?id123nameapple })接收页面在onLoad(options)里取onLoad(options) { this.id options.id this.name options.name }这种方式简单直接但缺点很明显传复杂对象很痛苦要么序列化成JSON字符串再encode要么拆成多个字段——但URL长度在小程序端是有上限的别拿它传大段数据。方式二globalData。在App.vue里可以声明一个globalData对象任何页面都能通过getApp().globalData访问。适合存用户信息、全局配置这种横跨多个页面的数据。// App.vue script export default { globalData: { userInfo: null, hasLogin: false } } /script方式三事件总线EventBus。用一个空的Vue实例来挂载自定义事件。比如// utils/eventBus.js import Vue from vue export const eventBus new Vue()页面A触发import { eventBus } from /utils/eventBus.js eventBus.$emit(cart-updated, { count: 5 })页面B监听import { eventBus } from /utils/eventBus.js onLoad() { eventBus.$on(cart-updated, (data) { console.log(购物车更新了, data) }) }这个方案适合跨任意页面通信只要注意在页面卸载时$off掉事件不然会内存泄漏。我在一个项目里就是忘记解绑导致页面反复进出时监听器越积越多最后事件触发了五六遍调查了大半天。如果用Vue3版本方式三可以换成mitt库但如果你还没特别熟悉那用Vue2事件总线先顶着也行逻辑是完全一样的。4.3 uni.request请求封装与拦截器思路在uni-app里发请求最底层的是uni.request这相当于浏览器里的fetch。但项目里没人会直接裸用因为你需要统一处理baseURL、请求头、token注入、错误码提示这些横切关注点。我一般的做法是封装一个request.js模块。下面给出一个最精简但功能完整的封装示例附带es6的Promise// utils/request.js const BASE_URL https://api.example.com function request(options) { return new Promise((resolve, reject) { const token uni.getStorageSync(token) uni.request({ url: BASE_URL options.url, method: options.method || GET, data: options.data || {}, header: { Content-Type: application/json, Authorization: token ? Bearer ${token} : }, success: (res) { // 约定后端返回格式{ code: 200, data: ..., message: ... } if (res.statusCode 401) { // token失效跳到登录页 uni.removeStorageSync(token) uni.reLaunch({ url: /pages/login/login }) reject(res.data) return } if (res.data.code 200) { resolve(res.data.data) } else { uni.showToast({ title: res.data.message || 请求失败, icon: none }) reject(res.data) } }, fail: (err) { uni.showToast({ title: 网络异常请稍后重试, icon: none }) reject(err) } }) }) } export default { get(url, data) { return request({ url, method: GET, data }) }, post(url, data) { return request({ url, method: POST, data }) } }这个封装有几个细节值得说uni.getStorageSync是同步取本地缓存相比uni.getStorage的异步回调在请求封装这种场景下更省事不用担心回调时序。Bearertoken的写法是个惯例后端一般也是这么写的你如果后端约定的前缀不一样改成对应的就行。statusCode 401时统一清理token并跳转登录页这个逻辑放在request层是最高效的做一次全局生效不用每个页面自己判断。然后你可以在业务里这样用import request from /utils/request.js async fetchGoodsList() { const data await request.get(/goods/list, { page: 1 }) this.goodsList data.list }如果你想做到拦截器效果uni.addInterceptor这个API在Vue3版本里可以用但兼容性在小程序端偶尔有版本差异。我的建议是先用上面这种Promise封装在success回调里做统一处理这是最底层也最稳的方案。5. 用户登录功能实战从获取code到全局登录态管理5.1 登录方案对比为什么小程序登录通常是code换openid这个主题是搜索热词榜上的常客说明大家都卡在这里。我先帮你把登录方案的逻辑理清楚。目前主流的uni-app登录方式大致分三类账号密码登录用户输入手机号/邮箱密码请求后端换取token。最简单但需要用户注册转化率低一点。第三方授权登录微信、支付宝、苹果等平台的OAuth授权。在App端通常唤起SDK授权在小程序端则是通过uni.login获取code。手机号快捷登录在微信小程序里利用微信的getPhoneNumber能力直接获取用户绑定的手机号配合code实现“无感注册”体验最好。在微信小程序场景下最核心的流程就是code换openid小程序的uni.login会返回一个临时凭证code你把code传给后端后端拿着code去微信服务器换取该用户的openid和session_key。openid是用户在你这个小程序下的唯一标识不是微信号也不是手机号但足以用来建立你自己的用户体系。为什么前端不能直接拿到openid这是微信的安全设计code是一次性的、有效期短只有后端配合appid和appsecret才能换到用户身份。所以流程上前端永远只碰code不碰敏感的身份数据。5.2 完整登录流程拆解前端这样写就对了下面我按最常用的“微信小程序一键登录”给你拆解完整的代码实现。第一步编写登录页。一个最简单的登录按钮绑定一个点击事件template view classlogin-container button typeprimary clickhandleWxLogin微信一键登录/button /view /template第二步点击后调用uni.login获取code。methods: { async handleWxLogin() { // 先调uni.login拿code const loginRes await this.getWxCode() if (!loginRes.code) { uni.showToast({ title: 获取登录凭证失败, icon: none }) return } // 把code传给后端 const userInfo await request.post(/auth/wxlogin, { code: loginRes.code }) // 后端返回token和用户信息 uni.setStorageSync(token, userInfo.token) getApp().globalData.userInfo userInfo.user getApp().globalData.hasLogin true uni.showToast({ title: 登录成功, icon: success }) uni.switchTab({ url: /pages/index/index }) }, getWxCode() { return new Promise((resolve) { uni.login({ provider: weixin, success: (res) resolve(res), fail: () resolve({ code: }) }) }) } }这里说明三点为什么这么写一是uni.login不传provider时默认就是微信登录但我习惯显式写上语义更清楚。二是uni.login本身是回调风格我用Promise包一层配合async/await让代码更线性避免回调嵌套。三是登录成功之后的操作是有顺序讲究的先存储token、再更新globalData、最后跳转顺序反了可能导致目标页面先去读用户信息读到空。第三步区分“已注册用户”和“新用户”。这个逻辑主要在后端。一般做法是后端拿到code换到openid后去user表里查一下有没有这个openid的记录。如果有直接生成token返回登录成功如果没有说明是新用户可以先自动创建一个“匿名账号”返回一个isNewUser标记前端根据这个标记决定是否引导用户去完善昵称头像。前端这段逻辑可以这样接if (userInfo.isNewUser) { // 弹出资料完善引导 uni.navigateTo({ url: /pages/profile-setup/profile-setup }) } else { uni.switchTab({ url: /pages/index/index }) }5.3 token的存储、携带与过期处理登录成功后token怎么存、怎么带、过期了怎么处理这三个问题贯穿你整个uni-app开发过程。存储位置用uni.setStorageSync(token, token)存在本地缓存里。不要把它放进Vuex或globalData当唯一存储——因为这两者都是内存态App一旦重启就没了。唯一可靠的就是本地缓存。Vuex或globalData可以放一份副本方便读取但真正的“数据源”必须是storage。携带方式就像我在4.3节写的request封装一样每次请求在header里加上Authorization: Bearer ${token}。写到一个公共位置不要每个页面手动加。过期处理一般有两种做法。第一种是“被动处理”就是我们之前说的请求返回401时统一清理token、跳登录页。第二种是“主动刷新”在token快过期时用refresh_token去换新的这个更复杂适合对用户体验要求高的项目。新手阶段先把401被动处理做好就足够了。还有一个细节容易踩坑uni.setStorageSync存进去的是字符串如果你存一个对象取出来时要自己JSON.parse。很多人存userInfo时忘了序列化取出来发现是[object Object]排查半天才发现问题。我的习惯是所有要存入storage的数据统一用一个封装的storage.js内部自己处理序列化反序列化这样就不会出这个错。5.4 登录状态检测与页面拦截很多页面要求用户登录后才能访问比如订单列表、个人中心、结算页。你不可能在每个页面都写一遍“没登录就跳登录页”的判断那样太啰嗦了。合理的做法是抽一个公共方法。我推荐在App.vue的onLaunch里先初始化登录状态// App.vue onLaunch() { const token uni.getStorageSync(token) this.globalData.hasLogin !!token }然后在需要登录的页面的onShow里统一判断onShow() { if (!getApp().globalData.hasLogin) { uni.navigateTo({ url: /pages/login/login }) return } // 继续执行本页逻辑 }如果你用的是Vue3版本uni-app还提供了路由拦截器uni.addInterceptor可以拦截navigateTo、switchTab这些路由跳转API在拦截器里统一判断登录状态。这个方案更全局、更优雅。下面给个示例// main.js 或单独的文件 uni.addInterceptor(navigateTo, { invoke(args) { const token uni.getStorageSync(token) const needLogin [/pages/order/list, /pages/user/profile] if (!token needLogin.some(path args.url.startsWith(path))) { uni.navigateTo({ url: /pages/login/login }) return false // 返回false中断跳转 } return true } })注意uni.addInterceptor这个API在小程序端覆盖得比较全但在App端个别情况可能有兼容问题所以生产环境要测试一下再用。我自己公司项目里就是因为线上App有台安卓机老机型拦截不生效最后退回最笨的“页面里判断”方案虽然丑但稳。6. 我替你先踩过的坑6.1 条件编译处理平台差异的正规姿势前面我反复提到条件编译因为这是跨端开发里绕不开的必修课。uni-app定义了官方注释语法用#ifdef和#ifndef来区分平台。前端写法!-- #ifdef MP-WEIXIN -- view只在微信小程序显示/view !-- #endif -- !-- #ifndef MP-WEIXIN -- view除了微信小程序其他端都显示/view !-- #endif --JS写法// #ifdef H5 console.log(只在H5端执行) // #endif样式写法/* #ifdef MP-WEIXIN */ .button { margin-bottom: 20rpx; } /* #endif */为什么要特意讲这个因为我见过太多人遇到“在微信小程序正常、App端样式崩了”的问题第一反应是去写各种样式覆盖或者加!important最后越改越乱。正确姿势就是用条件编译把有差异的那几行代码隔离出来明确告诉编译器“这段代码只服务某个平台”。平台代码比较多常驻这几个MP-WEIXIN微信小程序、APP-PLUSApp含安卓iOS、H5浏览器、MP-ALIPAY支付宝小程序。写之前先搞清目标平台标识别写错了。6.2 兼容性坑从input组件到vue版本差异说到跨端兼容性我印象最深的是input组件的坑。在小程序端input的样式默认是不受外部控制的你给它加height、padding经常不生效因为原生组件有自己的默认样式。正确做法是给input外面包一个view所有尺寸和边框样式都施加在外层view上input内部只设置height: 100%。还有一个特容易踩的是输入框聚焦时页面被顶起的问题。在小程序里键盘弹起时页面会自动上推如果你在input下面放了一个固定定位的按钮就会出现按钮盖住输入框的诡异现象。这种问题排查起来比写代码还累因为不同机型表现还不一样。我的建议是登录页这种简单交互页布局尽量用flex纵向排列别用fixed按钮老老实实跟着内容走。再说Vue版本差异。Vue2和Vue3在uni-app里写起来大部分一样但有几个重大差异要知道Vue.prototype.$xxx改成app.config.globalProperties.xxx全局属性挂载方式变了。filter过滤器在Vue3里没了要用计算属性或方法替代。this.$children在Vue3里也不推荐了组件间通信多用provide/inject或者状态管理。如果你之前只接触过Vue2刚切到uni-app的Vue3模板时可能会有点水土不服但只要记住“uni-app是以Vue语法为基础的再封装”遇到不认识的API先查一下它是Vue的、还是uni-app的大部分问题都能自答。6.3 性能问题的几个常见来源别看入门教程大多在讲“怎么跑起来”但项目上线后真正磨人的是性能。我把自己遇到的典型性能问题总结一下你们提前避开能省很多力气。第一页面体积过大。一次把所有组件、数据都塞进一个页面而且用v-for渲染几百条数据又不加v-if控制渲染条件页面打开会很卡。解决思路长列表用分页第三方组件按需加载别把所有UI库全量引入。第二乱用uni.getStorageSync做大数据读取。这个操作虽然是同步API但底层IO是耗时操作。每个页面启动都去读一遍大对象缓存页面切换就会觉得“慢半拍”。我的做法是用内存缓存globalData做读缓存storage只负责持久化每次App启动时读一次到globalData后面用内存数据。第三图片不处理。小程序端对图片体积敏感一张2MB的图片能在首页拖慢好几秒。现在后端一般都有图床或CDN务必让后端压缩好再给你前端代码里也要用lazy-load属性让图片懒加载image src/static/cover.png lazy-load/imagelazy-load是小程序端image自带的属性电商列表页必开。6.4 一点心态建议学uni-app或者说学任何跨端框架最忌讳的就是“神化它”。它确实能帮你一套代码覆盖多端但你要接受一个事实每个端都有自己的脾性你不可能完全忽略平台差异。跨端框架提供的是“80%的复用能力”剩下20%还是需要你用条件编译和平台专属代码去补。我见过不少同学抱着“一套代码全平台跑”的理想开始最后被各种兼容性问题劝退回到原生开发。其实不是uni-app不好而是预期管理没做好。跨端开发的核心能力不是“会写Vue”而是“知道差异在哪、能用条件编译把差异隔离干净”。这门功夫练出来你用哪个跨端框架都吃饭香。写在最后如果你从头读到这里那我可以很负责任地说你已经把uni-app从“听说过”推进到了“能上手”的阶段。再给你一个重新出发的路径建议先用今天的内容搭出第一个项目跑通浏览器和微信小程序两个端然后把登录功能完整做一遍最后再去看官方文档里组件和API的部分——文档不需要从头啃用到什么查什么效率最高。我个人做这个框架最大的体会就是工具是死的人是活的。跨端开发的关键永远不是你背了多少API而是你对业务结构的理解、对数据流的把握。uni-app把编码成本降下来了但判断成本不会凭空消失——每个平台用户体验的取舍、每个特殊场景的兜底策略都需要你基于对业务的理解来拍板。把这些想明白了跨端开发对你来说就不是什么难事。