在移动互联网多端化的今天，一款产品往往需要同时覆盖微信小程序、H5、iOS App、Android App 甚至鸿蒙应用。如果为每个平台单独开发一套代码，不仅开发成本高昂，后期维护更是噩梦。Uni-app 正是为解决这一痛点而生的跨端开发框架。它基于 Vue.js 技术栈，遵循 “一次编码，多端运行” 的理念。截至 2026 年，Uni-app 生态已覆盖数百万应用，月活设备超 12 亿，成为国内跨端开发的事实标准。

本文将从基础概念出发，逐步深入到企业级开发实战，涵盖环境搭建、核心语法、条件编译、网络封装、状态管理、性能优化等全链路知识点，帮助读者系统性掌握 Uni-app 开发能力。

一、环境搭建与项目初始化

1.1 开发工具选择

Uni-app 官方推荐使用 HBuilderX 作为主力开发 IDE，它内置了完整的编译、运行、打包能力，对 App 端原生调试和云打包支持最为完善。对于习惯 VSCode 的开发者，也可以通过 unibest 等脚手架实现 VSCode 开发环境搭建。

表格

方案	优势	适用场景
HBuilderX	官方原生支持、真机调试便捷、云打包开箱即用	全平台开发、App 端为主
VSCode + unibest	插件生态丰富、TS 支持更好、Vite 构建速度快	H5 + 小程序为主、前端团队协作

1.2 项目创建与目录规范

一个规范的 Uni-app 项目目录结构如下：

text

┌─ uni_modules          // 插件模块目录（uni_modules规范）
├─ pages                // 页面目录
│  └─ index
│     └─ index.vue      // 首页
├─ static               // 静态资源（图片、字体等）
├─ utils                // 工具函数
├─ api                  // 接口请求
├─ stores               // Pinia 状态管理
├─ components           // 公共组件
├─ App.vue              // 应用入口
├─ main.js              // 主入口文件
├─ pages.json           // 页面路由与全局配置
└─ manifest.json        // 应用配置与各平台参数

二、核心配置文件详解

2.1 pages.json

pages.json 是 Uni-app 最重要的配置文件，负责页面路由、导航栏、TabBar、窗口样式等全局配置。

json

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页",
        "enablePullDownRefresh": true
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "UniApp实战",
    "backgroundColor": "#f5f5f5"
  },
  "tabBar": {
    "color": "#999999",
    "selectedColor": "#007aff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "static/tab/home.png",
        "selectedIconPath": "static/tab/home-active.png"
      }
    ]
  }
}

2.2 manifest.json

用于配置应用 ID、版本号、各平台专属参数（如小程序 AppID、App 权限声明等）。针对不同平台特性，需在此配置差异化参数，例如微信小程序的权限声明：

json

"mp-weixin": {
  "appid": "wx...",
  "permission": {
    "scope.userLocation": {
      "desc": "需要获取位置信息"
    }
  }
}

三、跨端基石：条件编译与 Vue3 适配

3.1 条件编译 (Conditional Compilation)

不要试图用一套逻辑强行覆盖所有端，Uni-app 提供的条件编译是解决差异化的最有效手段。

语法速查：

• // #ifdef %PLATFORM% ：仅在某平台存在。
• // #ifndef %PLATFORM% ：除了某平台均存在。

实战场景：API 差异处理

javascript

运行

getUserInfo() {
  // #ifdef MP-WEIXIN
  // 微信小程序逻辑
  uni.getUserProfile({
    desc: '用于完善会员资料',
    success: (res) => this.saveUser(res.userInfo)
  });
  // #endif
  
  // #ifdef APP-PLUS
  // App 逻辑：通过 SDK 登录或原生插件
  uni.login({
    provider: 'weixin',
    success: (res) => this.getAppUserInfo(res)
  });
  // #endif
}

3.2 Vue3 + TypeScript 开发范式

