文章标签：#uni-app #跨平台开发 #前端实战 #小程序开发 #H5移动端

原创声明：本文为原创技术博客，从零梳理uni-app企业级开发完整流程，包含环境配置、项目搭建、跨端适配、接口请求

一、前言：为什么选择Uni-app跨平台开发？

在传统移动端开发中，多数项目需要分别开发微信小程序、安卓APP、iOS APP、移动端H5，多端代码割裂、重复开发、维护成本极高，这也是移动端开发的核心痛点。

而Uni-app是DCloud推出的基于Vue.js的全端跨平台开发框架，核心特性为一次编码，多端发布，一套代码可编译运行在微信/支付宝/抖音小程序、移动端H5、Android、iOS、鸿蒙等10+平台，完美解决多端重复开发的问题，是目前高校课程、企业中小型移动端项目的主流技术方案。

本文将结合课程项目实战，从零完成Uni-app跨平台项目完整开发，手把手教大家完成环境搭建、项目创建、页面开发、跨端适配、接口对接、项目打包全流程，适合Web应用课程结课作业、入门学习使用。

二、开发环境全套配置（零基础零踩坑）

Uni-app开发无需复杂的Java、Maven环境，仅需基础前端环境+官方开发工具，配置简单、上手快速，下面是可直接复用的标准开发环境配置步骤。

2.1 核心工具介绍

Uni-app官方推荐专属开发工具HBuilderX，相较于VS Code、WebStorm，该工具内置Uni-app编译环境、模拟器、报错检测、一键打包功能，是跨平台开发的最优选择。同时需要配套小程序开发者工具，用于调试小程序端项目。

、打包部署全流程，无搬运、无抄袭，适合新手入门与课程作业参考。

2.2 分步环境配置教程

第一步：安装HBuilderX编辑器

1. 进入HBuilderX官网，下载正式版（无需下载alpha测试版，稳定性更强）；

2. 安装完成后，打开工具，点击「工具-插件安装」，安装 uni-app编译插件、App真机运行插件，保证项目正常编译运行；

3. 配置完成后，重启HBuilderX，插件生效。

第二步：安装小程序开发者工具（可选，小程序调试必备）

1. 下载对应平台开发者工具，主流使用微信开发者工具；

2. 打开微信开发者工具，开启「端口设置」和「允许本地设置」，用于HBuilderX联动编译小程序项目。

第三步：基础环境校验

打开HBuilderX，点击「帮助-运行环境检测」，无报错、无缺失插件即代表环境配置完成，可正常开发Uni-app项目。

【配图建议1：HBuilderX插件安装界面+环境检测成功截图】

三、快速创建Uni-app标准项目（官方模板）

HBuilderX内置Uni-app官方模板，无需手动配置webpack、路由、适配规则，一键生成标准化项目架构，极大提升开发效率。

3.1 新建项目步骤

1. 打开HBuilderX，点击「文件-新建-项目」；

2. 项目名称自定义（如uni-app-demo、移动端课程项目）；

3. 选择模板：uni-app 基础模板（纯净模板，无多余冗余代码，适合课程开发）；

4. 勾选「创建uni-app项目」，点击创建，等待项目初始化完成。

3.2 项目核心目录结构解析（重点）

新手开发必须掌握核心目录，避免修改配置文件导致项目报错，标准目录作用如下：

• pages：核心页面目录，所有业务页面（首页、登录页、列表页）全部存放于此

• static：静态资源目录，存放图片、图标、本地静态文件

• components：自定义组件目录，封装公共按钮、卡片、导航栏等复用组件

• utils：工具类目录，存放接口请求、时间格式化、全局方法

• App.vue：项目全局入口，配置全局样式、全局生命周期

• main.js：全局挂载文件，挂载全局变量、接口、组件

• pages.json：核心配置文件，配置路由、导航栏、标题、tabbar、全局样式

【配图建议2：Uni-app项目完整目录结构截图+标注说明】

3.3 项目运行测试

1. 选中项目根目录，点击顶部「运行」；

2. 可选择运行到：浏览器（H5端）、微信模拟器、真机、App模拟器；

3. 编译成功后，默认展示官方首页，代表项目搭建成功。

四、核心实战：页面开发与跨端兼容适配

Uni-app基于Vue语法开发，同时针对多端差异提供了条件编译、统一单位、兼容样式，解决跨端适配难题，这也是区别于普通Vue项目的核心亮点。

4.1 统一尺寸单位（解决多端适配错乱）

Uni-app 摒弃px固定单位，统一使用rpx 自适应单位，rpx会自动根据屏幕宽度比例适配小程序、H5、APP所有平台，是跨端适配的核心关键。

规则：750rpx = 屏幕完整宽度，开发中直接使用rpx即可，无需手动适配不同设备。

4.2 条件编译（针对性适配多端差异）

不同平台存在原生差异（如小程序无浏览器属性、APP独有状态栏），Uni-app提供条件编译语法，可单独为某一个平台写专属代码，不影响其他端。

