UniApp + Vue3 + TypeScript 开发实战:避坑指南与最佳实践

书接上篇，今天我们来聊一个很多Vue3开发者转向UniApp时都会感到困惑的话题：如何正确地使用Vue3 Composition API和TypeScript开发UniApp应用。附带实现思路和所有源码示例，以及常见避坑指南和开发实践。

此系列文章将带领你从移动端跨平台开发入门到精通，如果你也喜欢关注APP、小程序、公众号、H5等等应用的开发，可以持续关注后续更新，避免错过宝贵的知识分享。

你可能觉得：“Vue3我都会，UniApp不就是多平台吗？能有什么不同？”等你真正上手，就会发现：

生命周期多了onLoad、onShow、onReady，它们和onMounted啥关系？
页面传参怎么和Vue Router不一样？
localStorage和uni.setStorageSync有啥区别？
Pinia还能用吗？怎么用？

别急，今天我就用一张表、一堆代码，把这些差异和坑点全部理清楚，让你写起UniApp来像写普通Vue3一样顺手。

一、开发环境搭建与基础配置

1.1 创建支持TypeScript的UniApp项目

npx degit dcloudio/uni-preset-vue#vite-ts my-ts-app
cd my-ts-app
npm install

或者在HBuilderX中新建项目时，选择“uni-app (Vue3)”，并勾选“启用TypeScript”。

1.2 tsconfig.json关键配置

{
"compilerOptions": {
"types": ["@dcloudio/types", "miniprogram-api-typings"],
"strict": true,
"moduleResolution": "node",
"resolveJsonModule": true
  },
"include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"]
}

1.3 类型声明增强（shims-uni.d.ts）

declaremodule'*.vue' {
importtype { DefineComponent } from'vue'
constcomponent: DefineComponent<{}, {}, any>
exportdefaultcomponent
}

二、生命周期：Vue3 vs UniApp，一张表看懂

场景	Vue3 组件生命周期	UniApp 页面生命周期	说明
组件/页面创建	`setup()`	`setup()`	同时执行，此时没有DOM
DOM挂载	`onMounted`	`onReady`	UniApp页面DOM完全渲染后触发
页面显示	无	`onShow`	每次进入页面都触发（包括返回）
页面隐藏	无	`onHide`	页面切到后台或跳转其他页
页面卸载	`onUnmounted`	`onUnload`	页面被销毁
页面初次加载	无	`onLoad`	接收路由参数，只执行一次

重点：

onLoad：接收页面参数，类似Vue Router的beforeRouteEnter。
onShow：类似Vue Router的onBeforeRouteUpdate，但更强大。
onReady：等同于Vue3的onMounted，但onMounted在UniApp中也会执行（组件级），推荐页面逻辑放onReady或onMounted均可，但获取元素位置用onReady更稳妥。

代码示例：组合使用

<scriptsetuplang="ts">
import { onMounted, ref } from'vue'
import { onLoad, onShow, onReady, onHide, onUnload } from'@dcloudio/uni-app'

constmessage=ref('')
constid=ref('')

onLoad((options: any) => {
// 接收URL参数，只执行一次
id.value=options.id
console.log('页面加载，参数id:', id.value)
})

onShow(() => {
console.log('页面显示，每次进入都触发')
})

onReady(() => {
console.log('页面DOM渲染完成')
// 可以在这里获取元素位置
constquery=uni.createSelectorQuery().in(getCurrentInstance()!.proxy)
query.select('.box').boundingClientRect(rect=> {
console.log(rect)
  }).exec()
})

onHide(() => {
console.log('页面隐藏')
})

onUnload(() => {
console.log('页面卸载，清理资源')
})

onMounted(() => {
console.log('组件挂载（Vue3生命周期）')
})
</script>

坑点：

不要在onLoad中尝试获取DOM，此时尚未渲染。
页面卸载时务必清理定时器、事件监听，否则内存泄漏。

三、页面传参与路由

3.1 URL传参（最常用）

发送页：

// 注意特殊字符要编码
constname=encodeURIComponent('张三&李四')
uni.navigateTo({
url: `/pages/detail/detail?id=123&name=${name}`
})

接收页：

import { onLoad } from'@dcloudio/uni-app'

onLoad((options: { id: string; name: string }) => {
console.log(options.id)   // '123'
console.log(options.name) // '张三&李四'（已自动解码）
// 数字需要转换
constidNum=parseInt(options.id)
})

注意事项：

参数值会被自动decodeURIComponent，无需手动解码。
参数都是字符串，对象需要JSON.stringify再编码。
URL长度限制：小程序约2KB，H5和App更大。