2025/2026 年的 Uni-app 已全面支持 Vue3 组合式 API，推荐使用 TypeScript 提升代码健壮性。

vue

<template>
  <view class="container">
    <text class="title">{{ message }}</text>
  </view>
</template>

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

const message = ref<string>('Hello UniApp 2026')
</script>

<style scoped>
.container {
  display: flex;
  flex-direction: column;
  align-items: center;
  padding: 40rpx;
}
</style>

四、企业级接口封装与安全策略

4.1 统一请求封装

创建 utils/request.js 实现统一请求管理：

javascript

运行

const baseURL = process.env.NODE_ENV === 'development' 
  ? 'https://test.api.com' 
  : 'https://prod.api.com';

const request = (options) => {
  return new Promise((resolve, reject) => {
    uni.request({
      url: baseURL + options.url,
      method: options.method || 'GET',
      data: options.data || {},
      header: {
        'Authorization': uni.getStorageSync('token'),
        'Content-Type': 'application/json'
      },
      success(res) {
        if (res.statusCode === 200) {
          resolve(res.data);
        } else {
          reject(res);
        }
      },
      fail(err) {
        reject(err);
      }
    });
  });
};

export default request;

4.2 接口安全策略

1. 传输层：强制 HTTPS 协议，配置 HSTS 头。
2. 鉴权层：JWT 令牌 + Refresh Token 机制。
3. 数据层：敏感字段 AES 加密。

五、样式兼容性避坑指南

5.1 导航栏与状态栏

• H5：通常有浏览器的地址栏。
• 小程序：右上角有胶囊按钮，自定义导航栏时需计算胶囊位置。
• App：沉浸式状态栏是标配。

最佳实践：取消原生导航栏（navigationStyle: "custom"），封装一个全局的 <CustomNavbar> 组件，内部根据 uni.getSystemInfoSync() 获取 statusBarHeight 和 titleBarHeight 进行动态占位。

5.2 底部安全区 (iPhone X+)

在 iOS 底部带有 “黑条” 的设备上，绝对定位的按钮容易被遮挡。

css

.footer-btn {
  position: fixed;
  bottom: 0;
  /* 适配底部安全区 */
  padding-bottom: constant(safe-area-inset-bottom); /* 兼容 iOS < 11.2 */
  padding-bottom: env(safe-area-inset-bottom);      /* 兼容 iOS >= 11.2 */
}

5.3 rpx 的陷阱与 PC 适配

rpx 在小程序和 App 端表现良好，但在 H5 端（尤其是 PC 浏览器访问 H5 时）可能会变得巨大。

解决方案：在 pages.json 中配置 globalStyle：

json

"rpxCalcMaxDeviceWidth": 960, 
"rpxCalcBaseDeviceWidth": 375, 
"rpxCalcIncludeWidth": 750 

对于 PC 端，建议利用 match-media 组件或 CSS 媒体查询提供两栏或三栏布局，而不是简单粗暴的拉伸。

六、性能优化与高阶实战

1. 代码分包加载：小程序有包体积限制，将非核心页面放入 subPackages 中，主包只保留 TabBar 页面和核心公共组件。
2. App 端渲染瓶颈：在长列表、复杂地图交互等场景，必要时使用 NVUE (原生渲染引擎)，App 端性能较传统 WebView 提升 50%。
3. 图片优化：使用 WebP 格式，结合懒加载指令，避免一次性加载过多高清大图。
4. 预加载策略：利用 preloadRule 在用户进入特定页面时，提前下载后续可能访问的分包。

总结

Uni-app 凭借 “一套代码覆盖 15 + 平台” 的能力，极大地降低了企业的开发和维护成本。但在实际项目中，真正的 “一套代码” 往往伴随着大量的条件编译和平台特异性处理。掌握条件编译、熟悉各端样式差异、做好工程化封装，是写出高质量跨端应用的关键。希望本文能为你的跨端开发之路提供有力的参考。