uni-app 使用教程：从入门到发布

一、uni-app 简介

uni-app 是一个使用 Vue.js 开发所有前端应用的框架，开发者编写一套代码，可发布到 iOS、Android、H5、微信小程序、支付宝小程序、百度小程序、字节跳动小程序、QQ小程序、快应用等多个平台。uni-app 采用"一次开发，多端运行"的理念，大幅提升开发效率，学习成本低，生态丰富，性能接近原生。

二、环境搭建

1. 安装开发工具

HBuilderX 是官方推荐的 IDE，内置 uni-app 开发支持：

下载地址：
选择"App开发版"进行安装
安装完成后，打开 HBuilderX，点击"新建项目"→"uni-app"

Node.js 环境准备：

从 Node.js 官网下载并安装最新版本
验证安装：在命令行输入 node -v 和 npm -v

2. 创建第一个 uni-app 项目

在 HBuilderX 中：

点击"文件"→"新建"→"项目"
选择"uni-app"类型
填写项目名称（如 MyFirstUniApp）
选择模板（推荐"Hello uni-app"或"uni-ui项目模板"）
点击创建

三、项目结构解析

创建的项目默认包含以下核心目录：

复制代码

├── pages          // 页面目录，每个页面一个文件夹
├── static         // 静态资源（图片、字体等）
├── components     // 自定义组件目录
├── uni_modules    // uni-app模块（新增）
├── App.vue        // 应用入口组件
├── main.js        // 项目入口文件
├── manifest.json  // 应用配置（如AppID、启动图等）
└── pages.json     // 页面路由与导航栏样式配置

关键文件说明：

pages.json：配置页面路由、导航栏、TabBar等
App.vue：全局样式和生命周期管理
manifest.json：配置App的图标、权限、SDK等

四、页面开发

1. 新建页面

在 pages 目录下右键"新建页面"，输入名称（如 todo），自动生成页面文件。

2. 编写页面代码

复制代码

<template>
  <view class="container">
    <input v-model="newTask" placeholder="输入任务" @confirm="addTask" />
    <button @click="addTask">添加</button>
    <view v-for="(task, index) in tasks" :key="index">
      {{ task }}
      <button @click="removeTask(index)">删除</button>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      newTask: "",
      tasks: []
    };
  },
  methods: {
    addTask() {
      if (this.newTask.trim()) {
        this.tasks.push(this.newTask);
        this.newTask = "";
      }
    },
    removeTask(index) {
      this.tasks.splice(index, 1);
    }
  }
};
</script>

<style>
.container {
  padding: 20px;
}
</style>

3. 配置页面路由

在 pages.json 中配置：

复制代码

{
  "pages": [
    {
      "path": "pages/todo/todo",
      "style": {
        "navigationBarTitleText": "待办清单"
      }
    }
  ]
}

五、组件使用

1. 内置组件

uni-app 内置了小程序的所有组件，如 view、text、button、image、picker、map 等。组件标签靠近小程序规范，事件绑定使用 Vue 的语法。

2. 自定义组件

创建组件：

在 components 目录下创建 .vue 文件：

复制代码

<template>
  <view>这是一个自定义组件</view>
</template>

<script>
export default {
  props: ['msg']
}
</script>

使用组件：

复制代码

<template>
  <view>
    <my-component :msg="message"></my-component>
  </view>
</template>

<script>
import MyComponent from '@/components/MyComponent.vue'

export default {
  components: { MyComponent },
  data() {
    return {
      message: 'Hello'
    }
  }
}
</script>

3. uni-ui 组件库

uni-ui 是官方维护的组件库，跨平台兼容性好：

安装：

复制代码

npm install @dcloudio/uni-ui

配置：

在 pages.json 中配置：

复制代码

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^uni-dcloudio/uni-ui/lib/uni-(.*)/uni-(.*).vue": "$1"
    }
  }
}

使用：

复制代码

<template>
  <uni-card>
    <text>这是一个卡片组件</text>
  </uni-card>
</template>

六、API 调用

uni-app 提供了丰富的 API，前缀为 uni.：

复制代码

// 网络请求
uni.request({
  url: 'https://example.com/api',
  success: (res) => {
    console.log(res.data)
  }
})

// 显示提示
uni.showToast({
  title: '操作成功',
  icon: 'success'
})

// 获取系统信息
uni.getSystemInfo({
  success: (res) => {
    console.log(res.model)
  }
})

七、调试与运行

1. 浏览器运行

点击 HBuilderX 工具栏的"运行"→"运行到浏览器"→选择浏览器，即可在浏览器中预览 H5 版本。

2. 小程序运行

微信小程序：

点击"运行"→"运行到小程序模拟器"→"微信开发者工具"
需提前安装微信开发者工具并配置路径

其他小程序：

支付宝小程序：运行到支付宝小程序开发者工具
百度小程序：运行到百度开发者工具
字节跳动小程序：运行到字节跳动开发者工具

3. 真机调试

连接手机，开启 USB 调试，点击"运行"→"真机运行"→选择设备，即可在真机上调试。

八、打包与发布

1. 发布到微信小程序

在 manifest.json 中配置微信小程序的 AppID
点击"发行"→"小程序-微信"，生成生产环境代码
上传至微信开发者工具，提交审核

2. 发布为 H5

点击"发行"→"网站-H5"，生成 dist 目录，部署到服务器（如 Nginx、阿里云 OSS）。

3. 打包为 App

云打包（推荐）：

在 manifest.json 中配置 App 图标、启动页等
点击"发行"→"原生App-云打包"
下载安装包，上传至应用商店

本地打包：

需配置 Android 证书（.keystore 文件）
iOS 需 Apple 开发者证书和描述文件

九、调试技巧

微信小程序：使用微信开发者工具的"调试"面板
H5：浏览器 F12 开发者工具
App：HBuilderX 的"真机调试"功能

常见问题解决：

样式不生效：检查是否使用了小程序不支持的 CSS 属性
跨端兼容问题：使用 #ifdef MP-WEIXIN 或 #ifdef H5 做条件编译

十、学习资源推荐

官方文档：
uni-ui 组件库：
插件市场：
社区论坛：

通过本教程，你已经掌握了 uni-app 的基础开发流程。建议从一个小项目开始实践，逐步探索 uni-app 的更多高级特性，如状态管理（Vuex/Pinia）、云开发（uniCloud）等。