uni-app 全知识点整理

uni-app 是一个基于 Vue.js 的跨平台应用开发框架，开发者编写一套代码，可发布到 iOS、Android、鸿蒙 Next、Web（响应式）以及微信/支付宝/百度/抖音等各种小程序、快应用等多个平台。以下是完整的知识体系整理

一、框架概述与核心概念

1.1 什么是 uni-app

uni-app 由 DCloud 公司推出，使用 Vue.js 语法，可编译到 iOS、Android、H5、小程序等多端，实现"一套代码，多端运行"。其核心优势在于降低开发成本、提升效率。

1.2 组成与跨端原理

uni-app 由编译器和运行时（runtime） 两部分配合实现跨端：

• 编译器：运行在电脑开发环境（HBuilderX 或 CLI），将开发者的 Vue 代码编译生成每个平台支持的特有代码

  • Web 平台：编译为 JS 代码

  • 微信小程序：拆分生成 wxml、wxss、js 等代码

  • App 平台：编译为 JS 代码；uts 代码编译为 Kotlin（Android）或 Swift（iOS）

  • 支持 Vue2（基于 webpack）和 Vue3（基于 Vite）两个版本

• 运行时：运行在真正的终端上，每个平台（Web、Android App、iOS App、各家小程序）都有各自的 runtime 进行解析

uni-app runtime 包括三部分：基础框架、组件、API。

1.3 基本语言与开发规范

• 基本语言：JS、Vue、CSS，以及 TS、SCSS 等预编译器

• App 端扩展：支持原生渲染的 nvue，以及可编译为 Kotlin 和 Swift 的 uts

• 开发规范：

  • 页面文件遵循 Vue 单文件组件（SFC）规范

  • 组件标签靠近小程序规范

  • API 接口靠近小程序规范，前缀统一为 uni

  • 数据绑定及事件处理同 Vue.js 规范

  • App-nvue 平台建议使用 flex 布局

二、开发环境与工程化

2.1 环境搭建

• HBuilderX：DCloud 官方 IDE，支持可视化操作与代码编辑

• Node.js 与 npm：建议 Node.js 14+

• 创建项目：通过 HBuilderX 新建 uni-app 项目，选择模板（默认模板或 uni-ui 模板）

• 运行调试：支持真机调试、模拟器运行及浏览器预览（H5 端）

2.2 项目目录结构

├── pages/              # 页面文件目录
├── static/             # 静态资源目录
├── components/         # 自定义组件目录
├── uni_modules/        # uni-app 插件模块目录
├── App.vue             # 应用入口组件
├── main.js             # 入口文件
├── manifest.json       # 应用配置文件
├── pages.json          # 页面路由配置文件
└── uni.scss            # 全局样式变量

2.3 核心配置文件

manifest.json：

• 应用配置文件，用于指定应用的名称、图标、权限等

• 配置应用基本信息（id、name、版本号等）

• 配置 Vue 版本（Vue2/Vue3）

• 配置 App 模块（如需要的原生功能模块）

• 配置各端特有的打包参数

pages.json：

• 页面路由配置文件，配置每个路由页面的路径及页面样式

• 类似小程序在 app.json 中配置页面路由

• Pages 列表第一项为项目的启动页面

• 可配置 tabBar

三、页面与路由

3.1 页面结构

uni-app 页面由 .vue 文件组成，包含三部分：

<template>
  <!-- 页面结构，必须有一个且只能有一个根 view -->
</template>

<script>
export default {
  // 页面逻辑
}
</script>

<style>
/* 页面样式 */
</style>

3.2 路由配置

• 在 pages.json 中配置页面路由

• 支持设置 tabBar

3.3 路由跳转方式

两种方式：

API 跳转：

• uni.navigateTo：保留当前页面，跳转到新页面

• uni.redirectTo：关闭当前页面，跳转到新页面

• uni.switchTab：跳转到 tabBar 页面

• uni.reLaunch：关闭所有页面，打开新页面

• uni.navigateBack：返回上一页面

组件跳转：使用 navigator 组件

3.4 路由传参

通过 URL 传递参数：

uni.navigateTo({
  url: '/pages/detail/detail?id=123'
})

四、组件系统

4.1 组件概念

组件是视图层的基本组成单元，是单独且可复用的功能模块的封装。一个组件包括开始标签和结束标签，标签上可写属性。

4.2 基础组件

内置在 uni-app 框架中的组件，包括 view、text、input、button、video 等几十个：

• 视图容器：<view>（类似 div）、<scroll-view>（可滚动区域）

• 基础内容：<text>（文本）、<rich-text>（富文本）

