uni-app 生态全景

1.1 什么是 uni-app？

uni-app 是由 DCloud（数字天堂）公司开发的一个使用 Vue.js 开发多端应用的前端框架。它的核心理念是"一次开发，多端发布"——开发者编写一份代码，经过编译工具链处理，可以同时运行在以下平台：

• H5 / Web：浏览器直接运行
• 微信小程序、支付宝小程序、抖音小程序、百度小程序等
• Android App
• iOS App
• 鸿蒙 HarmonyOS Next（uni-app x 支持）

为什么选择 uni-app 而不是 React Native 或 Flutter？

这是初学者最常问的问题。三个框架有各自的定位：

1.2 uni-app x：下一代跨端方案

uni-app x 是 DCloud 于 2023 年推出的全新跨端方案，与传统 uni-app 有根本性的架构差异。理解这种差异是掌握整个生态的关键。

传统 uni-app 的架构局限

传统 uni-app 在 App 端（非 H5、非小程序）采用的是双线程 WebView 渲染架构：

• 逻辑层：JavaScript 引擎（JSCore / V8）运行业务逻辑
• 渲染层：WebView 渲染页面（nvue 模式下使用 Weex/原生渲染）
• 两层之间通过 JSON 序列化通信，有性能瓶颈

这种架构的问题是：复杂动画、长列表、高频交互时，跨线程通信延迟会导致明显的卡顿感，和真正的原生 App 有差距。

uni-app x 的突破：原生渲染 + UTS 语言

uni-app x 彻底抛弃了 WebView，采用原生渲染引擎：

1.3 UTS 语言详解

UTS（Uni Type Script）是 DCloud 为 uni-app x 设计的一门强类型脚本语言。从语法层面看，它与 TypeScript 高度兼容，但有根本性的不同：

UTS 不是运行时脚本，而是编译型语言

TypeScript 最终会编译为 JavaScript 在 JS 引擎中运行。UTS 则不同：

这意味着：你写的同一份 UTS 代码，在 Android 上跑的是真正的 Kotlin 字节码，在 iOS 上跑的是真正的 Swift 代码，没有任何 JavaScript 桥接开销。

UTS 语法示例

// UTS 代码示例 — 语法与 TypeScript 高度相似
// 但会被编译为各平台原生代码

import { Vibrator, VibrateShort } from 'android.os'  // 直接导入 Android 原生类

export function vibrateDevice() : void {
  // 调用 Android 原生震动 API
  const vibrator = UTSAndroid.getSystemService('vibrator') as Vibrator
  vibrator.vibrate(VibrateShort({
    duration: 100
  }))
}

// 定义类型，与 TypeScript 完全一致
interface UserInfo {
  id: number
  name: string
  avatar?: string
}

function greet(user: UserInfo): string {
  return `你好，${user.name}！`
}

1.4 跨端渲染原理

理解 uni-app 如何实现"一套代码，多端运行"，需要了解它的编译器工作机制。

编译器的核心工作

uni-app 的编译器（基于 Vite + 自定义插件）将你的 .vue / .uvue 文件处理为各平台所需的格式：

源文件	目标平台	编译产物
.vue	H5	标准 HTML/CSS/JS（Vue 3 运行时）
.vue	微信小程序	.wxml + .wxss + .js + .json
.uvue	Android	Kotlin 代码 + 原生 XML 布局（或动态布局）
.uvue	iOS	Swift 代码 + 原生 UIKit 布局

条件编译：精确控制平台差异

当某些逻辑只应在特定平台执行时，uni-app 提供了条件编译语法，通过注释形式嵌入到代码中：

// #ifdef MP-WEIXIN
// 以下代码仅编译到微信小程序
wx.login({ success: (res) => console.log(res.code) })
// #endif

// #ifdef APP
// 以下代码仅编译到 App（Android + iOS）
import { NativeModule } from './native.uts'
NativeModule.requestPermission()
// #endif

// #ifndef H5
// 以下代码编译到除 H5 之外的所有平台
uni.showToast({ title: '非 H5 平台' })
// #endif

1.5 环境搭建

uni-app 的官方 IDE 是 HBuilderX，它是开发 uni-app 的最佳工具，内置了编译器、模拟器集成、调试工具等。

HBuilderX 安装

1. 访问 https://www.dcloud.io/hbuilderx.html，下载正式版（Alpha 版功能最新但可能有 Bug）
2. macOS 解压后拖入 Applications，Windows 直接运行安装程序
3. 首次启动需要登录 DCloud 账号（免费注册）

创建第一个项目

# 方式一：HBuilderX 图形界面
# 文件 → 新建 → 项目 → uni-app
# 选择模板：默认模板（Vue3 + Vite）

# 方式二：命令行（仅传统 uni-app，不含 uni-app x）
npx degit dcloudio/uni-preset-vue#vite-ts my-app
cd my-app
npm install

# 运行到 H5（开发模式）
npm run dev:h5

# 运行到微信小程序（需在 project.config.json 配置 appid）
npm run dev:mp-weixin

必装的辅助工具

1.6 项目目录速览

用 HBuilderX 创建的默认 uni-app 项目（Vue 3 + Vite 模板）结构如下：

my-uniapp/
├── src/
│   ├── pages/
│   │   └── index/
│   │       └── index.vue     # 首页
│   ├── static/               # 静态资源（图片、字体）
│   ├── uni_modules/          # uni-app 插件市场的组件
│   ├── App.vue               # 应用根组件，全局生命周期
│   ├── main.ts               # 入口文件，创建 Vue 实例
│   ├── manifest.json         # App 配置（appid、权限、图标）
│   └── pages.json            # 路由注册、导航栏、tabBar 配置
├── index.html                # H5 模板
├── vite.config.ts            # Vite 配置
└── package.json

uni-app x 的项目结构类似，但页面文件使用 .uvue 扩展名，UTS 逻辑文件使用 .uts 扩展名。

1.7 生命周期体系

uni-app 有三个层级的生命周期，理解它们的执行顺序至关重要：

应用生命周期（App.vue）

// App.vue
export default {
  onLaunch(options) {
    // 应用初次启动时触发（只触发一次）
    console.log('App 启动，参数：', options)
  },
  onShow(options) {
    // 应用进入前台时触发
  },
  onHide() {
    // 应用进入后台时触发
  }
}

页面生命周期

// 页面 .vue 文件
import { onLoad, onShow, onHide, onUnload, onReachBottom, onPullDownRefresh } from '@dcloudio/uni-app'

onLoad((query) => {
  // 页面加载，可获取路由参数 query
  console.log('页面参数：', query)
})

onShow(() => {
  // 页面每次显示时触发（包括从其他页面返回）
})

onReachBottom(() => {
  // 页面触底，适合加载更多数据
})

onPullDownRefresh(() => {
  // 下拉刷新（需在 pages.json 中启用 enablePullDownRefresh）
  // 完成后调用：
  uni.stopPullDownRefresh()
})

1.8 小结

本章我们建立了对 uni-app 生态的全局认知：

• uni-app（Vue 3 + Vite）适合全平台覆盖，尤其是小程序 + H5 场景
• uni-app x（UTS + uvue）适合 App 端原生性能需求，UTS 编译为 Kotlin/Swift 原生代码
• 条件编译是处理多平台差异的核心手段
• HBuilderX 是最佳开发环境，配合各平台调试工具使用
• uni-app 有三个层级生命周期：应用、页面、组件

下一章我们将深入项目结构与配置文件，理解 pages.json 和 manifest.json 的完整配置体系。