本篇文章是使用 uniapp 开发 h5 与微信小程序的一些踩坑总结与记录（至于 app 的跨端开发，那还是使用 [flutter](https://juejin.cn/post/7105196964597202974) 吧）。 # 开发 ## 使用 vue3 ### 新建项目在新建项目时勾选 vue3： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/bfe483d7d77746758c3f29b935a5b8bf~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=554\&h=866\&s=89681\&e=png\&b=fcf9f4) 在首次运行时，HBuilder 会自动安装相关插件： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/926e67d4fe184cd999f2778e83d4e35b~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=379\&h=111\&s=5522\&e=png\&b=fefbf2) ### props 接收路由传参使用 vue3 创建的项目，路由传参可以通过 `props` 接收，这功能在 [Vue Router 的官方文档](https://router.vuejs.org/zh/guide/essentials/passing-props.html)也有提及。 ## 样式 ### 全局样式在 uni.scss 文件定义或引入的 sass 变量，全局可以直接使用而无需 `@import` 引入。在 App.vue 页面的 ` ``` * 引入外部 css 文件可以使用 `@import url` 或 `@import`，它们的区别在于 `@import url` 可以引入网络文件，而 `@import` 只能引入本地文件； * 在 sass 中，只能使用 `@import` 引入外部 scss 文件，且后缀 .scss 可以省略。如果使用了 `@import url` 或者 `@import` 引入的是 css 文件，则不会导入 sass 文件而只是作为普通的 css 语句原封不动地照搬到编译后生成的 css 文件中； * 使用 sass 时，HBuilder 会自动安装相关插件，然后在 ` ``` 在小程序端每个页面的根元素就是 ``： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ed5d9e7481e9451c9419b6a51a6e64f4~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=461\&h=571\&s=28044\&e=png\&b=fcfcfc) 在 h5 端会生成自定义元素 ``： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/91b17bbddfe2477ea7ec7e68bd2f213f~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=691\&h=244\&s=41762\&e=png\&b=fefdfd) ### 关于 scoped 在 h5 端，写在页面或组件的样式，默认就是只在当前页面或组件生效，不需要写 `scoped`；但是在微信小程序端则需要明确写上 `scoped` 才可以为 css 指定作用域。 ### 适配刘海屏（异型屏）微信小程序端，有些页面头部的内容在 iphone6 等非刘海屏显示正常，在 iphone13 等异型屏会有问题。uniapp 中通过 css 变量 `--status-bar-height` 来设置状态栏高度，在小程序里固定为 `25px`，这是会有问题的。可以通过 `uni.getSystemInfo` 获取真实的 `statusBarHeight` 赋值给自定义的变量 `qyStatusBarHeight`，然后通过在每个页面文件的第一个节点设置 ``： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/88c2b2b29c6f4938ba55cabe535a6333~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=652\&h=199\&s=16034\&e=png\&b=fffae8) 在 `pageStyle` 中设置获取到的真实的状态栏高度等 css 变量： ```javascript this.pageStyle =`--qy-status-bar-height: ${qyStatusBarHeight}px;` ``` 为了让 h5 端也可以找到 `--qy-status-bar-height`，别忘了在样式文件中进行设置： ```css :root { --qy-status-bar-height: 0px; // ... } ``` 之后就可以在需要设置顶部安全区域的地方使用 css 变量 `--qy-status-bar-height` 了。屏幕底部的安全区域也可以通过 `uni.getSystemInfo` 返回的结果中的 `safeAreaInsets.bottom` 得到： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f9e293b49f2c4962b45e315229916898~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=265\&h=530\&s=12801\&e=png\&b=fefefe) ### 内置组件 input 的 placeholder 样式通过 [placeholder-class](https://uniapp.dcloud.net.cn/uni-app-x/component/input.html#%E5%B1%9E%E6%80%A7) 属性设置 placeholder 的样式类时，为了适配小程序端，需要将样式类定义在不带 `scoped` 的 ` ``` iconMixin.js 文件如下，主要是对样式的处理： ```javascript export default { props: { // icon 的名称 flag: { type: String, required: true }, classArr: { type: Array, required: false }, iconStyle: { type: Object, required: false } }, computed: { iconfontClass() { if (this.classArr) { return [...this.classArr, this.flag] } else { return [this.flag] } } } } ``` 使用时，如果传递的类名是定义在当前 vue 文件的，则需要添加 `::v-deep` 方可生效： ```vue ``` 在设置字体图标项目时，字体格式可以只勾选 WOFF 和 TTF： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f3c6c02586b04b1da06048fe63b31ab8~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=590\&h=546\&s=22180\&e=png\&b=fefefe) 微信小程序官方文档的建议也就是选择这两个： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/445ebffc550c47009a11df9b8e0f4ebc~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1732\&h=451\&s=52415\&e=png\&b=f9f9f9) ### 多色图标对于类似下图所示的多色图标： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/dbc79cd921a34a0f8cb5af80d6b89de5~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=290\&h=174\&s=5754\&e=png\&b=fcfcfc) 则添加到另一个项目，在 h5 端使用 svg 的 symbol 方式引用，在小程序端则依然采用字体图标的方式，对应封装的是 ``： ```vue ``` 使用时，如果多色图标在变为单色后依然可以使用，则直接使用（注意，该图标也需要添加到单色图标那个项目中去）： ```html ``` 如果多色图标改为单色后不可用，则该图标仅仅需要存在于多色图标项目，在微信小程序端另外挑选其它近似的纯色图标： ```html ``` ### 其它说明 * 之所以要分成 2 个项目，是为了尽可能减小 main.js 引入的图标相关文件的大小，减少打包体积： ```javascript // #ifdef H5 import './static/iconfont/iconfont.js' // 来自多色图标项目 // #endif import './static/iconfont/iconfont.css' // 来自单色图标项目 ``` * 对于 iconfont.css 文件，记得要更改 `@font-face` 里的文件引用路径，改为以 `~@` 开头的绝对路径（一般在 css 中都是使用 `~@` 而在 js 中使用 `@`）： ```css @font-face { font-family: 'iconfont'; src: url('~@/static/iconfont/iconfont.woff') format('woff'), url('~@/static/iconfont/iconfont.ttf') format('truetype'); } ``` * 字体图标的文件组织如下： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/20d0679f956d4e34baa14f2c6717a816~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=371\&h=175\&s=20121\&e=png\&b=fdf7e4) 当下载到本地的字体文件小于 40kb 时，在小程序端 uniapp 会自动将其转为 base64 格式以兼容小程序。 ## 不支持动态组件在微信小程序上是不支持使用 `` 然后通过 `is` 属性来渲染动态组件的，这一点在 [uniapp 的官方文档](https://uniapp.dcloud.net.cn/tutorial/vue-api.html#%E5%86%85%E7%BD%AE%E7%BB%84%E4%BB%B6)有说明： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e6f12b8c5c3147a6a6a7d567994756cc~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1397\&h=190\&s=20730\&e=png\&b=ffffff) ## 不支持自定义指令在微信小程序端是不支持 vue 的自定义指令的。 ## 不能在子组件直接修改 props 接收的父组件的值这句话乍看上去好像是句废话——这不就是 vue 官方文档的规范吗？但我在做一个页面时，使用到了 uView 框架的 Checkbox 复选框，该组件需要通过 `v-model` 绑定一个类型为布尔值的变量： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/68cbb4cd71104ce0a2cb6b6e1d956880~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=332\&h=217\&s=13221\&e=png\&b=fff9e7) 而我赋值的 `item.checked` 的 `item` 是从父组件传入的数组 `unpaidList` 的成员： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/4c9663c2e30f402d85a1e22dd0564153~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=231\&h=128\&s=4083\&e=png\&b=fffae8) 这么写在 H5 端一切正常，但是在微信小程序端会发现点击复选框没有效果。其原因就是点击复选框时会在子组件改变 `item.checked` 的值，相当于改变了 `props` 接收的父组件的 `unpaidList`，所以会导致点击失效。解决办法就是在 change 事件发生时，向父组件发射 `checkboxChange` 事件，然后由父组件更改对应 `item` 的 `checked` 的值： ```javascript checkboxChange(e) { this.$emit('checkboxChange', e) } ``` ## 值为 null 或 undefined 当接口传递的值为 `null` 或 `undefined` 时，微信小程序会直接显示 null 或 undefined，所以可以使用 `v-if` 做下判断，或是 vue2 中的 filter 做下处理。 ## 表单的验证使用 uView 的表单组件时，如果某一添加了必填验证的表单项有默认值，该值若是数字类型的：`submitForm: { quantity: 1 }`，要改为字符串类型：`submitForm: { quantity: '1' }`，否者提交表单时会报错： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ee35364918a54d87b953a4d5afe93c32~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=421\&h=85\&s=2377\&e=png\&b=ffffff) ## `` 组件的 `@input` 使用 uView 的 `` 组件，添加的 `@input` 事件，在微信小程序端，当删除输入框内容时，删除到最后清空的那一下操作不会触发 `@input` 事件，解决办法是可以配合 `watch` 来监听输入框值的变化。 ## ``组件中的空格 `` 组件中，空格最好使用 ` ` 表示，如果直接使用空格键敲出的空格： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c0959b05290d499e93c125b7c7cafe92~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=698\&h=350\&s=18484\&e=png\&b=fffae8) 在编译后可能导致换行： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/fb50a26f63b745998b9e7ba526d592fc~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1139\&h=310\&s=45157\&e=png\&b=fdfdfd) ## 小程序分享按钮如果要让小程序页面点击后弹出的菜单中分享按钮可用： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/83e00ea8c6a24ab59285e5071914d9c5~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=385\&h=817\&s=92695\&e=png\&b=f2f2f2) 需要在页面添加如下代码： ```javascript wx.showShareMenu({ withShareTicket: true, menus: ['shareAppMessage', 'shareTimeline'] }) ``` ## 网络请求 - `data` 不支持 formData 格式的数据： ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/a902a3faf48e4580acefbd9fe50a7323~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1684&h=238&s=33184&e=png&b=ffffff) - GET 方法请求传参时（query string），微信小程序端参数值不能是 `undefined`； # 运行 ## 运行时如果没有自动打开浏览器或微信开发者工具可以在 HBuilder X 中打开“运行”菜单： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/10abd08303864a56a214f0008789ed9b~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=682\&h=637\&s=65628\&e=png\&b=fefbf1) 在运行设置里设置浏览器或微信开发者工具的路径： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/42e52c68baa547dda44825cbe9e6fb84~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=637\&h=623\&s=43769\&e=png\&b=fef9e9) 另外，运行小程序还需要在微信开发者工具开启服务端窗口：“设置 - 安全设置“ 以让 HBuilder 可以启动微信开发者工具： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ebfeb0689c344f5aaf70cb99e89cc79c~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=684\&h=241\&s=15532\&e=png\&b=f8f8f8) ## 手动运行小程序如果自动打开微信开发者工具失败，也可以直接通过微信开发者工具打开打包后的位于项目根目录下的 unpackage\dist\dev\mp-weixin 来手动运行小程序（dev 目录下的是开发版，build 目录下的是生产版）。 ## 公众号网页调试在微信开发者工具中，通过“项目 - 更换开发模式”切换： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5706497a35e544b78351d1323a634549~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=437\&h=222\&s=15906\&e=png\&b=f6f6f6) 然后在新打开的窗口上方地址栏输入网页的地址即可： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/96a4bc3059bd48e08b49c7bd887182be~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=953\&h=104\&s=6717\&e=png\&b=ececec) # 打包 ## 减小主包的方法在打包上传微信小程序时，会要求主包大小不能大于 1.5M，下面介绍几点减小主包的方法。 ### 分包在 manifest.json 开启分包： ```json "mp-weixin": { "optimization": { "subPackages": true } }, ``` pages 目录下的页面会被放入主包，分包可以在 pages.json 中设置 `subPackages`，注意 `root` 的值不能是 `pages`： ```json // #ifdef MP-WEIXIN "subPackages": [{ "root": "subPages", "pages": [{ "path": "contact-information/contact-information", "style": { "navigationBarTitleText": "联系方式", "enablePullDownRefresh": false } }] }], // #endif "pages": [ // #ifdef H5 { "path": "subPages/contact-information/contact-information", "style": { "navigationBarTitleText": "联系方式", "enablePullDownRefresh": false } }, // #endif ] ``` 如此，subPages 目录下的页面就会被放入分包。 ### 按需引入 lodash 为了减小打包后的体积，要使用 lodash 中的哪个方法就按需引入哪个方法，比如 `import cloneDeep from 'lodash/cloneDeep'`。 ### 时间格式化使用 day.js 而不是 moment.js 来实现时间格式化，因为前者的包体积按其官方说法只有 2 kb。 ## 查看主包大小在微信开发者工具点击“详情 - 基本信息 - 代码依赖分析”查看： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/7ff637312ab9480d833a3cf853edeebb~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=487\&h=629\&s=37901\&e=png\&b=f6f6f6) 得到的结果如下所示： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6c07709b2e42420ca8662076bfe14eac~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1334\&h=889\&s=130513\&e=png\&b=f9f2f1) ## 代码质量分析通过微信开发者工具的“详情 - 性能质量” tab，点击扫描代码质量即可： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ed23aa669f694fc3abf2a0c4999fee5b~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=1706\&h=788\&s=87830\&e=png\&b=f5f5f5) # 报错汇总 ## \[ app.json 文件内容错误] app.json: pages 不能为空 ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6bf2c0be64274b91bbd2ad3564bdc56c~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=416\&h=715\&s=21111\&e=png\&b=ffffff) 查看 pages.json 文件，删除自动生成的如下代码即可： ```json { "path": "App", "style": {} } ``` ## watcher 报错使用 uView 的表单组件时，遇到如下报错： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/5334595638fd4e2fb8c1b4f458423d50~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=732\&h=202\&s=25515\&e=png\&b=ebf1fb) 原因是某个 `` 的 `type` 属性使用了 `select`，在某些情况下，比如清空表单后，该表单项的值为 `null`，uView 内部处理去掉多余空格时就会报错： ![image.png](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/4a568f215cfb4fadb38a85cd8165f150~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=630\&h=117\&s=16622\&e=png\&b=fffefe) 解决办法是让重置时 select 表单项的值为 `''`。 ## 页面路径找不到如果报错什么页面路径找不到，可以检查下路径的最前面是否缺少 `/`。 ## 当前页面正处于跳转状态当进入某个页面后立即跳转另一个页面时会出现报错： ![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/b8191a622efc400492eeb1b59d961a35~tplv-k3u1fbpfcp-jj-mark:0:0:0:0:q75.image#?w=892&h=52&s=8999&e=png&b=fff0f0) 目前的解决办法是设置一定的延迟： ```javascript const t = setTimeout(() => { uni.reLaunch({ url }) clearTimeout(t) }, 400) ``` ![感谢.gif](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d160e26986d1447e8ef2dfe783fc6eb6~tplv-k3u1fbpfcp-watermark.image#?w=1920\&h=1080\&s=1605675\&e=gif\&f=125\&b=3f7b7d) ![点赞.png](https://p9-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/0a7fbbcaca1c480c942b7735a7228e9f~tplv-k3u1fbpfcp-watermark.image#?w=1800\&h=363\&s=230657\&e=png\&b=ffffff)