UniApp从入门到实践完整教程（2025版）

为什么选择UniApp开发跨平台应用

2025年，移动开发领域正面临前所未有的多端挑战——iOS、Android、鸿蒙Next、微信/支付宝小程序、H5等平台需求并存，企业开发成本持续高企。而UniApp作为DCloud推出的跨平台框架，已实现"一套代码覆盖15+平台"，全球900万开发者选择，手机端月活用户超14亿（数据来源：UniApp官方案例库）。

与传统开发模式相比，UniApp的核心优势在于：

  • 开发效率提升300%：一次编码适配全平台，华为荣耀亲选商城等企业案例证实，多端开发周期缩短至原来的1/3（来源：CSDN博客）
  • 原生级性能体验：通过nvue原生渲染引擎，App端性能较传统WebView提升50%，在地图交互等场景流畅度媲美原生应用
  • 2025年新特性爆发：全面支持鸿蒙Next元服务开发、Vue3+TypeScript、Pinia状态管理，成为跨端开发的首选框架

本教程将从环境搭建到实战项目，带你掌握UniApp开发全流程，特别聚焦2025年最新技术栈与鸿蒙生态适配。

开发环境搭建（HBuilderX 4.57+版）

安装HBuilderX编辑器

作为UniApp官方推荐IDE，HBuilderX 4.57版本带来了鸿蒙元服务开发支持、Vite5编译优化等重要更新。下载地址：HBuilderX官方下载，建议选择"App开发版"以获得完整功能。

安装完成后首次启动，会提示安装UniApp插件（若下载标准版），按提示完成即可。HBuilderX的核心优势在于：

  • 极速启动：绿色发行包，解压即可使用，启动速度比VSCode快3倍
  • 智能编码：支持Vue3+TS语法高亮、组件自动补全，输入u-即可唤起uView组件列表
  • 多端调试：内置真机运行、小程序模拟器联动，调试效率提升40%

配置开发环境

  1. Node.js环境（可选，用于CLI创建项目）
    安装v18+版本，配置npm镜像源：

    npm config set registry https://registry.npmmirror.com

  2. 平台工具链

    • 微信小程序开发者工具：用于小程序调试，需在HBuilderX"运行设置"中配置安装路径
    • 鸿蒙DevEco Studio 5.0.5+：开发鸿蒙元服务必备，下载地址
    • Android Studio/Xcode：如需离线打包原生App，需安装对应平台工具

创建第一个UniApp项目

通过可视化界面创建（推荐初学者）：

  1. 点击菜单栏 文件 → 新建 → 项目，选择"UniApp"类型
  2. 输入项目名称（如my-uniapp），选择模板：
    • uni ui项目模板：内置常用组件，日常开发首选
    • Hello uni-app：官方组件和API示例，适合学习
  3. 点击"创建"，HBuilderX会自动生成项目结构并安装依赖

项目目录结构解析：

my-uniapp/
├── pages/          # 页面目录（约定式路由）
├── static/         # 静态资源（图片/字体等）
├── uni_modules/    # 组件库目录（自动引入）
├── App.vue         # 应用入口组件
├── main.ts         # 入口文件（Vue3+TS配置）
├── manifest.json   # 应用配置（平台信息/权限等）
└── pages.json      # 页面路由配置

基础语法与核心概念

Vue3+TypeScript开发范式

2025年的UniApp已全面支持Vue3组合式API，推荐使用TypeScript提升代码健壮性。以下是一个基础页面示例（pages/index/index.vue）：

<template>
  <view class="container">
    <text class="title">{{ message }}</text>
    <u-button @click="handleClick" type="primary">点击我</u-button>
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue'

// 定义响应式数据
const message = ref<string>('Hello UniApp 2025')

// 定义事件处理函数
const handleClick = (): void => {
  uni.showToast({
    title: '按钮被点击',
    icon: 'success'
  })
}
</script>

<style scoped>
.container {
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 40rpx;
}
.title {
  font-size: 32rpx;
  margin-bottom: 20rpx;
}
</style>

关键特性：

  • setup语法糖：无需export default，直接定义变量和函数
  • 类型注解：通过: string指定变量类型，IDE自动提示错误
  • 组件自动导入：uView组件无需import，直接在模板中使用（基于easycom规范）

页面生命周期与路由

UniApp页面生命周期在Vue3基础上扩展了小程序特性：

// pages/detail/detail.vue
export default {
  onLoad(option: { id: string }) {
    console.log('页面加载，接收参数：', option.id) // 路由传参获取
  },
  onShow() {
    console.log('页面显示')
  },
  onReady() {
    console.log('页面初次渲染完成')
  }
}

路由跳转使用UniApp内置API：

// 保留当前页，跳转到详情页
uni.navigateTo({ url: '/pages/detail/detail?id=1' })

// 关闭当前页，跳转到首页
uni.redirectTo({ url: '/pages/index/index' })

// 跳转到TabBar页面
uni.switchTab({ url: '/pages/home/home' })

网络请求与数据缓存

网络请求（替代axios，全平台兼容）：

