uni-app 跨端小程序开发实践
uni-app 是一个基于 Vue 技术栈的跨端开发框架，支持编译到微信、支付宝、字节跳动等多端小程序以及 H5 和 APP。它与 Vue 生态高度契合，上手快速，并且拥有丰富的模板和插件资源，非常适合业务型项目的快速落地。项目地址为 https://github.com/dcloudio/uni-app，文档位于 https://uniapp.dcloud.net.cn/，开发时还可以参考 awesome-wechat-weapp 等资源清单。
目标
- 使用官方模板创建 uni-app 项目
- 掌握 pages.json 路由、页面与组件的基础用法
- 了解 uni.request 与条件编译
- 把控工程化与包体策略
初始化与运行
使用 Vite 预设模板（Vue3）进行初始化：
# 使用 degit 拉取官方模板（或使用 HBuilderX 创建项目）
npx degit dcloudio/uni-preset-vue#vite my-uni-app
cd my-uni-app
npm i
运行到微信小程序：
# 开发模式（微信小程序）
npm run dev:mp-weixin
# 生产构建
npm run build:mp-weixin
构建产物位于 dist/dev/mp-weixin 或 dist/build/mp-weixin，用微信开发者工具“打开”该目录即可预览。
路由与页面（pages.json）
pages.json 文件用于声明页面与窗口配置，示例如下：
{
"pages": [
{ "path": "pages/index/index", "style": { "navigationBarTitleText": "首页" } },
{ "path": "pages/about/index", "style": { "navigationBarTitleText": "关于" } }
],
"window": {
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black"
}
}
页面单文件组件（SFC）示例（Vue3）：
<!-- pages/index/index.vue -->
<template>
<view class="page">
<text>计数：{{ count }}</text>
<button @click="count++">+1</button>
<button @click="goAbout">关于</button>
</view>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const count = ref(0)
function goAbout() {
uni.navigateTo({ url: '/pages/about/index' })
}
</script>
<style>
.page { padding: 24rpx; }
</style>
网络请求与封装
基础网络请求调用方式：
uni.request({
url: 'https://api.example.com/items',
method: 'GET',
success: (res) => {
// 建议统一判断后端业务字段
console.log(res.data)
},
fail: () => {
uni.showToast({ title: '网络错误', icon: 'none' })
}
})
为了更好的代码组织和复用，可以进行统一封装，例如：
// src/services/http.ts
export function request<T>(url: string, options: UniApp.RequestOptions = {}) {
const token = uni.getStorageSync('token')
return new Promise<T>((resolve, reject) => {
uni.request({
url: 'https://api.example.com' + url,
timeout: 10000,
header: { 'Content-Type': 'application/json', Authorization: token ? `Bearer ${token}` : '' },
...options,
success: (res) => {
const data: any = res.data
if (data && data.code === 0) resolve(data.data as T)
else reject({ code: data?.code ?? -1, message: data?.message ?? '业务错误', raw: data })
},
fail: (err) => reject({ code: 0, message: '网络异常', raw: err })
})
})
}
条件编译与跨端差异
uni-app 支持条件编译指令，便于处理多端差异：
// #ifdef MP-WEIXIN
console.log('仅在微信小程序端执行')
// #endif
// #ifdef H5
console.log('仅在 H5 端执行')
// #endif
常见跨端差异包括能力差异（如文件系统、Canvas）和组件差异。建议优先使用官方或生态中跨端兼容的组件，必要时使用条件编译或封装适配层。
工程化与包体
- easycom 自动组件：遵循命名和目录约定可以免注册组件；第三方组件建议放入
uni_modules以便管理。 - 分包：利用
pages.json的subPackages拆分业务，降低主包体积。 - 资源治理：进行图片压缩、接口域名配置、CDN 缓存等优化。
- 错误治理与埋点：统一封装 toast、dialog 和日志，上报关键错误。
分包配置示例片段：
{
"subPackages": [
{
"root": "pages-sub/user",
"pages": [{ "path": "profile/index", "style": { "navigationBarTitleText": "我的" } }]
}
]
}
常见问题
- 微信开发者工具 npm 构建：如果引入第三方 npm 包，需在工具中开启“使用 npm 模块”并执行“构建 npm”。
- 组件不生效：检查 easycom 命名与路径；或在页面
components中显式注册（旧方案）。 - pages.json 修改不生效：需重启编译或开发工具；确保路径正确且文件已保存。
- 条件编译未按预期：确认注释语法与构建目标平台一致。
适用场景
- 以 Vue 技术栈为主的前端团队
- 快速构建业务型小程序与 H5
- 多端覆盖但更偏向小程序与移动端
参考
- 官方文档：https://uniapp.dcloud.net.cn/
- 条件编译教程：https://uniapp.dcloud.net.cn/tutorial/platform.html
- 分包配置：https://uniapp.dcloud.net.cn/collocation/pages.html#subpackages
总结
uni-app 在“上手速度”、“生态整合”与“跨端覆盖”方面表现优秀。合理使用条件编译、分包与统一数据层，可以在多端间保持一致的开发体验与交付质量。