3.2 事件总线传参（跨页面）

// 发送页
uni.$emit('updateCart', { count: 5 })
uni.navigateBack()

// 接收页（在onLoad中监听）
import { onLoad, onUnload } from'@dcloudio/uni-app'

consthandleUpdate= (data: { count: number }) => {
console.log('购物车更新', data)
}

onLoad(() => {
uni.$on('updateCart', handleUpdate)
})
onUnload(() => {
uni.$off('updateCart', handleUpdate) // 必须移除
})

3.3 与Vue Router的差异

无$router：所有跳转使用uni.navigateTo等API。
无$route：参数通过onLoad的options获取。
无嵌套路由：页面扁平化，通过pages.json配置。

四、API Client：uni.request vs axios

在UniApp中，网络请求不能使用axios（因为依赖XMLHttpRequest），必须用uni.request或封装。

4.1 基础使用

// 原生用法
uni.request({
url: 'https://api.example.com/user',
method: 'GET',
data: { id: 1 },
success: (res) => {
console.log(res.data)
  },
fail: (err) => {
console.error(err)
  }
})

4.2 封装为Promise + TypeScript

// utils/request.ts
interfaceRequestOptions {
url: string
method?: 'GET'|'POST'|'PUT'|'DELETE'
data?: any
header?: any
showLoading?: boolean
}

functionrequest<T=any>(options: RequestOptions): Promise<T> {
returnnewPromise((resolve, reject) => {
if (options.showLoading) {
uni.showLoading({ title: '加载中...' })
    }
uni.request({
url: options.url,
method: options.method||'GET',
data: options.data,
header: options.header,
success: (res) => {
if (res.statusCode===200) {
resolve(res.dataasT)
        } else {
reject(res)
        }
      },
fail: reject,
complete: () => {
if (options.showLoading) {
uni.hideLoading()
        }
      }
    })
  })
}

exportdefaultrequest

4.3 类型安全的API调用

// api/user.ts
importrequestfrom'@/utils/request'

interfaceUser {
id: number
name: string
email: string
}

exportconstgetUserInfo= (id: number) => {
returnrequest<User>({
url: `/user/${id}`,
method: 'GET'
  })
}

// 页面中使用
constuser=awaitgetUserInfo(123)
console.log(user.name) // TS自动推断类型

五、本地存储：uni.setStorageSync vs localStorage

功能	Web (localStorage)	UniApp	差异说明
同步写入	`localStorage.setItem`	`uni.setStorageSync`	前者只接受字符串，后者自动转换
同步读取	`localStorage.getItem`	`uni.getStorageSync`	后者返回已解析的对象
异步写入	无	`uni.setStorage`	回调方式
容量限制	5-10MB	小程序10MB，App无限制	小程序注意不要超

使用示例：

// 存储对象（自动序列化）
uni.setStorageSync('user', { name: '张三', age: 18 })

// 读取对象（自动反序列化）
constuser=uni.getStorageSync('user') as { name: string; age: number } |null

// 移除
uni.removeStorageSync('user')

// 清空
uni.clearStorageSync()

注意：

小程序中单个key不能超过1MB，总容量10MB。
不要频繁同步存储大量数据，可能阻塞UI。

六、状态管理：Pinia依然是最佳选择

Pinia完美支持UniApp，且比Vuex更轻量。

6.1 安装与配置

npm install pinia

// main.ts
import { createSSRApp } from'vue'
importAppfrom'./App.vue'
import { createPinia } from'pinia'

exportfunctioncreateApp() {
constapp=createSSRApp(App)
constpinia=createPinia()
app.use(pinia)
return { app }
}

6.2 定义store（stores/user.ts）

import { defineStore } from'pinia'

exportconstuseUserStore=defineStore('user', {
state: () => ({
token: ''asstring,
userInfo: nullas { name: string; avatar: string } |null
  }),
getters: {
isLogin: (state) =>!!state.token
  },
actions: {
login(token: string, userInfo: any) {
this.token=token
this.userInfo=userInfo
// 持久化到storage
uni.setStorageSync('userStore', { token, userInfo })
    },
logout() {
this.token=''
this.userInfo=null
uni.removeStorageSync('userStore')
    },
// 初始化从storage读取
init() {
constdata=uni.getStorageSync('userStore')
if (data) {
this.token=data.token
this.userInfo=data.userInfo
      }
    }
  }
})

6.3 在页面中使用

<template>
<view>
<textv-if="userStore.isLogin">欢迎 {{ userStore.userInfo?.name }}</text>
<buttonv-else@click="handleLogin">登录</button>
</view>
</template>

