做前端这些年我碰到的多端需求实在太多了同一个项目老板说要 App、说要有小程序、网页也要跟上。按传统方式做等于把一个需求拆成三套代码分别维护光是同步业务逻辑就足够让人崩溃。后来我大量使用 Uni-app它真正的价值不是“少写几行代码”而是把业务沉淀成一套代码再按不同平台输出这个思路在中小团队和外包项目里特别实用。这篇文章我会沿着实际做项目的路径从 HBuilderX 建项目、入口文件配置、Vue3 里 ref 的用法到用户登录功能落地、微信小程序适配、最后做安卓离线打包完整过一遍。适合刚接触 uni-app 的开发者也适合已经能跑 demo 但没完整撸过一个项目的人。我不会照搬官方文档重点讲那些影响成败的关节和容易踩的坑。1. 先搞清楚 Uni-app 到底解决了什么问题1.1 一套代码走天下的编译逻辑Uni-app 的定位是基于 Vue 语法的跨端开发框架它的核心做法是“编译到不同目标”。开发时写的是 Vue 单文件组件编译器会把它转成微信小程序的 WXML/WXSS、App 端的原生控件、H5 的 DOM 结构。这里有个容易误解的点它并不是用浏览器套壳去运行网页编译到小程序和 App 端时走的还是各平台的渲染机制只是业务代码在你的工程里统一了。所以你不能在代码里随手写document.getElementById这类浏览器 API因为到了小程序环境根本不存在这个对象。理解这一点很多新人报错“window is not defined”时就不会慌那是把 Web 开发思维直接搬过来了。这套编译逻辑带来的收益很明显一份业务代码覆盖 iOS、Android、微信小程序、支付宝小程序、H5甚至快应用和百度小程序。对独立开发者和中小团队来说维护成本下降得非常明显。但它也有边界凡是涉及复杂原生能力的场景比如自定义摄像头、蓝牙协议栈、特殊硬件调用就得靠条件编译加原生插件去补完全想“一套代码通吃所有奇怪需求”是不现实的。我通常把 uni-app 定位成“业务逻辑复用框架”原生能力是它的补给线需要时再单独接。1.2 为什么新项目我建议选 Vue3早期 uni-app 大量项目跑在 Vue2 上那时候 Vue3 刚发布插件生态和周边组件没有跟上我在正式项目里也不太敢切。但 2022 年后情况完全不同了Vue3 的响应式系统、组合式 API、TypeScript 支持都已经稳定HBuilderX 新建项目也把 Vue3 作为得力选项。对新项目我的建议非常直接选 Vue3 模板不要再开 Vue2 的坑。Vue3 最让我受用的不是那点性能提升而是组合式 API 对复杂状态的整理能力。以前写登录功能data、methods、computed 分散在一个组件里逻辑一多就想翻车。现在可以把用户状态、登录请求、token 刷新全部搬进一个useUser组合式函数组件里几行代码就搞定。这也直接影响到 uni-app 项目的后期维护多个页面共享同一份登录逻辑时Vue3 的组合式函数是天然抽取单元。另一个现实原因是 DCloud 的新工具链、uni-app x、新版本插件都在向 Vue3 靠拢新项目如果还守着 Vue2后面想升级会非常痛苦。2. 从 HBuilderX 和入口文件开始搭骨架2.1 HBuilderX 的创建、运行与调试做 uni-app 开发官方推荐的 IDE 是 HBuilderX它对 uni-app 的编译、运行、打包深度集成很多环境配置在图形界面里点一下就行。下载安装后新建项目能看到一个“uni-app”模板选项创建时会让选 Vue2 还是 Vue3这里直接选 Vue3。项目生成后工具栏上会有“运行”按钮你可以选择运行到浏览器、运行到微信开发者工具、运行到手机或模拟器。第一次运行到微信小程序时需要在 manifest.json 里填上微信小程序的 AppID并且保证本机装了微信开发者工具HBuilderX 会自动调用它打开编译产物。真机运行则要打开手机的 USB 调试Android 手机在开发者选项里打开“USB 调试”iPhone 则需要安装相应驱动并信任电脑。我习惯先在 H5 端快速看页面效果因为编译速度最快确认业务逻辑没问题后再切到小程序端验证兼容最后才用真机测原生交互。调试时记得用控制台里的 vConsole小程序端可以使用真机调试的 vConsoleApp 端则可以用 HBuilderX 自带的调试工具查看日志。2.2 六个入口文件各自管什么很多新手卡在“入口文件”这一关其实 uni-app 项目里需要理解的入口就那么几个main.js、App.vue、manifest.json、pages.json、uni.scss如果跑 H5 还有一个index.html。main.js是整个应用的 JS 入口Vue 实例在这里创建全局组件、全局混入、全局方法都在这里挂载。App.vue是应用根组件里面不写模板主要放应用级生命周期onLaunch、onShow、onHide以及全局样式。pages.json是页面路由和窗口样式的总配置相当于微信小程序的app.json。manifest.json是应用配置包含应用名称、图标、各平台的 AppID、SDK 配置。uni.scss是全局样式变量文件你可以把主题色、公共间距都定义成变量。还有一个容易被忽略的细节框架内置了/这个路径别名默认指向项目根目录。如果你的代码放在src目录下/指向src组件里引用自己写的模块时尽量用/而不是相对路径因为页面层级一深那些../../../很容易把人搞晕。移动端项目结构里文件位置经常调整用别名可以减少重构时的低级错误。2.3 pages.json 和 manifest.json 容易踩的配置坑pages.json里pages数组的第一个元素就是应用启动后的首页这里写错路径启动就会白屏或者报路由找不到。每个页面的window字段控制导航栏标题、背景色、下拉刷新等。tabBar 页面必须出现在pages数组中而且iconPath用的图片不能放在远程地址必须是本地静态资源。另一个常见坑是navigationBarTitleText没写页面顶部标题会一直是欢迎使用看起来像没改配置。manifest.json的坑更多。微信小程序如果没有填正确的 AppID很多 API 会被限制真机体验根本跑不通App 端如果要使用地图、支付、推送等模块需要在这里配置对应 SDK 的 key漏了的话运行时不会报编译错误但点击相关功能就是没反应。每次修改manifest.json最好重启编译或者重新运行项目因为某些配置是编译期读取的热更新并不会自动重新加载。我见过有人改了 AppID页面一直同步不上最后发现是微信开发者工具里的本地设置没有改成同一 AppID这类问题排查起来非常浪费时间。3. Vue3 组合式 API 在 uni-app 里怎么落地3.1 ref 为什么被叫万能对象热搜词里有个“ref 万能对象”这个词其实很形象。Vue3 的ref能包裹任何类型的值基本类型、对象、数组、Map、Set 都能包。它返回一个带有.value属性的响应式引用在模板里使用时会自动解包所以你写{{ count }}就行不需要手动.value。但在 script 里操作它就必须写count.value。为什么说万能因为当你需要把一个普通值变成响应式的时候ref是最直接的入口不需要关心它到底是个数字还是复杂对象。举个例子一个购物车列表你完全可以用ref([])来声明向里面 push 新商品时页面会更新给整个列表重新赋值也会更新。以前在 Vue2 里修改数组要担心索引赋值不响应到了ref Vue3 这套响应式系统里这些问题基本不需要再操心。这里我有一个实际经验ref对象存在reactive对象里时会被自动解包但只限于第一层。如果ref嵌套在数组里比如reactive({ list: [ref(1), ref(2)] })数组里的ref不会被自动解包要用.value。这个细节我在封装复杂表单数据时踩过一刚开始数据总是显示不对排查半天才发现是数组里套了ref。3.2 ref 和 reactive 怎么选ref和reactive都能做响应式数据我个人的项目里默认用ref基本不用reactive。原因很简单reactive只能包裹对象而且直接对变量整体重新赋值会丢失响应性。比如let state reactive({ name: 张三 }); state reactive({ name: 李四 })这个操作在 setup 里执行后页面不会更新因为state这个变量已经指向了新的对象响应式连接断掉了。而ref不同它内部始终是那个带.value的引用对象你给.value赋新值响应式依然成立。在实际业务里这种“整体赋值”很常见比如登录后把从接口拿到的用户信息一次性丢进状态。用ref就是userInfo.value res.data干净利落。用reactive就得先Object.assign(state, res.data)或者逐个字段赋值写起来很别扭。所以我的建议是团队统一用ref配合computed处理派生数据配合watch处理副作用遇到嵌套层级比较深的数据就用ref包裹再配合不可变更新。这样统一风格的好处是 code review 的时候不会为“这里到底该用哪个 API”争论新手也容易上手。3.3 页面生命周期与 setup 的配合uni-app 的页面生命周期和普通 Vue 组件的生命周期是有区别的。页面级的onLoad、onShow、onReady、onHide这些是从dcloudio/uni-app里导入的 API在script setup里直接调用就能用。比如想拿到页面跳转带的参数就写onLoad(options { console.log(options.id) })。但要注意这些页面生命周期只能在页面组件里调用放到普通子组件里会报警告或者不生效连在组合式函数里引入也要格外小心因为组合式函数被普通组件复用时生命周期钩子可能不在预期的时机触发。我还经常看到有人在setup里发登录请求这其实不太合理。setup执行时机非常靠前此时页面路由参数还没拿到页面可能还没准备好。正确做法是把请求放到onLoad或onShow里触发。有些业务是每次进入页面都要刷新数据比如订单列表那就在onShow里拉接口如果只需要首次加载就放onLoad。这个选择直接影响交互体验进了页面数据半天不刷和反复刷请求都令人崩溃。我自己的原则是页面维度的事放在页面生命周期里组件维度的事放在 Vue 生命周期里不要混着用。4. 用户登录从登录页到状态管理的完整闭环4.1 登录页面的表单校验和防重复提交用户登录功能是很多 uni-app 项目的第一个核心业务这里面的水其实挺深。先说登录页我见过不少项目直接把账号密码塞进状态就发请求校验全靠后端体验很糟糕。基础校验至少要有账号不能为空、密码不能为空、长度要符合规则。可以用简单的 if 判断也可以用第三方校验库但建议别过度设计几条规则手写 if 就够真正复杂的格式校验留给后端。校验不通过的时候给用户一个明确的提示最好提示具体是什么没填对而不是笼统的“输入有误”。防重复提交是另一个重要的细节。用户点了登录按钮如果网络慢有可能连点好几次每次都发请求。我一般在提交函数开头判断一个loading状态if (loading.value) return然后loading.value true请求结束再置为false。按钮同时显示“登录中...”并禁用视觉上也要防止用户继续点击。还有一个容易被忽略的点密码框要用password类型避免在页面上明文展示如果输入的是手机号键盘类型要设置成number方便移动端用户。4.2 封装 request 请求模块与 token 管理我几乎从不在业务代码里直接调用uni.request而是封装一层请求模块。统一封装有几个直接好处baseURL 只写一遍每个请求自动带上 token错误处理不用每个页面重复写还能统一处理登录过期跳转。简单封装可以这么写在utils/request.js里导出一个函数内部用Promise包装uni.request发起前从uni.getStorageSync(token)取出 token 放进 header收到响应后先看 HTTP 状态码再按后端约定的业务码处理。后端返回的数据结构如果统一是{ code, data, message }那么页面上调用时基本只需要关心data。token 管理看起来简单但有几个坑。第一uni.setStorageSync是同步操作不会阻塞后续代码但读出来的数据可能会被其他代码误改所以最好封装成getToken/setToken函数统一从这个接口走。第二token 有时效性过期后后端通常会返回 401 或者自定义的登录态失效码。我在封装层会统一拦截这种状态清理本地登录信息然后跳转到登录页。但这里要注意防抖如果页面同时发出三个请求每个都返回 401就会连续触发三次跳转。简单做法是定义一个全局标志位已经在跳转就不重复跳了。4.3 登录状态恢复与路由拦截用户登录后状态要能从本地恢复而不是每次冷启动都重新登录。我的做法是在App.vue的onLaunch里检查本地有没有 token有的话就调用“获取用户信息”的接口把用户数据放到全局状态没有就什么都不做。这个过程要放在onLaunch因为它只在应用启动时执行一次。有的项目会把登录态恢复放在首页的onLoad这样如果用户从某个页面深链接进来首页还没加载登录态可能就先发生了错乱。路由级别的拦截可以用uni.addInterceptor它类似于 Axios 的拦截器可以在uni.navigateTo、uni.redirectTo、uni.reLaunch这些跳转方法执行前做统一判断。比如维护一个白名单数组里面放“登录页、注册页、隐私政策页”如果目标页面不在白名单里并且本地没有 token就直接重定向到登录页。这个方案比每个页面手动检查要清爽得多新增页面时只要在路由表里声明“是否需要登录”拦截器自动处理。不过要注意拦截器不是所有跳转 API 都默认生效需要逐一注册并且注意在 App 端有一定兼容性限制实测后最稳的平台是 H5 和微信小程序。5. 微信小程序适配绕不开的差异化问题5.1 条件编译处理平台差异uni-app 虽然宣称一套代码多端运行但实际项目里微信小程序和其他端的差异一定会出现。处理差异的首选方案是条件编译写法是// #ifdef MP-WEIXIN和// #endif。它和普通注释不同编译时不是简单忽略而是由编译器决定保留还是删除代码块。这样就能在一个文件里同时维护两端逻辑比如 App 端用plus.push做推送小程序端用uni.subscribeMessage做订阅消息用条件编译包起来切换平台编译时只会带出对应代码。我见过有团队用“复制页面 两端各写一套”的方式处理差异短期看起来快长期维护成本是双倍改个按钮文案要改两处。条件编译虽然带点魔法但它让差异局部化既不破坏共用逻辑又能自由使用各平台能力。需要注意条件编译不是瓦罐里随意用的文件、样式、变量、配置都可以用它但别把整个页面写两遍否则就失去了 uni-app 的意义。尽量把差异收敛到函数级别或者用uni.getSystemInfoSync拿到平台信息后进行运行时判断二者结合效果最好。5.2 页面栈、tabBar 和键盘的坑微信小程序的页面栈有上限一般是十层。如果用户不停从详情页 A 跳到详情页 B再到详情页 C到达上限后uni.navigateTo会失败页面看起来像卡住。这个问题在 uni-app 里很隐蔽因为 H5 端没有这个限制。我在项目里定了规矩列表到详情用navigateTo详情返回列表用navigateBack而涉及跳 tabBar 页面必须用uni.switchTab不能用navigateTo否则会直接报错页面不存在。需要清空页面栈重新进某个页面时用uni.reLaunch或者uni.redirectTo代替。键盘顶起页面是另一个常见体验问题。输入框在小程序里聚焦时底部按钮经常被键盘盖住解决方案是给需要滚动的区域加adjust-position处理或者监听onKeyboardHeightChange动态调整按钮位置。如果项目里用到了自定义导航栏还要注意状态栏高度适配不同手机的胶囊位置、刘海高度都不一样。这里建议直接用uni.getSystemInfoSync()拿状态栏高度再通过计算给占位视图赋值而不是写死像素值否则会有一大片安卓机型不适配。5.3 小程序登录与手机号授权微信小程序的登录机制和其他端不太一样。它没有传统的用户名密码而是通过uni.login拿到临时 code再把 code 传给后端后端调微信接口换取 openid 和 session_key然后由后端生成你们自己的 token 返回给前端。这个 token 才是你识别用户身份的唯一凭证。拿到 token 后建议继续调用uni.getUserProfile获取头像昵称但这里要注意现在微信对开发者获取用户昵称头像的接口限制比较多许多场景已经推荐用“头像昵称填写能力”让用户主动填写而不是直接获取。手机号授权是另一个小程序特色。需要用户触发button的open-typegetPhoneNumber然后在回调里拿到 code再把 code 交给后端解密前端拿不到完整手机号。这里必须提醒这个能力需要小程序已经通过企业认证个人主体小程序无法使用。而且手机号授权不能作为唯一登录方式因为用户可能拒绝授权。我在项目里的做法是微信登录作为主登录手机号作为一个可选绑定项弹窗里讲清楚用途不强制。这种设计相比强制授权用户流失率明显更低。6. 安卓离线打包从云打包到本地 APK 的完整路径6.1 云打包和离线打包怎么选uni-app 打包成 App 有两条路云打包和离线打包。云打包是把你项目的资源上传到 DCloud 的服务器由服务器帮你完成打包你只需要准备一个证书。好处是本地不用安装 Android Studio、不用配 Java 环境鼠标点几下就能出包。缺点也很明显打包过程依赖网络和服务器排队高峰期可能等很久如果想接入比较复杂的原生 SDK或者公司要求必须在自己服务器上出包云打包会受限。离线打包是在本地用 Android Studio 编译优势有三个。一是构建过程完全可控适合自动化交付二是能更方便地接入公司的内部原生库和签名体系三是本地调试效率高不用每次改原生配置都上传等半天。代价是环境搭建有门槛Android SDK、JDK、Gradle 版本稍不注意就装不对。我自己的建议是个人练手项目用云打包没问题但公司里涉及正式交付、安全合规、特殊原生模块的项目一定要掌握离线打包否则临时要加一个原生功能会非常被动。6.2 安卓离线打包的准备工作与操作步骤离线打包前先把环境准备好Android Studio 最新稳定版、JDK 17 或 Android Studio 自带的 JBR、Android SDK 配合 Gradle 版本。接着在 HBuilderX 里选择“发行 - 原生 App 云资源”让工具生成离线打包用的 App 资源包这个资源包实际上就是你要嵌入原生工程的assets/apps/__UNI__你的Appid目录。然后从 DCloud 官网下载对应版本的“Android 离线打包 SDK”用 Android Studio 打开里面的原生工程。合并资源时把刚才生成的 App 资源包整个拷贝到原生工程的app/src/main/assets/apps下目录名必须是__UNI__你的Appid不能改。再打开项目的AndroidManifest.xml确认包名、权限和证书签名。这里最大的坑是 AppKey在 DCloud 开发者中心申请 AppKey 时填写的包名和签名必须和本地 Android Studio 里的一致否则 App 启动后会提示“AppKey 校验失败”。所以签名的 keystore 一定要提前生成并且把签名信息、包名记录好。最后在 Android Studio 里选 Build - Generate Signed APK填好 keystore 信息就能打出正式包。第一次打包很容易碰到 Java 版本或 Gradle 版本冲突建议新建一个空模板先跑通一次再往里面加自己的东西。6.3 uni-app x 离线打包有哪些不同uni-app x和经典 uni-app 是两套不同的产品体系不能只用 uni-app 的经验去套它。uni-app x 基于 uts 语言和 Vue3编译到 App 端时是用原生渲染而不是以前那套 WebView 方案所以性能和原生能力都要强不少。但这也意味着离线打包的逻辑有变化它需要更完整的 Android 原生工具链有时还需要配合对应版本的uni-app x 离线打包 SDK单独下载不能拿普通 uni-app 的 SDK 替换。实际操作时建议优先去 DCloud 官方文档里找当前版本的“uni-app x 离线打包指南”因为 uni-app x 还在快速迭代不同版本之间 SDK 差异很大。打包产物的包名、版本号、appkey 校验思路类似但原生插件接入要遵循新的方式比如自定义模块需要使用 uts 插件工程来管理。如果遇到编译错误最容易的原因是 HBuilderX 版本和离线 SDK 版本对不上升级 HBuilderX 之后最好重新下载最新离线 SDK 再打一次包。7. 常见问题排查与新手避坑清单7.1 白屏和页面打不开白屏是 uni-app 新手最容易遇见的综合性问题。首先检查pages.json里第一个页面路径是否正确必须对应真实的.vue文件路径包括大小写和目录层级然后看main.js里是否创建了 Vue 实例并app.mount如果有语法错误启动时会直接白屏。H5 端可以按 F12 打开控制台看具体报错小程序端在微信开发者工具里看 Console 和 SourceApp 端通过 HBuilderX 控制台或者 Log 输出看异常。还有一种情况是安装了插件但没在main.js里注册页面引用了不存在的组件也会白屏这类错误在控制台里一般有明确报错仔细看就不难找。7.2 请求失败与跨域H5 端发请求最容易遇到跨域浏览器对跨域限制很严格而后端接口往往不会专门为前端开发环境开 CORS。解决办法是在开发环境用devServer的代理转发或者让后端临时开一个允许跨域的配置。微信小程序端没有跨域问题但要求所有请求域名必须在小程序后台配置为 request 合法域名开发阶段可以勾选“不校验合法域名”生产环境必须提前配好。这里提醒一下域名必须是 HTTPS不能是 IP也不能带端口。App 端基本没这些限制但要检查是否在 manifest.json 中配置了网络访问权限否则请求直接失败连错误信息都很模糊。7.3 登录态频繁失效登录态失效会表现为页面里操作到一半突然弹出“请重新登录”或者请求时不时返回 401。排查时先看后端 token 的有效期是多长前端是否在过期前做了自动刷新再看前后端时间是否一致很多系统因为服务器和手机时间相差几分钟导致 token 校验失败。更隐蔽的问题在并发请求同一时刻三个请求同时过期都触发登录跳转用户会被反复弹登录页。我在封装层已经处理过这个场景核心就是“只跳一次”。另外本地存储的 token 不要搞多个 key比如 localStorage 里存一个、storage 里又存一个读取时各自为政后面排查起来都想骂人。7.4 新手最容易踩的五个坑第一个坑是用 npm 安装依赖后忘了重启或重新编译页面一直报模块找不到。第二个坑是把浏览器特有 API 当 uni-app 通用能力用在模板里绑定window.innerWidth之类编译到小程序直接报错应该用uni.getSystemInfoSync()。第三个坑是修改数组用普通下标赋值然后发现页面不更新虽然现在 Vue3 的代理已经解决了一部分但在某些嵌套场景下还是建议用新的数组方法或者整体重新赋值。第四个坑是给 tabBar 页面用navigateTo跳转结果各种诡异报错正确姿势是switchTab。第五个坑是随意升级 HBuilderX 到最新版之后原本正常的插件不能用了生产项目建议锁定版本等插件兼容了再升级。我个人在实际项目里的体会是别把 uni-app 当成万能工具也别一开始就追求所有端一次跑通。最稳妥的路径是先选定一个主平台比如微信小程序把核心功能做到稳定然后再用条件编译和真机测试逐步铺开 App 和 H5。登录闭环、请求封装、页面拦截这三件事是几乎所有项目的底座把它们打磨好后面往上堆业务功能会顺手很多。离线打包这类原生操作不用着急等确实需要正式发版或者接入原生 SDK 时再学一次踩完坑后就能沉淀出自用的打包流程。希望这些记录能帮你少走几段弯路做出来的项目既快又能扛得住真实使用。