常用条件编译代码示例：

// #ifdef H5
// 仅H5端执行的代码
console.log("当前运行在H5浏览器端")
// #endif

// #ifdef MP-WEIXIN
// 仅微信小程序执行的代码
console.log("当前运行在微信小程序端")
// #endif

// #ifdef APP-PLUS
// 仅APP端执行的代码
console.log("当前运行在APP端")
// #endif

4.3 实战开发：自定义首页页面

在pages目录新建index页面，编写简单展示页面，兼容所有平台，完整可运行代码如下：

<template>
  <view class="content">
    <text class="title">Uni-app跨平台课程项目</text>
    <button type="primary" class="btn">跨端适配测试按钮</button>
  </view>
</template>

<script>
export default {
  name: "index",
  data() {
    return {}
  }
}
</script>

<style scoped>
.content {
  width: 750rpx;
  height: 100vh;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  background-color: #f5f7fa;
}
.title {
  font-size: 36rpx;
  color: #333;
  margin-bottom: 80rpx;
}
.btn {
  width: 600rpx;
}
</style>

【配图建议3：多端同步运行效果截图（H5+小程序双端界面一致）】

五、项目核心功能：全局接口请求封装

所有移动端项目都需要对接后端接口，Uni-app原生支持uni.request请求，我们可以全局封装请求方法，统一处理请求头、超时、报错、加载状态，适配多端请求规则。

5.1 在utils下新建request.js工具类

// 全局接口请求封装
const baseUrl = "http://localhost:8080/api" // 后端接口地址

// 请求封装
export function request(options) {
  // 开启加载动画
  uni.showLoading({
    title: "加载中..."
  })
  return new Promise((resolve, reject) => {
    uni.request({
      url: baseUrl + options.url,
      method: options.method || "GET",
      data: options.data || {},
      header: {
        "content-type": "application/json"
      },
      success: (res) => {
        uni.hideLoading()
        // 统一成功返回
        if (res.data.code === 200) {
          resolve(res.data)
        } else {
          uni.showToast({
            title: res.data.msg || "请求失败",
            icon: "none"
          })
          reject(res.data)
        }
      },
      fail: (err) => {
        uni.hideLoading()
        uni.showToast({
          title: "网络请求异常",
          icon: "none"
        })
        reject(err)
      }
    })
  })
}

export default request

5.2 全局挂载使用

在main.js中挂载全局，所有页面可直接调用，无需重复引入：

import request from './utils/request'
// 全局挂载
Vue.prototype.$request = request

六、路由与Tabbar底部导航配置

移动端项目必备底部导航栏，在pages.json中可快速配置全局路由和tabbar，无需手动封装，配置后多端同步生效。

pages.json核心配置代码：

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "pages/mine/mine",
      "style": {
        "navigationBarTitleText": "我的"
      }
    }
  ],
  "tabBar": {
    "color": "#666",
    "selectedColor": "#007aff",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "static/home.png",
        "selectedIconPath": "static/home-active.png"
      },
      {
        "pagePath": "pages/mine/mine",
        "text": "我的",
        "iconPath": "static/mine.png",
        "selectedIconPath": "static/mine-active.png"
      }
    ]
  }
}

【配图建议4：Tabbar底部导航最终效果截图】

七、项目打包与多端发布

Uni-app最大的优势就是一键多端打包发布，一套代码分别打包H5、小程序、APP，操作简单：

1. H5打包：运行-发行-网站-H5，自动生成dist打包文件，可直接部署到服务器；

2. 微信小程序打包：运行-发行-微信小程序，生成代码后导入微信开发者工具，直接上传发布；

3. APP打包：运行-发行-原生APP，可生成安卓apk、iOS安装包。

八、课程项目开发总结

本文完整实现了Uni-app跨平台项目从环境配置→项目搭建→页面开发→跨端适配→接口封装→路由配置→项目打包的全流程开发，相较于传统Web项目和原生移动端开发，Uni-app具备以下核心优势：

1. 开发成本低：一套代码适配10+平台，无需多端重复开发；

2. 上手门槛低：基于Vue语法，前端开发者可快速入门；

3. 适配性强：rpx单位+条件编译，完美解决多端样式、逻辑差异；

4. 部署便捷：一键打包多端，适配课程作业、小型商业项目开发场景。

九、常见开发踩坑问题（课程必备）

1. 样式错乱：统一使用rpx单位，禁止全局使用px；

2. 小程序请求报错：在微信开发者工具开启「不校验合法域名」；

3. 多端逻辑冲突：使用条件编译区分不同平台逻辑；

4. 页面不生效：检查pages.json路由配置是否正确。

结语

Uni-app跨平台开发是当下Web应用课程、移动端开发的热门技术方向，掌握全套开发流程，可快速完成课程大作业、小型移动端项目开发。本文所有代码均可直接复制运行，适合新手零基础学习。