<scriptsetuplang="ts">
import { useUserStore } from'@/stores/user'

constuserStore=useUserStore()

consthandleLogin= () => {
userStore.login('fake-token', { name: '张三', avatar: '' })
}
</script>

6.4 与Vue3的区别

Pinia用法完全相同，只是持久化需要自己配合uni.setStorageSync。
注意：Pinia默认存储在内存中，刷新页面会丢失，必须持久化。

七、常见错误与解决方案

❌ 错误1：在`onLoad`中获取DOM位置为0

原因：DOM未渲染完成。解决：移到onReady或nextTick中。

❌ 错误2：TypeScript报错“找不到模块'@dcloudio/uni-app'”

原因：类型定义未安装。解决：npm install -D @dcloudio/types，并在tsconfig.json中配置types。

❌ 错误3：Pinia数据在页面跳转后不更新

原因：页面没有重新读取store（但store是响应式的，按理应该自动更新）。可能是你在onLoad中一次性读取了store的值到本地data，导致后续store变化未同步。解决：直接使用store的响应式数据，不要复制到本地data。

❌ 错误4：`uni.setStorageSync`存储对象后，读取时类型丢失

原因：返回的是any类型。解决：使用类型断言或定义类型守卫。

interfaceUser { name: string }
constuser=uni.getStorageSync('user') asUser|null

❌ 错误5：事件总线监听多次触发

原因：未在onUnload中取消监听，导致页面多次进入时重复绑定。解决：成对使用uni.$on和uni.$off，并确保移除的是同一个函数引用。

❌ 错误6：URL传参时，对象参数丢失

原因：未使用JSON.stringify。解决：

constobj= { id: 1, name: '张三' }
conststr=encodeURIComponent(JSON.stringify(obj))
uni.navigateTo({ url: `/pages/detail/detail?data=${str}` })
// 接收时
onLoad((options) => {
constobj=JSON.parse(decodeURIComponent(options.data))
})

八、完整示例：一个带用户登录和商品列表的小程序

项目结构

src/
├── api/
│   └── goods.ts          # 商品API
├── components/
│   └── GoodCard.vue      # 商品卡片组件
├── pages/
│   ├── index/
│   │   └── index.vue     # 首页（商品列表）
│   ├── login/
│   │   └── login.vue     # 登录页
│   └── detail/
│       └── detail.vue    # 商品详情
├── stores/
│   └── user.ts           # 用户store
├── utils/
│   └── request.ts        # 请求封装
├── App.vue
├── main.ts
├── pages.json
└── manifest.json

8.1 请求封装（utils/request.ts）

interfaceRequestConfig {
url: string
method?: 'GET'|'POST'|'PUT'|'DELETE'
data?: any
header?: any
showLoading?: boolean
}

exportfunctionrequest<T=any>(config: RequestConfig): Promise<T> {
returnnewPromise((resolve, reject) => {
if (config.showLoading) uni.showLoading({ title: '加载中...', mask: true })
uni.request({
url: `https://your-api.com${config.url}`,
method: config.method||'GET',
data: config.data,
header: {
'Content-Type': 'application/json',
...config.header
      },
success: (res) => {
if (res.statusCode===200) {
resolve(res.dataasT)
        } else {
reject(res)
        }
      },
fail: reject,
complete: () => {
if (config.showLoading) uni.hideLoading()
      }
    })
  })
}

8.2 商品API（api/goods.ts）

import { request } from'@/utils/request'

exportinterfaceGoods {
id: number
name: string
price: number
image: string
}

exportconstgetGoodsList= (page: number, pageSize: number=10) => {
returnrequest<{ list: Goods[]; total: number }>({
url: '/goods/list',
method: 'GET',
data: { page, pageSize },
showLoading: true
  })
}

8.3 首页（pages/index/index.vue）

<template>
<viewclass="container">
<viewclass="goods-list">
<GoodCard
v-for="item in goodsList"
:key="item.id"
:goods="item"
@click="toDetail(item.id)"
/>
</view>
<button@click="loadMore":disabled="loading">加载更多</button>
</view>
</template>

<scriptsetuplang="ts">
import { ref, onMounted } from'vue'
import { getGoodsList, typeGoods } from'@/api/goods'
importGoodCardfrom'@/components/GoodCard.vue'

constgoodsList=ref<Goods[]>([])
constpage=ref(1)
constloading=ref(false)
consthasMore=ref(true)