• 表单组件：<input>、<button>、<checkbox> 等

• 媒体组件：<image>、<video>、<audio> 等

4.3 扩展组件与自定义组件

• 从插件市场获取扩展组件（如 uni-rate 评分组件）

• 自定义组件放在 components 目录下

• 支持 easycom 方式（符合 components/组件名称/组件名称.vue 结构即可直接使用）

4.4 组件注册

两种命名方式：

• kebab-case（短横线分隔）：<my-component-name>

• PascalCase（首字母大写）：<MyComponentName>

五、API 体系

5.1 API 组成

uni-app 的 js API 由标准 ECMAScript 的 js API 和 uni 扩展 API 两部分组成。

5.2 标准 JS 与浏览器 JS 的区别

非 web 端（小程序和 App）不支持 window、document、navigator 等浏览器专用对象，但支持标准 ECMAScript。Android 平台运行在 v8 引擎，iOS 运行在 jscore 引擎。

5.3 uni API 规范

• uni.on 开头的 API 是监听事件，接受 CALLBACK 函数

• 其他 API 接受 OBJECT 参数，包含 success、fail、complete 回调

• 异步 API 返回 errMsg 字段，同步 API 不返回

• 异步方法不传入 callback 参数时，以 Promise 返回数据

5.4 常用 API 分类

网络请求：

uni.request({
  url: 'https://api.example.com/data',
  method: 'GET',
  success: (res) => { console.log(res.data); }
})

数据存储：

• uni.setStorageSync / uni.getStorageSync（同步）

• uni.setStorage / uni.getStorage（异步）

路由跳转：uni.navigateTo、uni.redirectTo 等

5.5 各端特色 API

各端自己的特色 API 可通过条件编译自由使用。App 端的 JS API 参考 html5plus。

六、样式与适配

6.1 rpx 单位

rpx（responsive pixel）是 uni-app 提供的自适应单位：

• 基准：1rpx = 屏幕宽度的 1/750

• 用法：在样式文件中使用 rpx 单位，如 width: 750rpx;

• 建议：字体和宽高等都使用 rpx，需要固定尺寸时使用 px

6.2 样式预处理器

支持使用 less、sass、scss、stylus 等预处理器

6.3 布局建议

App-nvue 平台建议使用 flex 布局进行开发

七、生命周期

7.1 应用生命周期

生命周期	说明
onLaunch	应用初始化时触发，仅触发一次
onShow	应用启动或从后台进入前台时触发
onHide	应用从前台进入后台时触发
onError	应用发生错误时触发
onPageNotFound	页面找不到时触发

7.2 页面生命周期

生命周期	说明
onInit	页面初始化，触发比 onLoad 更早，仅执行一次
onLoad	页面加载时触发，携带页面参数
onShow	页面显示时触发
onReady	页面初次渲染完成时触发
onHide	页面隐藏时触发
onUnload	页面卸载时触发

7.3 生命周期执行顺序

• 冷启动：onLaunch → onShow → 首页 onLoad → 首页 onShow → 首页 onReady

• 热启动：onShow → 当前页 onShow

• 页面跳转：原页 onHide → 新页 onLoad → 新页 onShow → 新页 onReady

八、状态管理

8.1 Vuex

传统的 Vue 状态管理库，全局单例模式，所有组件共享单一状态树。

8.2 Pinia（推荐）

Vue 官方推荐的状态管理库：

• API 设计接近 Vuex 5

• 天生具备完美的 TypeScript 类型推断

• 更轻量、模块化

• 更简洁的 API 设计（无需 mutations）

uni-app 官方已推荐使用 Pinia。

九、平台差异与条件编译

9.1 条件编译

条件编译是用特殊注释作为标记，编译时根据这些注释将代码编译到不同平台。

使用方法：

// #ifdef APP-PLUS
// 仅出现在 App 平台的代码
// #endif

// #ifndef H5
// 除了 H5 平台，其它平台均存在的代码
// #endif

// #ifdef H5 || MP-WEIXIN
// H5 或微信小程序平台存在的代码
// #endif

%PLATFORM% 可取值：APP-PLUS、H5、MP-WEIXIN、MP-ALIPAY、MP-BAIDU 等

9.2 平台差异处理

uni-app 已将常用的组件、API 封装到框架中，大部分业务可直接满足。但每个平台有自己特性，存在无法跨平台的情况。核心策略包括：

• 条件编译覆盖模板、样式、JS、配置文件等场景

• 各端特色 API 通过条件编译自由使用

十、性能优化

10.1 包体积优化

• 条件编译：不同平台只加载各自需要的资源