const fetchData = async () => {
  try {
    const res = await uni.request<{ data: Article[] }>({
      url: 'https://api.example.com/articles',
      method: 'GET',
      data: { page: 1 }
    })
    if (res.statusCode === 200) {
      articles.value = res.data.data
    }
  } catch (err) {
    uni.showToast({ title: '请求失败', icon: 'none' })
  }
}

数据缓存（跨平台统一API）：

// 存储数据
uni.setStorageSync('userInfo', { name: '张三', token: 'xxx' })

// 获取数据
const user = uni.getStorageSync<UserInfo>('userInfo')

// 异步操作（推荐）
uni.setStorage({
  key: 'config',
  data: { theme: 'dark' },
  success: () => console.log('存储成功')
})

核心技术栈与实战应用

UI组件库选型

2025年UniApp生态中，以下组件库占据主流：

组件库 特点 适用场景
uView Plus 80+组件，全端兼容，Vue3+TS重构 中大型项目，电商/社交App
uni-ui 官方维护，轻量高效，nvue原生支持 性能敏感场景，政务应用
ColorUI 高颜值动画，CSS样式库 展示类小程序，个人项目

以uView Plus为例，安装与使用步骤：

  1. 安装依赖： 
    npm install uview-plus
  2. 全局引入（main.ts）： 
    import uView from 'uview-plus'
createApp(App).use(uView)
  3. 使用组件： 
    <u-button type="primary" size="large" @click="submit">提交订单</u-button>
<u-input v-model="username" placeholder="请输入用户名" />

Pinia状态管理

Pinia作为Vue3官方推荐状态库，比Vuex更简洁，在UniApp中使用步骤：

  1. 安装配置：

    npm install pinia @pinia/uni

    // store/index.ts
import { createPinia } from 'pinia'
export const pinia = createPinia()

// main.ts
import { pinia } from './store'
createApp(App).use(pinia)

  2. 定义Store：

    // store/user.ts
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => ({
    token: '',
    userInfo: null as UserInfo | null
  }),
  actions: {
    login(credentials: { username: string, password: string }) {
      return uni.request({
        url: '/api/login',
        method: 'POST',
        data: credentials
      }).then(res => {
        this.token = res.data.token
        this.userInfo = res.data.user
        uni.setStorageSync('token', this.token)
      })
    },
    logout() {
      this.$reset() // 重置状态
      uni.removeStorageSync('token')
    }
  },
  getters: {
    isLogin: (state) => !!state.token
  }
})

  3. 组件中使用：

    <template>
  <view v-if="userStore.isLogin">
    {{ userStore.userInfo?.name }}
  </view>
</template>

<script setup lang="ts">
import { useUserStore } from '@/store/user'
const userStore = useUserStore()
</script>

鸿蒙Next元服务开发（2025新特性）

UniApp 4.34+版本支持鸿蒙元服务开发，实现"一次开发，多端部署"到鸿蒙App和元服务。

环境配置

  1. 注册元服务AppID
    在华为AGC后台创建应用，获取包名（格式：com.atomicservice.xxx）

  2. 配置签名证书
    创建harmony-mp-configs/build-profile.json5：

    {
  app: {
    signInfo: {
      // 自动签名配置（开发环境）
      autoGenerate: true
    }
  }
}

  3. 权限配置（module.json5）
    声明网络、存储等权限：

    {
  module: {
    reqPermissions: [
      { name: "ohos.permission.INTERNET" },
      { name: "ohos.permission.GET_NETWORK_INFO" }
    ]
  }
}
实现原子化服务卡片
// 鸿蒙元服务卡片更新
import featureAbility from '@ohos.ability.featureAbility'

// 创建资讯快捷卡片
const updateCard = (news: NewsItem) => {
  const cardInfo = {
    cardName: "newsCard",
    data: JSON.stringify({ 
      title: news.title, 
      time: formatTime(news.pubTime) 
    })
  }
  featureAbility.addCard(cardInfo)
}
鸿蒙性能优化专项

  1. 长列表优化（使用鸿蒙原生list组件）：

    <template>
  <list>
    <list-item v-for="item in list" :key="item.id">
      <news-item :data="item"></news-item>
    </list-item>
  </list>
</template>

  2. 任务分发（避免UI线程阻塞）：

    import taskpool from '@ohos.taskpool'

// 将耗时操作放入任务池
const heavyTask = async () => {
  const result = await taskpool.execute((param) => {
    // 复杂计算逻辑
    return processData(param)
  }, largeData)
}

实战项目：鸿蒙资讯类App开发

项目初始化与架构设计

技术栈：

  • 框架：UniApp 3.8 + Vue3 + TypeScript
  • UI：uni-ui + 鸿蒙原生组件
  • 状态管理：Pinia
  • 数据存储：unStorage + 鸿蒙DB

项目结构：

src/
├── api/          # 接口封装
├── components/   # 业务组件
├── hooks/        # 自定义钩子（如useNews、useUser）
├── pages/        # 页面（首页/详情/我的）
├── store/        # Pinia状态管理
├── harmony-mp-configs/  # 鸿蒙配置文件
└── utils/        # 工具函数