constloadGoods=async () => {
if (loading.value||!hasMore.value) return
loading.value=true
try {
constres=awaitgetGoodsList(page.value)
if (res.list.length) {
goodsList.value.push(...res.list)
page.value++
    } else {
hasMore.value=false
    }
  } catch (err) {
console.error(err)
  } finally {
loading.value=false
  }
}

constloadMore= () =>loadGoods()

consttoDetail= (id: number) => {
uni.navigateTo({ url: `/pages/detail/detail?id=${id}` })
}

onMounted(() => {
loadGoods()
})
</script>

8.4 商品卡片组件（components/GoodCard.vue）

<template>
<viewclass="card"@click="handleClick">
<image:src="goods.image"mode="aspectFill"class="img"/>
<viewclass="info">
<textclass="name">{{ goods.name }}</text>
<textclass="price">¥{{ goods.price }}</text>
</view>
</view>
</template>

<scriptsetuplang="ts">
importtype { Goods } from'@/api/goods'

constprops=defineProps<{
goods: Goods
}>()

constemit=defineEmits<{
  (e: 'click'): void
}>()

consthandleClick= () => {
emit('click')
}
</script>

8.5 用户Store（stores/user.ts）

import { defineStore } from'pinia'

exportconstuseUserStore=defineStore('user', {
state: () => ({
token: ''asstring,
nickname: ''asstring
  }),
getters: {
isLogin: (state) =>!!state.token
  },
actions: {
login(token: string, nickname: string) {
this.token=token
this.nickname=nickname
uni.setStorageSync('user', { token, nickname })
    },
logout() {
this.token=''
this.nickname=''
uni.removeStorageSync('user')
    },
init() {
constdata=uni.getStorageSync('user') as { token: string; nickname: string } |null
if (data) {
this.token=data.token
this.nickname=data.nickname
      }
    }
  }
})

8.6 App.vue初始化

<scriptsetuplang="ts">
import { onLaunch } from'@dcloudio/uni-app'
import { useUserStore } from'@/stores/user'

onLaunch(() => {
constuserStore=useUserStore()
userStore.init()
})
</script>

8.7 pages.json配置

{
"pages": [
    {"path": "pages/index/index", "style": {"navigationBarTitleText": "商城"}},
    {"path": "pages/login/login", "style": {"navigationBarTitleText": "登录"}},
    {"path": "pages/detail/detail", "style": {"navigationBarTitleText": "商品详情"}}
  ],
"globalStyle": {
"navigationBarTextStyle": "black",
"navigationBarTitleText": "我的应用",
"navigationBarBackgroundColor": "#FFFFFF"
  }
}

九、总结

今天我们系统地学习了在UniApp中使用Vue3 Composition API和TypeScript的注意事项，包括：

生命周期：区分Vue3组件和UniApp页面的不同钩子。
页面传参：URL传参、事件总线、与Vue Router的差异。
API Client：封装uni.request并提供类型安全。
本地存储：uni.setStorageSync的用法和限制。
状态管理：Pinia的集成与持久化。
常见错误：典型场景的解决方案。

最后送你一句话：跨平台开发不是复制粘贴，而是理解差异，写出优雅兼容的代码。希望你能用好TypeScript这把利剑，让UniApp项目更加健壮。

如果在实际开发中遇到问题，欢迎带着你的代码来找我。

加油，未来的全栈大佬！💪如果你也对移动端跨端开发感兴趣，关注我，后续还有更多优质文章分享！

往期相关文章推荐

Uniapp实现省市区地址选择器组件开发实战教程
你开发的Uniapp应用页面跳转还只会傻傻的用uni.navigateTo？快来充充电吧!
Uniapp实现下拉刷新上拉加载更多功能开发实战教程
Uniapp实现微信小程序和公众号用户静默登录功能开发实战教程
企业级跨平台移动应用开发实战之Uniapp生命周期详解和避坑指南
为什么在AI时代，学习Uni-App的价值反而更突出了？
企业级跨平台移动应用开发实战性能利器之Uniapp整合UnoCss
企业级跨平台移动端应用开发实战之UniApp项目框架搭建
手把手带你深度解剖Uniapp子组件封装及其应用开发实战教程
Uniapp如何实现用户千人千面权限控制开发实战？
Uniapp路由相关功能及其应用深度解剖教程
虚拟滚动技术：让万条数据也能丝滑滚动（UniApp跨平台实战）
手把手教你打造跨平台图片查看器组件（UniApp实战）
手把手打造跨平台自由画板组件（UniApp实战）
UniApp数据共享与传递：打通页面与组件的任督二脉
UniApp元素获取与操作的那些高端骚操作实战
UniApp必备技能之通用可拓展自定义加载动画组件实战