UniApp 从入门到实战：一套代码多端运行的最佳实践

2025年10月24日 121点热度 0人点赞 0条评论

一、前言

做移动端和小程序开发时常有一个痛点：

Android、iOS、微信小程序、H5 都要分别开发一遍？

UniApp 给出的答案是：不用。
它是基于 Vue.js 的跨平台框架，一套代码就能编译到微信小程序、支付宝小程序、H5、App 等多端。
生态完善、插件丰富、官方更新活跃，适合前端工程师一站式开发。

二、环境准备与项目创建

1. 安装 HBuilderX（推荐）

下载：https://www.dcloud.io/hbuilderx.html

创建项目 → 选择 uni-app 默认模板（Hello uni-app） → 命名为 my-uni-demo。

目录结构如下：

my-uni-demo/
├── pages/
│   ├── index/
│   │   └── index.vue
├── static/
├── uni.scss
├── manifest.json
├── pages.json
└── main.js

2. 启动项目

点击 运行 → 运行到浏览器（H5） 或 运行到小程序模拟器（微信），看到默认页面即成功。

三、核心知识点

页面注册

JSON

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": { "navigationBarTitleText": "首页" }
    }
  ]
}

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": { "navigationBarTitleText": "首页" }
    }
  ]
}

路由跳转

JavaScript

uni.navigateTo({ url: '/pages/about/about' })
uni.navigateBack()

uni.navigateTo({ url: '/pages/about/about' })
uni.navigateBack()

生命周期

JavaScript

export default {
  onLoad() {},
  onShow() {},
  onPullDownRefresh() {}
}

export default {
  onLoad() {},
  onShow() {},
  onPullDownRefresh() {}
}

网络请求封装

JavaScript

export const request = (options) => {
  return new Promise((resolve, reject) => {
    uni.request({
      ...options,
      header: { Authorization: uni.getStorageSync('token') || '' },
      success: (res) => res.statusCode === 200 ? resolve(res.data) : reject(res),
      fail: reject
    })
  })
}

export const request = (options) => {
  return new Promise((resolve, reject) => {
    uni.request({
      ...options,
      header: { Authorization: uni.getStorageSync('token') || '' },
      success: (res) => res.statusCode === 200 ? resolve(res.data) : reject(res),
      fail: reject
    })
  })
}

四、实战：开发一个待办清单（ToDo List）

pages/index/index.vue：

Vue

<template>
  <view class="container">
    <view class="header">我的待办事项</view>
    <view class="add">
      <input v-model="task" placeholder="输入任务..." />
      <button @click="addTask">添加</button>
    </view>
    <view class="list">
      <view v-for="(item, index) in list" :key="index" class="item">
        <text>{{ item }}</text>
        <button @click="removeTask(index)">删除</button>
      </view>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return { task: '', list: [] }
  },
  methods: {
    addTask() {
      if (!this.task) return uni.showToast({ title: '请输入内容', icon: 'none' })
      this.list.push(this.task)
      this.task = ''
      uni.setStorageSync('todos', this.list)
    },
    removeTask(index) {
      this.list.splice(index, 1)
      uni.setStorageSync('todos', this.list)
    }
  },
  onShow() {
    this.list = uni.getStorageSync('todos') || []
  }
}
</script>

<style>
.container { padding: 20rpx; }
.header { font-size: 40rpx; margin-bottom: 20rpx; }
.add { display: flex; }
.list .item { display: flex; justify-content: space-between; margin: 10rpx 0; }
</style>

<template>
  <view class="container">
    <view class="header">我的待办事项</view>
    <view class="add">
      <input v-model="task" placeholder="输入任务..." />
      <button @click="addTask">添加</button>
    </view>
    <view class="list">
      <view v-for="(item, index) in list" :key="index" class="item">
        <text>{{ item }}</text>
        <button @click="removeTask(index)">删除</button>
      </view>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return { task: '', list: [] }
  },
  methods: {
    addTask() {
      if (!this.task) return uni.showToast({ title: '请输入内容', icon: 'none' })
      this.list.push(this.task)
      this.task = ''
      uni.setStorageSync('todos', this.list)
    },
    removeTask(index) {
      this.list.splice(index, 1)
      uni.setStorageSync('todos', this.list)
    }
  },
  onShow() {
    this.list = uni.getStorageSync('todos') || []
  }
}
</script>

<style>
.container { padding: 20rpx; }
.header { font-size: 40rpx; margin-bottom: 20rpx; }
.add { display: flex; }
.list .item { display: flex; justify-content: space-between; margin: 10rpx 0; }
</style>

即可在多端运行。

五、常见坑与解决方案

问题	原因	解决办法
页面刷新状态丢失	Vue 实例重载	用 `uni.setStorageSync` 持久化
小程序不支持部分 DOM 操作	渲染层隔离	用 `uni.createSelectorQuery()`
页面栈超限	小程序限制10层	使用 `uni.switchTab()` 或 `uni.reLaunch()`
图片路径差异	加载机制不同	放 `static/` 用绝对路径