小兔鲜儿 UniApp 项目 - 第五周综合笔记第五周学习内容主要涵盖项目收尾阶段的工作将开发完成的 uni-app 项目打包发布到不同平台。核心内容包括微信小程序打包全流程、条件编译处理多端差异、H5 端打包与路由配置。一、微信小程序端打包与发布1.1 整体流程将 uni-app 项目发布为微信小程序涉及三个工具的协作VSCode编码 编译 -- 微信开发者工具预览 上传 -- 微信公众平台审核 发布阶段工具做什么编译VSCode / 命令行执行pnpm build:mp-weixin将 Vue 代码编译为原生小程序代码调试微信开发者工具导入编译产物本地预览、真机调试、性能检测上线微信公众平台提交审核、灰度发布、正式上线1.2 编译产物执行pnpm build:mp-weixin后项目根目录生成/dist/build/mp-weixin文件夹。这个文件夹就是微信小程序的原生代码包包含app.js/app.json/app.wxss—— 小程序入口文件pages/—— 每个 Vue 页面对应一个原生页面文件夹含 wxml、wxss、js、jsoncomponents/—— 组件编译后的原生代码static/—— 静态资源需要注意的是开发时使用的/dist/dev/mp-weixin是开发编译产物含 sourcemap、未压缩上线时必须使用/dist/build/mp-weixin。1.3 微信开发者工具的正确导入导入时容易搞混路径正确选择/dist/build/mp-weixin目录错误选择项目根目录那是 uni-app 源码不是小程序代码错误选择/dist/dev/mp-weixin那是开发版不能用于发布导入后需要填入 AppID。如果只是本地预览可以用测试号但要上传发布必须使用已注册的小程序 AppID。1.4 上传与审核在微信开发者工具中确认预览效果无误点击工具栏上传填写版本号如 1.0.0和备注登录 微信公众平台进入管理 - 版本管理在开发版本中找到刚上传的版本点击提交审核等待微信官方审核通常 1-7 个工作日审核通过后点击发布用户即可搜索到该小程序也可以配置 CI/CD 自动上传微信官方提供了 miniprogram-ci 工具适合团队协作场景下的自动化流程。二、条件编译2.1 为什么需要条件编译uni-app 的核心理念是一套代码多端运行但不同平台存在本质差异微信小程序有专属 APIwx.login、wx.requestPayment、wx.chooseMedia网页端没有微信授权能力登录方式完全不同小程序支持特殊的按钮属性open-typegetPhoneNumberH5 不支持某些样式特性只在特定平台上生效如果不在代码中做平台区分轻则功能失效重则编译报错。条件编译就是用来解决这个问题的。2.2 基本语法条件编译使用特殊的注释语法这些注释在编译时会被处理不是普通的代码注释// #ifdef 平台标识 // 只有在指定平台才保留的代码 // #endif // #ifndef 平台标识 // 只有在非指定平台才保留的代码 // #endif#ifdef相当于如果定义了该平台if defined#ifndef相当于如果没定义该平台if not defined。支持多平台组合// #ifdef H5 || MP-WEIXIN // H5 端 或 微信小程序端都保留 // #endif2.3 条件编译的作用范围条件编译几乎可以出现在项目的任何文件中文件类型示例场景.vue的script调用平台特有 API.vue的template使用平台特有组件或属性.vue的style处理平台样式兼容.ts/.js平台特有逻辑pages.json不同平台的页面配置、tabBar 差异.scss/.css不同平台的样式变量2.4 实际应用场景场景一微信小程序特有 API小程序提供了wx.login()、wx.requestPayment()等专属 API在 H5 端调用会报错。这些调用需要用条件编译包裹// #ifdef MP-WEIXIN wx.login() wx.requestPayment() // #endif场景二平台特有的按钮能力小程序的button支持open-type属性实现特殊功能获取手机号、打开设置、客服会话等这些属性在 H5 端无效且可能引起警告!-- #ifdef MP-WEIXIN -- button open-typeopenSetting授权管理/button button open-typefeedback问题反馈/button button open-typecontact联系我们/button !-- #endif --场景三登录方式的差异化这是项目中最大的条件编译应用。微信小程序使用wx.login()getPhoneNumber实现一键授权登录而 H5 端需要传统表单登录。整个登录页的模板结构在不同平台下完全不同需要大段的条件编译区分。场景四样式兼容page { /* #ifdef H5 */ background-color: #f5f5f5; // H5 端背景色 /* #endif */ /* #ifdef MP-WEIXIN */ background-color: #f7f7f8; // 小程序端背景色 /* #endif */ }场景五pages.json 配置差异H5 端通常不需要底部 tabBar导航在顶部小程序端则需要{ tabBar: { // #ifdef MP-WEIXIN list: [ { pagePath: pages/index/index, text: 首页 }, { pagePath: pages/cart/cart, text: 购物车 }, { pagePath: pages/my/my, text: 我的 } ] // #endif // #ifdef H5 list: [ { pagePath: pages/index/index, text: 首页 }, { pagePath: pages/my/my, text: 我的 } ] // #endif } }2.5 开发注意事项条件编译注释必须以//开头不能使用/* */块注释代码写完建议搜索项目中的wx.、open-type等平台关键词确保所有平台特有代码都已被条件编译包裹条件编译的代码在不同的编译目标下会被完全移除不是隐藏所以不会增大其他平台的包体积三、H5 端打包3.1 编译与预览pnpm build:h5编译产物在/dist/build/h5是一个标准的静态网站目录结构index.html—— 入口文件static/js/—— 编译后的 JavaScriptstatic/css/—— 编译后的 CSSstatic/img/—— 图片资源本地预览直接用浏览器打开index.html即可。但如果路由基础路径配置不对可能会出现页面空白。3.2 路由基础路径manifest.json中h5.router.base决定了所有路由的前缀{ h5: { router: { base: ./ } } }配置值适用场景/部署在域名根路径如example.com//app/部署在子目录如example.com/app/./相对路径兼容性最好本地预览首选如果部署后资源 404JS/CSS 加载失败首先检查base是否和服务端路径匹配。3.3 H5 端与小程序端的主要差异能力微信小程序H5微信登录支持不支持需要自己实现微信支付支持wx.requestPayment不支持需走 H5 支付或扫码支付原生导航有原生导航栏和 tabBar全部需要自己写手机号授权支持getPhoneNumber不支持滚动驱动动画animate()方法不支持需用 CSS 或 JS 实现文件上传uni.uploadFile可用 axios 或 fetch分包加载支持无此概念包体积限制主包 2MB总包 20MB无限制但体积过大会影响加载速度这些差异就是条件编译需要处理的核心内容。项目开发的思路是以小程序为主要目标平台把小程序不支持的功能在 H5 端降级或提供替代方案。四、其他打包目标简介4.1 打包为 APP 端小兔鲜儿项目主要以小程序和 H5 为目标APP 端的打包使用 HBuilderX 工具完成。打包 APP 时使用的是 App 端的条件编译标识APP-PLUS。4.2 其他小程序平台打包到其他小程序平台百度、支付宝、字节跳动等的流程类似替换打包命令和对应的开发者工具即可。但需要注意不同平台的 API 支持程度不同可能需要额外的条件编译各平台的审核规范不同包体积限制不同如支付宝小程序主包限制 2MB五、TypeScript 补充5.1 环境变量import.meta.env.DEV // 开发模式为 true import.meta.env.PROD // 生产模式为 true项目中利用import.meta.env.DEV来区分开发/生产行为——支付模块在开发环境走模拟支付生产环境走真实微信支付模拟发货功能也只在开发环境显示。5.2 Page 类型扩展当 uni-app 的类型定义缺少某些平台特有方法时如微信小程序的animate需要通过类型扩展来补全// 基于小程序的 Page 类型扩展 uni-app 的 Page type PageInstance Page.PageInstance WechatMiniprogram.Page.InstanceMethodsany const pageInstance pages.at(-1) as PageInstance这种方式在保证类型安全的前提下让 TypeScript 不再报错同时 IDE 也能提供代码提示。六、项目整体回顾至此小兔鲜儿 uni-app 项目的全部模块学习完成周次模块核心内容第一周项目起步uni-app 脚手架、pages.json 配置、条件编译基础第二周首页 分类轮播图、分类导航、商品列表、下拉刷新第三周登录 用户 地址 SKU微信授权、个人信息、地址管理、SKU 弹窗第四周购物车 订单购物车 CRUD、订单流转、支付、物流第五周打包发布小程序打包、H5 打包、条件编译总结七、常见报错速查问题原因解决小程序运行白屏导入目录错误确认导入/dist/build/mp-weixin而非项目根目录微信开发者工具正常真机异常条件编译遗漏搜索wx.和open-type确保有#ifdef包裹H5 端 wx is not defined小程序 API 未条件编译所有wx.xxx用// #ifdef MP-WEIXIN包裹H5 本地预览空白路由 base 为绝对路径改为./相对路径打包后 H5 资源 404base 与服务器路径不一致按运维提供的路径调整h5.router.baseanimate方法 TS 报错uni-app 类型缺失扩展 Page 类型Page.PageInstance WechatMiniprogram.Page.InstanceMethodsany小程序上传失败未配置 AppID 或不是管理员在开发者工具中填入正确的 AppID真机预览未找到页面页面路径未注册检查 pages.json 是否包含该页面八、实用命令速查# 微信小程序开发热更新 pnpm dev:mp-weixin # 微信小程序打包 pnpm build:mp-weixin # H5 开发热更新 pnpm dev:h5 # H5 打包 pnpm build:h5