🚀 UniApp 从零到一完整入门指南涵盖环境搭建、项目创建、页面开发、组件使用、API 调用、打包发布等全流程内容。

涵盖环境搭建、项目创建、页面开发、组件使用、API 调用、打包发布等全流程内容。

✅ 一、什么是 UniApp？

UniApp 是一个使用 Vue.js 开发所有前端应用的框架。
支持一次开发，多端发布：

- 微信小程序
- H5
- App（iOS / Android）
- 百度/支付宝/抖音/快手小程序
- 快应用
- QQ 小程序等

官网：www.dcloud.io

✅ 二、环境准备

1. 安装 HBuilderX（推荐）

HBuilderX 是 DCloud 推出的官方 IDE，对 UniApp 支持最好。

下载地址：www.dcloud.io/hbuilderx.h…
选择对应系统版本（Windows / macOS）

💡 优点：内置编译器、真机调试、代码提示、一键运行

2. 安装 Node.js（可选）

虽然 HBuilderX 不强制要求，但如果你要用 CLI 创建项目或使用 npm 包管理，则需要安装：

下载地址：nodejs.org
推荐 LTS 版本（如 v18.x）

✅ 三、创建第一个项目

方法一：使用 HBuilderX 图形化创建（推荐新手）

打开 HBuilderX
点击菜单栏：文件 > 新建 > 项目
选择项目类型：

- uni-app 或 uni-app Vue3

填写项目名称（如 hello-uniapp）
选择模板：推荐 默认模板
点击“创建”

方法二：使用命令行（CLI）

# 全局安装 @dcloudio/uni-cli
npm install -g @dcloudio/uni-cli

# 创建项目
npx degit dcloudio/uni-preset-vue#vite my-project

cd my-project
npm install
npm run dev:mp-weixin  # 运行微信小程序

✅ 四、项目结构解析

hello-uniapp/
├── pages/               // 页面目录
│   ├── index/
│   │   └── index.vue    // 首页页面
│   └── about/
│       └── about.vue
├── static/              // 静态资源（图片、字体等）
├── unpackage/           // 编译后的文件（自动生成）
├── main.js              // 应用入口文件
├── App.vue              // 根组件
├── manifest.json        // 应用配置（名称、图标、启动页等）
├── pages.json           // 页面路由、窗口样式、 tabBar 配置
└── uni.scss             // 公共样式变量

✅ 五、配置 pages.json

这是核心配置文件，用于设置：

1. 页面路由注册

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "首页"
      }
    },
    {
      "path": "pages/about/about",
      "style": {
        "navigationBarTitleText": "关于我们"
      }
    }
  ]
}

2. 设置底部 TabBar

{
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "static/tabbar/home.png",
        "selectedIconPath": "static/tabbar/home-active.png"
      },
      {
        "pagePath": "pages/about/about",
        "text": "关于",
        "iconPath": "static/tabbar/about.png",
        "selectedIconPath": "static/tabbar/about-active.png"
      }
    ]
  }
}

注意：TabBar 图片必须为 png 格式，建议尺寸 80x80 px，大小不超过 40KB。

✅ 六、编写页面（Vue 单文件组件）

示例：pages/index/index.vue

<template>
  <view class="container">
    <text class="title">欢迎使用 UniApp！</text>
    <button @click="goToAbout">跳转到关于页</button>
    <image src="/static/logo.png" mode="widthFix"></image>
  </view>
</template>
<script setup>
import { navigateTo } from '@dcloudio/uni-api-router'

const goToAbout = () => {
  uni.navigateTo({
    url: '/pages/about/about'
  })
}
</script>
<style>
.container {
  padding: 20px;
  text-align: center;
}
.title {
  font-size: 24px;
  color: #007AFF;
}
</style>

✅ 七、常用 API 示例

1. 跳转页面

uni.navigateTo({
  url: '/pages/about/about'
})

2. 显示消息提示

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

3. 获取用户信息（微信小程序）

uni.getUserProfile({
  desc: '用于完善资料',
  success: (res) => {
    console.log(res.userInfo)
  }
})

4. 请求数据（uni.request）

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

✅ 八、条件编译（多端兼容）

// #ifdef MP-WEIXIN
console.log('这是微信小程序')
// #endif

// #ifdef H5
console.log('这是 H5 页面')
// #endif

// #ifdef APP-PLUS
console.log('这是 App')
// #endif

支持平台标识：

MP-WEIXIN：微信小程序
H5：H5 页面
APP-PLUS：App
MP-ALIPAY：支付宝小程序

✅ 九、打包与发布

1. 发布 H5

HBuilderX 中点击：发行 > 网站-H5手机浏览器
生成静态文件，部署到 Nginx / Vercel / Netlify 等

2. 发布微信小程序

点击：发行 > 小程序-微信
使用微信开发者工具打开导出的目录
上传代码、提审、发布

3. 发布 App（Android / iOS）

点击：发行 > 原生App-云打包
选择模式：

- 自定义基座（调试用）
- 云打包（正式包）

配置证书、图标、启动图等（manifest.json）
生成 .apk（Android）或 .ipa（iOS）

iOS 打包需 Mac 环境 + 苹果开发者账号

✅ 十、进阶技巧

1. 使用 Vuex/Pinia 状态管理

npm install pinia

在 main.js 中注册：

import { createSSRApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

export function createApp() {
  const app = createSSRApp(App)
  const pinia = createPinia()
  app.use(pinia)
  return { app }
}

2. 使用 Sass/Scss

// 安装
npm install sass --save-dev

// 在 style 中使用
<style lang="scss">
.container {
  .title {
    color: $uni-color-primary;
  }
}
</style>

3. 引入第三方 UI 库

✅ 十一、常见问题 FAQ

问题	解决方案
页面不显示？	检查 `pages.json` 是否注册了路径
图片不显示？	使用 `/static/xxx.png` 绝对路径
跨域问题？	H5 端需配置代理或后端 CORS
App 打包失败？	检查证书、图标、权限配置
小程序登录获取 openid？	需调用微信登录接口 + 后端配合

✅ 十二、学习资源推荐

📘 官方文档：uniapp.dcloud.io
🎥 B站教程：搜索“uniapp 入门”有很多免费视频
🧩 GitHub 示例项目：

- github.com/dcloudio/un…

💬 社区交流：

- DCloud 官方论坛
- CSDN、掘金、思否

✅ 总结：UniApp 从 0 到 1 步骤回顾

步骤	内容
1	安装 HBuilderX
2	创建项目
3	配置 pages.json
4	编写页面（.vue）
5	使用 API 和组件
6	条件编译适配多端
7	打包发布（H5 / 小程序 / App）

🎯 目标达成：你现在可以独立开发一个跨端应用了！

进阶：

完整项目源码打包
商城类模板结构
登录 + 请求封装模板
可视化配置工具推荐