核心功能实现

1. 智能化资讯流

基于用户行为推荐算法，实现瀑布流布局：

<template>
  <waterfall :col="2" :data="newsList">
    <template #item="{ item }">
      <news-card 
        :title="item.title" 
        :image="item.cover"
        :on-preview="() => previewNews(item.id)"
      ></news-card>
    </template>
  </waterfall>
</template>

<script setup lang="ts">
import { useNewsStore } from '@/store/news'
const newsStore = useNewsStore()
const newsList = newsStore.recommendNews

// 监听滑动到底部加载更多
const loadMore = () => {
  newsStore.loadMore()
}
</script>
2. 鸿蒙服务卡片

实现资讯快捷卡片，支持点击直达详情页：

// 在App.vue中初始化卡片
onLaunch() {
  // #ifdef HARMONYOS
  this.initHarmonyCard()
  // #endif
},
methods: {
  initHarmonyCard() {
    // 监听卡片点击事件
    featureAbility.on('cardClick', (data) => {
      const { newsId } = JSON.parse(data)
      uni.navigateTo({ url: `/pages/detail/detail?id=${newsId}` })
    })
    // 更新卡片数据
    this.updateNewsCard()
  }
}
3. 跨平台差异处理

使用条件编译适配不同平台：

<template>
  <view>
    <!-- 鸿蒙平台显示原生分享按钮 -->
    <!-- #ifdef HARMONYOS -->
    <ohos-share-button :data="news"></ohos-share-button>
    <!-- #endif -->
    
    <!-- 其他平台显示普通按钮 -->
    <!-- #ifndef HARMONYOS -->
    <u-button @click="share">分享</u-button>
    <!-- #endif -->
  </view>
</template>

性能优化与打包发布

性能优化策略

  1. 代码优化

    • 路由懒加载：在pages.json中配置"lazyCodeLoading": "requiredComponents"
    • 组件按需引入：通过unplugin-auto-import自动导入API
    • 避免setData滥用：使用Pinia状态管理替代页面间数据传递

  2. 渲染优化

    • 图片懒加载：<image lazy-load src="xxx"></image>
    • 虚拟滚动：长列表使用uni-virtual-list组件
    • nvue原生渲染：性能敏感页面改用.nvue后缀，如首页、商品列表

  3. 鸿蒙平台专项优化

    • 资源预加载：通过@ohos.resourceManager预加载图片资源
    • 后台任务管理：使用BackgroundTaskManager处理耗时操作
    • 内存泄漏监控：集成@ohos.hiviewdfx.memoryAnalyzer

多平台打包发布

1. 鸿蒙元服务发布
  1. 在HBuilderX菜单栏选择"发行 → 鸿蒙元服务"
  2. 填写应用名称、版本号，选择签名方式（开发环境用自动签名）
  3. 生成HAP包，上传至华为应用市场
2. 微信小程序发布
  1. 在manifest.json中配置小程序AppID
  2. 点击"发行 → 小程序-微信"，生成代码包
  3. 在微信开发者工具中导入unpackage目录，测试后提交审核
3. 原生App打包

云端打包（推荐）：

  1. 在DCloud开发者中心申请App证书
  2. HBuilderX"发行 → 原生App-云端打包"
  3. 选择证书，配置权限，等待打包完成（约3分钟）

离线打包（企业级需求）：

  1. 生成离线打包资源（“发行 → 本地打包”）
  2. 使用Android Studio导入工程，配置签名
  3. 编译生成APK/IPA文件

总结与未来展望

通过本教程，你已掌握UniApp从入门到实战的全流程，包括：

  • HBuilderX 4.57开发环境搭建与配置
  • Vue3+TypeScript语法与UniApp核心API
  • uView组件库与Pinia状态管理的实战应用
  • 鸿蒙Next元服务开发与性能优化
  • 多平台打包发布流程

2025年，UniApp在鸿蒙生态的深度整合将成为最大趋势。随着华为鸿蒙设备保有量突破8亿，掌握UniApp+鸿蒙开发的开发者将迎来新的职业机遇。建议持续关注：

  • UTS语言：UniApp原生插件开发新范式，可直接调用鸿蒙ArkUI API
  • 跨端AI能力：集成华为盘古大模型，实现智能推荐、语音交互等功能
  • 低代码平台：DCloud即将推出的UniLowCode，可进一步降低开发门槛

最后，推荐学习资源：

现在，开启你的UniApp跨端开发之旅，用一套代码征服全平台！

# vue.js # javascript # 前端
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

鸿蒙 ArkTS 组件化开发深度解析：幻梦工坊梦境编织系统的架构与实现

avatar HarmonyOS开发者社区
cover

【寻迹校园 HarmonyOS NEXT 实战 48】不新增测试依赖：用 Node Loader 直接测试生产 ArkTS 纯规则与状态机

avatar HarmonyOS开发者社区
cover

【寻迹校园 HarmonyOS NEXT 实战 47】小艺 Agent 审核驳回复盘：工作流“有输出”为什么智能体“无回复”

avatar HarmonyOS开发者社区