1.1 UniApp简介
1.1.1 什么是UniApp
UniApp是一个使用Vue.js开发所有前端应用的框架，开发者编写一套代码，可发布到iOS、Android、Web（响应式）、以及各种小程序（微信/支付宝/百度/头条/飞书/QQ/快手/钉钉/淘宝）、快应用等多个平台。
1.1.2 UniApp的特点
一套代码，多端运行 - 使用Vue.js语法开发 - 支持10+个平台发布 - 代码复用率高达90%以上
丰富的组件和API - 内置丰富的基础组件 - 提供完整的API体系 - 支持原生插件扩展
强大的开发工具 - HBuilderX集成开发环境 - 可视化界面设计 - 实时预览和调试
活跃的生态系统 - 插件市场资源丰富 - 社区活跃，文档完善 - 持续更新和维护
1.1.3 UniApp架构原理
┌─────────────────────────────────────┐
│ UniApp │
├─────────────────────────────────────┤
│ Vue.js 框架 │
├─────────────────────────────────────┤
│ 编译器 (Compiler) │
├─────────────────────────────────────┤
│ 运行时 (Runtime) + 适配层 │
├─────────────────────────────────────┤
│ iOS │ Android │ Web │ 小程序... │
└─────────────────────────────────────┘
编译时转换： - Vue组件 → 各平台原生组件 - Vue API → 各平台原生API - CSS样式 → 平台特定样式
运行时适配： - 统一的事件系统 - 统一的生命周期 - 统一的数据绑定
1.1.4 支持的平台
| 平台类型 | 具体平台 | 说明 |
|---|---|---|
| 移动端 | iOS、Android | 原生App |
| Web端 | H5、PC Web | 响应式网页 |
| 小程序 | 微信、支付宝、百度、头条、QQ等 | 各厂商小程序 |
| 快应用 | 华为、小米、OPPO、VIVO等 | 手机厂商快应用 |
| 桌面端 | Windows、macOS、Linux | Electron应用 |
1.2 开发环境搭建
1.2.1 系统要求
操作系统： - Windows 7及以上 - macOS 10.12及以上 - Ubuntu 16.04及以上
硬件要求： - 内存：8GB以上推荐 - 存储：至少10GB可用空间 - 处理器：Intel i5或同等性能
1.2.2 安装HBuilderX
1. 下载HBuilderX
访问HBuilderX官网下载最新版本。
版本选择： - 标准版：免费，包含基础功能 - App开发版：付费，包含App打包等高级功能
2. 安装步骤
# Windows
1. 下载 HBuilderX.exe
2. 双击运行安装程序
3. 选择安装路径
4. 完成安装
# macOS
1. 下载 HBuilderX.dmg
2. 双击挂载镜像
3. 拖拽到Applications文件夹
4. 启动应用
# Linux
1. 下载 HBuilderX.tar.gz
2. 解压到指定目录
3. 运行 HBuilderX 可执行文件
3. 首次启动配置
// 启动HBuilderX后的配置步骤
1. 选择工作空间目录
2. 登录DCloud账号（可选）
3. 安装必要插件
4. 配置代码格式化选项
1.2.3 安装Node.js环境
1. 下载安装Node.js
# 访问 https://nodejs.org/
# 下载LTS版本（推荐）
# 验证安装
node --version
npm --version
2. 配置npm镜像（可选）
# 使用淘宝镜像加速
npm config set registry https://registry.npmmirror.com
# 验证配置
npm config get registry
3. 安装全局工具
# 安装Vue CLI（可选）
npm install -g @vue/cli
# 安装UniApp CLI（可选）
npm install -g @dcloudio/uvm
1.2.4 移动端开发环境
Android开发环境
# 1. 安装Android Studio
# 下载地址：https://developer.android.com/studio
# 2. 配置Android SDK
# 设置环境变量 ANDROID_HOME
# 添加到PATH：$ANDROID_HOME/tools
# $ANDROID_HOME/platform-tools
# 3. 创建Android虚拟设备（AVD）
# 在Android Studio中创建模拟器
iOS开发环境（仅macOS）
# 1. 安装Xcode
# 从App Store下载安装
# 2. 安装Xcode Command Line Tools
xcode-select --install
# 3. 配置iOS模拟器
# 在Xcode中配置iOS Simulator
1.2.5 小程序开发工具
微信小程序
# 1. 下载微信开发者工具
# https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html
# 2. 安装并登录微信账号
# 3. 获取小程序AppID（需要注册小程序账号）
支付宝小程序
# 1. 下载支付宝小程序开发者工具
# https://opendocs.alipay.com/mini/ide/download
# 2. 安装并登录支付宝账号
# 3. 创建小程序应用
1.3 创建第一个UniApp项目
1.3.1 使用HBuilderX创建项目
1. 新建项目
// 在HBuilderX中操作步骤
1. 文件 → 新建 → 项目
2. 选择 "uni-app" 项目类型
3. 选择模板：
- 默认模板（推荐新手）
- Hello uni-app（示例项目）
- 其他模板
4. 填写项目名称和存储位置
5. 点击创建
2. 项目模板选择
| 模板类型 | 适用场景 | 特点 |
|---|---|---|
| 默认模板 | 新项目开发 | 基础结构，轻量级 |
| Hello uni-app | 学习参考 | 包含丰富示例 |
| 登录模板 | 需要用户系统 | 包含登录注册功能 |
| 新闻模板 | 内容展示类 | 新闻列表和详情 |
| 商城模板 | 电商应用 | 商品展示和购买流程 |
1.3.2 使用Vue CLI创建项目
1. 安装Vue CLI
# 全局安装Vue CLI
npm install -g @vue/cli
# 验证安装
vue --version
2. 创建UniApp项目
# 使用Vue CLI创建项目
vue create -p dcloudio/uni-preset-vue my-uniapp-project
# 选择模板
# 1. 默认模板
# 2. 默认模板(TypeScript)
# 3. 默认模板(Vue3/Vite)
# 进入项目目录
cd my-uniapp-project
# 安装依赖
npm install
3. 项目结构说明
my-uniapp-project/
├── public/ # 静态资源目录
│ └── index.html # HTML模板
├── src/ # 源代码目录
│ ├── components/ # 组件目录
│ ├── pages/ # 页面目录
│ ├── static/ # 静态资源
│ ├── store/ # 状态管理
│ ├── utils/ # 工具函数
│ ├── App.vue # 应用入口组件
│ ├── main.js # 应用入口文件
│ ├── manifest.json # 应用配置文件
│ ├── pages.json # 页面路由配置
│ └── uni.scss # 全局样式
├── package.json # 项目配置文件
└── README.md # 项目说明
1.3.3 项目配置详解
1. manifest.json配置
{
"name": "my-uniapp-project",
"appid": "__UNI__XXXXXXX",
"description": "我的第一个UniApp项目",
"versionName": "1.0.0",
"versionCode": "100",
"transformPx": false,
"app-plus": {
"usingComponents": true,
"nvueStyleCompiler": "uni-app",
"compilerVersion": 3,
"splashscreen": {
"alwaysShowBeforeRender": true,
"waiting": true,
"autoclose": true,
"delay": 0
},
"modules": {},
"distribute": {
"android": {
"permissions": [
"<uses-permission android:name=\"android.permission.CHANGE_NETWORK_STATE\" />",
"<uses-permission android:name=\"android.permission.MOUNT_UNMOUNT_FILESYSTEMS\" />",
"<uses-permission android:name=\"android.permission.VIBRATE\" />",
"<uses-permission android:name=\"android.permission.READ_LOGS\" />",
"<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\" />",
"<uses-feature android:name=\"android.hardware.camera.autofocus\" />",
"<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\" />",
"<uses-permission android:name=\"android.permission.CAMERA\" />",
"<uses-permission android:name=\"android.permission.GET_ACCOUNTS\" />",
"<uses-permission android:name=\"android.permission.READ_PHONE_STATE\" />",
"<uses-permission android:name=\"android.permission.CHANGE_WIFI_STATE\" />",
"<uses-permission android:name=\"android.permission.WAKE_LOCK\" />",
"<uses-permission android:name=\"android.permission.FLASHLIGHT\" />",
"<uses-permission android:name=\"android.permission.WRITE_SETTINGS\" />"
]
},
"ios": {},
"sdkConfigs": {}
}
},
"quickapp": {},
"mp-weixin": {
"appid": "",
"setting": {
"urlCheck": false
},
"usingComponents": true
},
"mp-alipay": {
"usingComponents": true
},
"mp-baidu": {
"usingComponents": true
},
"mp-toutiao": {
"usingComponents": true
},
"uniStatistics": {
"enable": false
},
"vueVersion": "3"
}
2. pages.json配置
{
"pages": [
{
"path": "pages/index/index",
"style": {
"navigationBarTitleText": "首页"
}
},
{
"path": "pages/about/about",
"style": {
"navigationBarTitleText": "关于我们"
}
}
],
"globalStyle": {
"navigationBarTextStyle": "black",
"navigationBarTitleText": "uni-app",
"navigationBarBackgroundColor": "#F8F8F8",
"backgroundColor": "#F8F8F8"
},
"tabBar": {
"color": "#7A7E83",
"selectedColor": "#3cc51f",
"borderStyle": "black",
"backgroundColor": "#ffffff",
"list": [
{
"pagePath": "pages/index/index",
"iconPath": "static/tab-home.png",
"selectedIconPath": "static/tab-home-current.png",
"text": "首页"
},
{
"pagePath": "pages/about/about",
"iconPath": "static/tab-about.png",
"selectedIconPath": "static/tab-about-current.png",
"text": "关于"
}
]
}
}
1.4 运行和调试项目
1.4.1 在HBuilderX中运行
1. 运行到浏览器
// 操作步骤
1. 在项目上右键
2. 选择 "运行" → "运行到浏览器" → "Chrome"
3. 项目会自动编译并在浏览器中打开
4. 支持热重载，修改代码会自动刷新
2. 运行到小程序
// 微信小程序
1. 运行 → 运行到小程序模拟器 → 微信开发者工具
2. 首次运行需要配置微信开发者工具路径
3. 自动打开微信开发者工具并加载项目
// 支付宝小程序
1. 运行 → 运行到小程序模拟器 → 支付宝开发者工具
2. 配置支付宝开发者工具路径
3. 在支付宝开发者工具中预览
3. 运行到手机或模拟器
// Android
1. 连接Android设备或启动模拟器
2. 运行 → 运行到手机或模拟器 → Android
3. 选择设备进行安装和调试
// iOS（仅macOS）
1. 连接iOS设备或启动模拟器
2. 运行 → 运行到手机或模拟器 → iOS
3. 需要配置开发者证书
1.4.2 使用命令行运行
1. 开发模式运行
# 运行到H5
npm run dev:h5
# 运行到微信小程序
npm run dev:mp-weixin
# 运行到支付宝小程序
npm run dev:mp-alipay
# 运行到Android
npm run dev:app-android
# 运行到iOS
npm run dev:app-ios
2. 生产模式构建
# 构建H5
npm run build:h5
# 构建微信小程序
npm run build:mp-weixin
# 构建支付宝小程序
npm run build:mp-alipay
# 构建Android
npm run build:app-android
# 构建iOS
npm run build:app-ios
1.4.3 调试技巧
1. 浏览器调试
// 使用浏览器开发者工具
1. F12打开开发者工具
2. 在Console中查看日志
3. 在Sources中设置断点
4. 在Network中查看网络请求
// 移动端调试
1. 开启浏览器移动端模拟
2. 选择不同设备尺寸测试
3. 模拟触摸事件
2. 小程序调试
// 微信开发者工具调试
1. 在调试器中查看页面结构
2. 在Console中执行JavaScript
3. 在Network中查看请求
4. 在Storage中查看本地存储
// 真机调试
1. 开启调试模式
2. 扫码在真机上预览
3. 使用vconsole进行调试
3. App调试
// Android调试
1. 启用USB调试
2. 使用Chrome DevTools
3. 查看logcat日志
// iOS调试
1. 连接Xcode
2. 查看控制台日志
3. 使用Safari Web Inspector
1.5 常见问题与解决方案
1.5.1 安装问题
问题1：HBuilderX启动失败
# 解决方案
1. 检查系统权限
2. 关闭杀毒软件
3. 以管理员身份运行
4. 重新下载安装
问题2：Node.js安装失败
# 解决方案
1. 下载官方LTS版本
2. 清理之前的安装残留
3. 检查系统环境变量
4. 使用nvm管理Node版本
1.5.2 项目创建问题
问题1：项目创建失败
// 可能原因和解决方案
1. 网络连接问题 → 检查网络或使用代理
2. 权限不足 → 使用管理员权限
3. 磁盘空间不足 → 清理磁盘空间
4. 路径包含中文 → 使用英文路径
问题2：依赖安装失败
# 解决方案
# 清理npm缓存
npm cache clean --force
# 删除node_modules重新安装
rm -rf node_modules
npm install
# 使用yarn替代npm
npm install -g yarn
yarn install
1.5.3 运行问题
问题1：编译失败
// 常见原因
1. 语法错误 → 检查代码语法
2. 依赖缺失 → 安装缺失的依赖
3. 版本不兼容 → 检查版本兼容性
4. 配置错误 → 检查配置文件
问题2：热重载不工作
// 解决方案
1. 重启开发服务器
2. 清理浏览器缓存
3. 检查文件监听设置
4. 更新HBuilderX版本
1.5.4 调试问题
问题1：无法连接调试器
# Android调试
1. 检查USB调试是否开启
2. 安装ADB驱动
3. 检查设备连接状态
4. 重启ADB服务
# iOS调试
1. 信任开发者证书
2. 检查设备连接
3. 重启Xcode
4. 检查开发者账号
问题2：小程序调试异常
// 解决方案
1. 更新开发者工具
2. 清理小程序缓存
3. 检查AppID配置
4. 重新导入项目
1.6 开发工具详解
1.6.1 HBuilderX功能介绍
1. 代码编辑功能
// 智能提示
- Vue语法高亮
- 组件属性提示
- API自动补全
- 错误检查和提示
// 代码格式化
- 自动缩进
- 代码美化
- 自定义格式化规则
2. 项目管理功能
// 项目结构
- 文件树视图
- 快速搜索文件
- 批量操作文件
- 项目模板管理
// 版本控制
- Git集成
- 代码对比
- 提交历史查看
3. 调试和预览
// 实时预览
- 边写边看效果
- 多设备同步预览
- 二维码扫码预览
// 调试工具
- 断点调试
- 变量查看
- 调用栈分析
1.6.2 插件和扩展
1. 必备插件
// 代码提示插件
- uni-app代码块
- Vue语法提示
- JavaScript增强
// 主题插件
- 暗色主题
- 护眼主题
- 自定义主题
// 工具插件
- 代码格式化
- 图片压缩
- 文件对比
2. 插件安装方法
// 通过插件市场安装
1. 工具 → 插件安装
2. 搜索需要的插件
3. 点击安装
4. 重启HBuilderX
// 手动安装插件
1. 下载插件文件
2. 解压到plugins目录
3. 重启编辑器
1.6.3 自定义配置
1. 编辑器设置
// settings.json配置示例
{
"editor.fontSize": 14,
"editor.tabSize": 2,
"editor.insertSpaces": true,
"editor.wordWrap": "on",
"editor.minimap.enabled": true,
"files.autoSave": "afterDelay",
"files.autoSaveDelay": 1000
}
2. 快捷键设置
// 常用快捷键
Ctrl + S // 保存文件
Ctrl + Shift + P // 命令面板
Ctrl + ` // 打开终端
Ctrl + / // 注释代码
Ctrl + D // 选择相同内容
F5 // 运行项目
F12 // 打开调试工具
1.7 本章小结
1.7.1 学习要点回顾
- UniApp概念：理解UniApp的核心理念和架构原理
- 环境搭建：掌握完整的开发环境配置流程
- 项目创建：学会使用不同方式创建UniApp项目
- 运行调试：熟悉各平台的运行和调试方法
- 问题解决：了解常见问题的解决方案
1.7.2 实践练习
练习1：环境验证
# 验证开发环境是否正确安装
1. 检查HBuilderX是否正常启动
2. 验证Node.js和npm版本
3. 测试创建新项目
4. 尝试运行到不同平台
练习2：项目探索
// 熟悉项目结构
1. 查看默认项目的文件结构
2. 理解各配置文件的作用
3. 修改页面内容并查看效果
4. 尝试添加新页面
1.7.3 下章预告
下一章我们将深入学习UniApp的项目结构和开发工具的使用，包括： - 详细的项目目录结构分析 - 配置文件的深入理解 - 开发工具的高级功能 - 代码组织和管理最佳实践
1.7.4 扩展阅读
恭喜您完成了UniApp开发环境的搭建！现在您已经具备了开始UniApp开发的基础条件。
