1. uni-app小程序开发环境搭建与基础配置
作为一款基于Vue.js的跨平台开发框架,uni-app让开发者能够使用一套代码同时发布到iOS、Android以及各种小程序平台。我在实际项目中发现,搭建一个高效的开发环境能显著提升后续开发效率。
首先需要安装HBuilderX作为主力开发工具,这是官方推荐的IDE,内置了uni-app项目模板和调试工具。安装完成后,建议立即配置以下关键插件:
- eslint-plugin-vue:用于Vue语法校验
- uni-app-snippets:代码片段自动补全
- uni-helper:API智能提示
基础项目创建时有个关键选择:是否启用uni-app的Vue3版本。根据我的经验,如果是新项目且团队熟悉Vue3,建议直接选择Vue3版本,其Composition API在复杂业务场景下更有优势。创建命令如下:
bash复制# Vue2版本
vue create -p dcloudio/uni-preset-vue my-project
# Vue3版本
npx degit dcloudio/uni-preset-vue#vite my-vue3-project
2. 多平台适配与样式处理技巧
uni-app的最大优势在于跨平台,但这也带来了样式适配的挑战。经过多个项目实践,我总结出以下核心适配方案:
2.1 响应式单位使用策略
推荐使用upx(uni-app像素单位)作为基础单位,它会自动根据屏幕宽度进行换算。但在实际项目中,我发现纯upx方案在某些安卓设备上会出现计算误差,更稳妥的做法是:
css复制/* 基础方案 */
.element {
width: 750upx; /* 满屏宽度 */
}
/* 增强方案 */
@media screen and (min-width: 768px) {
.element {
width: 100%;
}
}
2.2 平台条件编译实战
不同平台可能需要完全不同的实现方式。uni-app的条件编译非常实用:
javascript复制// #ifdef MP-WEIXIN
wx.login({
success(res) {
console.log('微信登录成功', res)
}
})
// #endif
// #ifdef H5
console.log('这是H5环境')
// #endif
3. 微信小程序专项优化方案
虽然uni-app支持多平台,但微信小程序仍然是国内最主要的发布平台。针对微信小程序,有几个关键优化点:
3.1 分包加载配置
随着项目体积增大,必须配置分包。在manifest.json中:
json复制{
"mp-weixin": {
"optimization": {
"subPackages": true
},
"subPackages": [
{
"root": "packageA",
"pages": [
"pages/cat",
"pages/dog"
]
}
]
}
}
3.2 双Token认证实现
对于需要高安全性的应用,推荐实现双Token机制(access_token + refresh_token)。在uni-app中可以通过拦截器实现:
javascript复制// utils/http.js
const http = new Request({
config: {
baseURL: 'https://api.example.com'
},
interceptor: {
request(config) {
config.header.Authorization = `Bearer ${store.state.token}`
return config
},
response(response) {
if (response.statusCode === 401) {
return refreshToken().then(() => {
return http.request(response.config)
})
}
return response.data
}
}
})
4. 性能优化与调试技巧
4.1 图片加载优化方案
小程序中图片加载是性能瓶颈之一,我们采用三级优化策略:
- 使用image组件的lazy-load属性
- 重要图片预加载到本地缓存
- 非关键图片使用CDN并添加webp格式支持
html复制<image
:src="imgUrl"
mode="aspectFill"
lazy-load
@load="handleImageLoad"
></image>
4.2 真机调试技巧
开发过程中有几个必知的调试命令:
bash复制# 开启自定义编译条件
npm run dev:mp-weixin -- --my-flag
# 查看详细日志
export UNI_DEBUG=true && npm run dev:mp-weixin
5. 常见问题解决方案实录
5.1 下载文件类型限制问题
遇到saveVideoToPhotoAlbum:fail invalid file type错误时,需要检查文件后缀和实际类型是否匹配。解决方案:
javascript复制uni.downloadFile({
url: 'https://example.com/video.mp4',
success(res) {
if (res.statusCode === 200) {
uni.saveVideoToPhotoAlbum({
filePath: res.tempFilePath,
success() {
console.log('保存成功')
}
})
}
}
})
5.2 导航栏高度适配
获取微信小程序导航栏高度的可靠方法:
javascript复制const getNavBarHeight = () => {
const systemInfo = uni.getSystemInfoSync()
const menuButtonInfo = uni.getMenuButtonBoundingClientRect()
return menuButtonInfo.bottom + menuButtonInfo.top - systemInfo.statusBarHeight
}
6. 项目架构与代码组织建议
经过多个uni-app项目实践,我总结出一套高效的目录结构:
code复制src/
├── common/ # 公共资源
│ ├── icons/ # 字体图标
│ └── styles/ # 全局样式
├── components/ # 公共组件
│ ├── base/ # 基础组件
│ └── business/ # 业务组件
├── pages/ # 页面目录
│ ├── index/ # 首页
│ └── user/ # 用户中心
├── services/ # 服务层
│ ├── api/ # 接口定义
│ └── modules/ # 模块化服务
├── stores/ # 状态管理
└── utils/ # 工具函数
对于字体图标的使用,推荐以下方案:
- 将iconfont下载到本地
- 在App.vue中全局引入
- 创建icon组件统一管理
vue复制<!-- components/base/Icon.vue -->
<template>
<text
class="iconfont"
:class="`icon-${name}`"
:style="{ fontSize: size + 'px', color }"
></text>
</template>
7. 安全与隐私合规要点
随着平台审核越来越严格,隐私合规成为必须重视的环节。几个关键注意事项:
- 在manifest.json中正确声明权限:
json复制{
"mp-weixin": {
"permission": {
"scope.userLocation": {
"desc": "用于展示附近服务"
}
}
}
}
- 用户隐私协议必须单独弹窗授权,不能默认勾选。实现方案:
javascript复制uni.showModal({
title: '隐私协议',
content: '请阅读并同意用户协议',
confirmText: '同意',
success(res) {
if (res.confirm) {
// 用户同意后执行操作
}
}
})
- 敏感信息如声纹数据需要单独授权:
javascript复制function requestVoiceprintAuth() {
return new Promise((resolve) => {
uni.showModal({
title: '声纹授权',
content: '需要您授权使用声纹信息',
success(res) {
resolve(res.confirm)
}
})
})
}
8. 进阶开发技巧与模式
8.1 全局状态管理方案
对于复杂应用,推荐使用Pinia作为状态管理工具。配置示例:
javascript复制// stores/user.js
export const useUserStore = defineStore('user', {
state: () => ({
token: '',
userInfo: null
}),
actions: {
async login(credentials) {
const res = await api.login(credentials)
this.token = res.token
this.userInfo = res.user
}
}
})
8.2 混合开发模式
当需要接入原生功能时,可以使用uni-app的Native.js技术:
javascript复制// 调用原生Toast
const main = plus.android.runtimeMainActivity()
const Toast = plus.android.importClass('android.widget.Toast')
const toast = Toast.makeText(main, 'Hello Native', Toast.LENGTH_SHORT)
toast.show()
8.3 自动化部署流程
建立CI/CD流程可以大幅提升发布效率。推荐配置:
yaml复制# .github/workflows/deploy.yml
name: Deploy Mini Program
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- run: npm install
- run: npm run build:mp-weixin
- uses: wulabing/wechat-miniprogram-action@v1
with:
appid: ${{ secrets.APPID }}
version: ${{ github.sha }}
desc: 'Auto deploy'
project-path: './dist/build/mp-weixin'
private-key: ${{ secrets.PRIVATE_KEY }}
9. 项目实战经验总结
在最近开发的电商小程序项目中,我们遇到了几个典型问题及解决方案:
-
长列表渲染卡顿:
- 使用uni-app的
<scroll-view>+虚拟列表方案 - 实现分页加载,每页不超过20条数据
- 图片使用懒加载和占位图
- 使用uni-app的
-
表单验证复杂度高:
- 采用VeeValidate进行表单验证
- 自定义验证规则库
- 实现实时验证反馈
vue复制<template>
<uni-form :model="form" :rules="rules">
<uni-form-item prop="phone">
<uni-input v-model="form.phone" placeholder="请输入手机号" />
</uni-form-item>
</uni-form>
</template>
<script>
import { useField, useForm } from 'vee-validate'
export default {
setup() {
const { handleSubmit } = useForm()
const { value: phone } = useField('phone', validatePhone)
return { phone }
}
}
</script>
- 多端样式差异:
- 建立样式适配层(Style Adapter)
- 使用CSS变量定义主题
- 重要组件实现平台专属样式覆盖
css复制/* 适配层样式 */
:root {
--primary-color: #007aff;
}
/* 平台覆盖 */
/* #ifdef MP-WEIXIN */
:root {
--primary-color: #07c160;
}
/* #endif */
10. 持续更新与社区资源
uni-app生态正在快速发展,保持技术更新非常重要。我常用的资源渠道包括:
- 官方文档(及时查看更新日志)
- uni-ui组件库(官方维护的组件集合)
- DCloud插件市场(解决特定需求的现成方案)
- GitHub上的优秀开源项目(学习先进实践)
对于复杂功能实现,我的建议是:
- 先查官方文档是否有现成方案
- 搜索插件市场是否有合适插件
- 参考GitHub类似项目实现
- 最后考虑自己造轮子
在开发过程中,我习惯维护一个本地知识库,记录遇到的特殊案例和解决方案。例如:
markdown复制## 微信小程序特定问题
### 背景音频播放限制
- 解决方案:使用`uni.getBackgroundAudioManager()`
- 注意事项:必须配置`requiredBackgroundModes`
### 用户授权策略变更
- 新规则:部分API需要用户主动操作触发
- 适配方案:按钮点击事件中调用API