• 静态资源 CDN：将图片等放在 CDN 服务器

• 分包：资源按需加载，减少初始包体积

• 依赖优化：将调试用的插件放到 devDependencies

• 代码拆分：路由懒加载或按需加载

10.2 渲染性能

• nvue 原生渲染：比 vue 页面（WebView 渲染）快 30%-60%

• 使用 uni-ui 组件可自动处理 webview 渲染和原生渲染

10.3 首屏优化

• nvue 页面基于原生渲染，组件直接映射为系统原生控件，跳过 HTML/CSS 解析和 DOM 树构建

十一、nvue 原生渲染

11.1 概念

nvue（native vue）是 uni-app 在 App 端提供的原生渲染方案：

• 基于 weex 改进的原生渲染引擎

• 组件直接映射为系统原生控件（Android 的 View、iOS 的 UIView）

• 支持 vue 页面和 nvue 页面混搭、互相跳转

11.2 优势

• 渲染速度比 vue 页面快 30%-60%

• 纯原生渲染可减少 App 包体积和内存占用

• 不存在 webview 渲染和原生字体不一致的问题

11.3 注意事项

• 建议使用 flex 布局

• 建议使用 uni-ui 的组件，自动处理两种渲染模式

十二、UTS 插件

12.1 概念

UTS 插件是利用 uts 语法操作原生 API（手机 OS 的 API 或三方 SDK），封装成 uni_modules 插件供前端调用。不需要熟悉 Kotlin 和 Swift 语法。

12.2 类型

• UTS API 插件：提供原生 API 扩展

• UTS 组件：提供原生 UI 组件开发模式

12.3 跨平台

uts 插件在 uni-app 和 uni-app x 中都支持。编译到鸿蒙端时会被编译成 ArkTS 代码。

十三、uniCloud 云开发

13.1 概念

uniCloud 是 DCloud 联合阿里云、腾讯云、支付宝小程序云提供的基于 serverless 模式和 JS 编程的云开发平台。

13.2 核心模块

• 云函数：无服务器计算单元

• 云数据库：数据存储

• 云存储：文件存储

13.3 优势

• 无需搭建服务器即可实现完整业务逻辑

• 开发效率提升 40% 以上，运维成本降低 70%

• 尤其适合不太熟悉后端的前端工程师

十四、调试工具

14.1 HBuilderX 调试

• 支持在 HBuilder 自带的调试面板中调试 js 代码

• 调试工具栏包含变量窗口、监视窗口、调用堆栈窗口、断点窗口

• 支持对 vue、uvue、nvue、uts、ts、js 文件打断点

14.2 小程序开发者工具调试

运行到微信、支付宝等小程序开发者工具时，可在控制台查看 console 信息、网络请求等

14.3 uni-vue-devtools

基于 vue-devtools 开发的 uni-app 项目调试工具，HBuilderX 已集成

十五、插件市场

15.1 概述

uni-app 插件市场（https://ext.dcloud.net.cn）是官方插件生态集中地。有数千款插件，支持前端组件、JS SDK、页面模板、项目模板、原生插件等多种类型。

15.2 插件类型

• 前端组件

• App 原生插件

• UTS 插件

• uniCloud 插件

15.3 使用方式

• 在插件市场购买或下载插件

• 购买时需选择正确的 appid 和绑定正确包名

• 原生插件可直接云端打包生效

十六、常用 UI 框架与生态

16.1 官方推荐

• uni-ui：官方组件库

• uView：第三方组件库

16.2 可使用的 UI 框架

详见：关于uni-app的ui库、ui框架、ui组件 - DCloud问答

十七、与 Vue 的差异要点

1. 不支持浏览器专用对象：非 web 端不支持 window、document、navigator 等

2. 路由管理不同：由框架统一管理，在 pages.json 中配置，而非 Vue Router

3. 生命周期扩展：在 Vue 生命周期基础上增加了应用级和页面级生命周期

4. 组件标签：靠近小程序规范

5. API 调用：使用 uni 前缀，而非 wx. 或 my. 等

十八、学习路线建议

1. 基础阶段：了解 uni-app 概念、环境搭建、项目结构

2. 核心阶段：掌握页面与路由、组件使用、API 调用、生命周期

3. 进阶阶段：学习状态管理（Pinia）、条件编译、平台适配

4. 深入阶段：nvue 原生渲染、UTS 插件开发、uniCloud 云开发

5. 实战阶段：性能优化、打包部署、插件市场使用

---

以上涵盖了 uni-app 从入门到进阶的完整知识体系。建议结合实际项目开发，边学边练，逐步掌握各知识点。