黑马前端 2024 · 教程站

主题

项目介绍与 uni-app 基础（一） ​

本页对应 项目介绍与 uni-app 基础，共 7 段视频，约 51 分钟。

学习目标 ​

  1. 能独立完成 HBuilderX 的下载、安装与首次启动配置，并将编辑器主题与快捷键方案设置为 VS Code 风格。
  2. 能使用 HBuilderX 创建 uni-app 项目，正确选择默认模板与 Vue3 版本，并将项目存放在规范目录中。
  3. 能将创建好的 uni-app 项目分别运行到浏览器（H5）和微信小程序端，并说明两端运行结果的对应关系。
  4. 能配置微信小程序运行环境，包括在 manifest 中填写 AppID、在微信开发者工具中开启服务端口，并能解决 HBuilderX 无法自动打开微信开发者工具时的手动路径配置问题。
  5. 能完成安卓真机运行环境配置，包括开启开发者选项与 USB 调试、安装真机运行插件与 ADB 驱动，并在 HBuilderX 中识别设备后运行项目。
  6. 能用自己的话说明 uni-app 跨端开发的含义，并列举其可运行的目标端（H5、小程序、App）及一套代码多端运行的基本优势。

知识点 ​

本节目标与整体思路 ​

本节要掌握三件事：创建 uni-app 项目、把项目运行到浏览器/小程序、配置 Android 真机运行环境。转写稿里反复强调，这一节“操作多、理解少”，遇到错误不用慌，可以按步骤从头重做，直到环境正常运行。

为什么需要：uni-app 的核心价值是“跨端开发”，一套代码可生成 H5、小程序、App 等多端项目；但跨端项目要先有可运行的开发环境，否则后面写页面、调接口都无从谈起。
怎么想：先装工具 HBuilderX，再建一个最干净的默认模板项目，然后分别验证浏览器端、小程序端，最后接 Android 真机。
怎么做：按“安装工具 → 创建项目 → 运行 H5 → 运行小程序 → 配置真机”的顺序推进。
易错点：HBuilderX 不要放中文目录；创建项目不要选错模板和 Vue 版本；小程序要填 AppID 并打开微信开发者工具服务端口；真机要开 USB 调试并装驱动。

安装 HBuilderX ​

为什么需要：HBuilderX 是 DCloud 推出的开发工具，类似 VS Code，但针对 uni-app 做了运行到浏览器、小程序、手机等集成能力。
怎么想：把 HBuilderX 当成“uni-app 专用编辑器”，先保证它能正常启动，再谈建项目。
怎么做：Windows 下载压缩包，解压后找到 HBuilderX.exe 双击启动，建议创建桌面快捷方式；Mac 下载 .dmg 后拖入安装。首次启动按喜好选主题，快捷键风格建议选 VS Code，便于延续已有习惯。
易错点：Windows 下千万不要把 HBuilderX 放在中文目录中；关闭时若提示创建快捷方式，建议选择“是”，方便后续启动。

首次启动 HBuilderX

用 HBuilderX 创建 uni-app 项目 ​

为什么需要：后续课程项目“神领物流”是 uni-app 项目，需要先有一个标准工程骨架。
怎么想：学习阶段选“默认模板”，因为初始代码最少、项目最干净，便于在空白基础上理解结构。
怎么做：菜单栏选择【文件】→【新建】→【项目】，项目类型选 uni-app，模板选默认模板，Vue 版本选 Vue3；项目目录要放在自己常用、规范的资料目录中，项目名可自定义。创建后能看到目录和文件，其中 .vue 文件就是 Vue 单文件组件，包含模板、脚本、样式。
易错点：不要把项目类型选成普通 Vue 或其他模板；Vue 版本按课程统一选 Vue3；目录不要随手乱放，便于以后复习和查找。

创建项目

配置项目属性

项目概览

vue-cli 方式说明与代码保留 ​

笔记还提到可用 vue-cli 创建项目。转写稿说明：CLI 方式可用 VS Code 开发，但运行到手机/模拟器等能力不如 HBuilderX 集成方便；本次课程不采用该方式，因此不展开命令。原笔记此处保留了 CLI 创建入口的代码块：

bash

易错点：不要因为看到 CLI 方式就混用两套流程；本节统一用 HBuilderX 创建和运行。

运行到浏览器与微信小程序 ​

为什么需要：创建项目后必须验证工程是否能编译运行，同时直观看到 uni-app 的跨端效果。
怎么想：先跑浏览器端，因为最简单；再跑微信小程序，因为它需要额外配置微信开发者工具。
怎么做：在 HBuilderX 中点击“运行”，先运行到浏览器，等待编译完成会自动打开页面，切换到手机模式即可看 H5 效果。运行小程序前，要在项目 manifest 中填写微信小程序 AppID；打开微信开发者工具，在【设置】→【安全设置】中打开服务端口；再在 HBuilderX 选择运行到微信小程序，工具会自动编译并拉起微信开发者工具。若 HBuilderX 不能自动打开微信开发者工具，需要在 HBuilderX 中配置微信开发者工具的安装目录。
易错点：服务端口默认可能是关闭的，必须打开；端口号每个人可能不同，打开即可；HBuilderX 中红色提示不一定代表报错，转写稿特别提醒它有时只是重点提示；未填 AppID 可能进入游客模式。

Android 真机运行环境 ​

为什么需要：课程项目包含 App 端，最终要把应用跑到手机上验证。
怎么想：Android 建议优先用真机，调试和性能更直接；模拟器往往要装 Android Studio 并虚拟手机，占内存、易卡顿。苹果真机需要证书成本，课程环境以 Android 真机为主。
怎么做：首次在 HBuilderX 点“运行到手机或模拟器”，按提示下载真机运行插件；手机进入【设置】→【系统】→【关于手机】，连续点击“版本号”直到开启开发者模式；返回系统设置找到“开发者选项”，打开“USB 调试”；用支持数据传输的数据线连接电脑。若 HBuilderX 识别不到设备，运行群里的 ADB Driver Installer.exe，识别到设备后点 Install 安装驱动，然后重启 HBuilderX，再运行到 Android App。
易错点：数据线可能是充电线，无法传数据；没开 USB 调试或没装驱动会识别不到手机；装完驱动建议重启 HBuilderX；不同品牌手机界面略有差异，但“开发者选项”和“USB 调试”是关键。

小结与检查清单 ​

检查：HBuilderX 能否启动且不在中文目录；项目是否用默认模板、Vue3 创建；浏览器端是否运行成功；微信开发者工具服务端口是否打开、AppID 是否填写；Android 手机是否开启开发者选项和 USB 调试、驱动是否安装、HBuilderX 是否识别到设备。按转写稿建议，出错就从头复核步骤，直到环境正常运行。

先建立整体认识：Vue 语法 + 小程序能力 ​

为什么需要：uni-app 组合了 Vue 和微信小程序的相关技术，学习前要同时具备 Vue 与原生小程序基础。怎么想：把全局文件对应到小程序的 app.js/app.wxss/app.json，把组件、API、生命周期对应到小程序能力，同时用 Vue 的模板与组件写法开发。怎么做：用 HBuilderX 新建 uni-app 项目，模板选默认、Vue 版本选 Vue3；先运行到浏览器看 H5，再运行到微信小程序，最后配置真机运行 App。易错点：创建项目时不要选错模板和 Vue 版本；转写稿里的“神领物流”“HBuilderX”“VS Code”“AppID”等同音字要按正确名称理解。

uni.scss：统一全局样式变量 ​

为什么需要：页面主色调、边框圆角等样式如果分散写，后期难统一。怎么想：uni-app 运行时会自动把 uni.scss 注入页面样式，所以可在这里定义全局 SASS 变量。怎么做：在原有 SASS 变量基础上追加变量，例如：

css
/* uni.scss */
/* 在原有 sass 变量基础上添加新的变量 */
$uni-bg-color: #f4f4f4;

易错点：变量要在支持 SCSS 的样式环境中使用；不要误以为它等同于普通 CSS 全局类。

App.vue：应用入口与全局样式 ​

为什么需要：应用启动、显示、隐藏等全局逻辑，以及页面全局背景色，需要一个统一入口。怎么想：App.vue 是特殊文件：script 相当于小程序 app.js，style 相当于 app.wxss，template 必须省略。怎么做：

html
<script>
  // 相当于小程序的 app.js
  export default {
    onLaunch: function () {
      console.log('App Launch')
    },
    onShow: function () {
      console.log('App Show')
    },
    onHide: function () {
      console.log('App Hide')
    },
  }
</script>

<!-- 组件模板需要被省略 -->
<template></template>
<!-- 组件模板需要被省略 -->

<style>
  /* 相当于 app.wxss */
  page {
    background-color: $uni-bg-color;
  }
</style>

为其指定 lang="scss" 后，会自动安装 dart-sass 插件。dart-sass 插件自动安装提示易错点：template 不要写实际页面结构；使用 $uni-bg-color 时样式需具备 SCSS 处理能力。

pages.json：页面配置与全局配置 ​

为什么需要：项目要有页面路径、导航栏、背景色、tabBar、分包等配置。怎么想：pages 是页面配置，globalStyle 对应全局 window；其他全局配置如 tabBar、subPackages 与 globalStyle 平级。怎么做：

json
{
	"pages": [
		{
			"path": "pages/index/index",
			"style": {
				"navigationBarTitleText": "学习uni-app"
			}
		}
	],
	"globalStyle": {
		"navigationBarTextStyle": "black",
		"navigationBarTitleText": "uni-app",
		"navigationBarBackgroundColor": "#F8F8F8",
		"backgroundColor": "#F8F8F8"
	},
	"uniIdRouter": {}
}

tabBar 与 subPackages 也按平级方式配置。易错点：tabBar 的图片必须放到 static 目录下，否则小程序中无法运行；页面 path 要真实存在。

组件：内置组件与扩展组件 ​

为什么需要：跨端开发要尽量保证组件表现一致。怎么想：内置组件参照微信小程序内置组件使用；扩展组件（uni ui）多用于倒计时、日历、文件上传等业务交互，需要下载到项目目录。怎么做：

xml
<view class="message">hello uni-app!</view>
<image src="" mode="" />
<swiper autoplay>
  <swiper-item>
  	<image src="" />
  </swiper-item>
  <swiper-item>
  	<image src="" />
  </swiper-item>
<swiper>

uni ui 扩展组件易错点：扩展组件不是默认全部可用，需按文档下载引入；笔记提示 uView 不支持 Vue3。

生命周期：应用/页面用小程序，组件用 Vue ​

为什么需要：应用、页面、组件职责不同，生命周期不能混用。怎么想：记原则——应用生命周期和页面生命周期采用小程序生命周期，自定义组件生命周期使用 Vue 生命周期。Vue3 setup 中，应用/页面生命周期从 @dcloudio/uni-app 导入，Vue 生命周期从 vue 导入。怎么做：

html
<script setup>
  // Vue 组件生命周期
  import { onMounted } from 'vue'
  // 应用/页面生命周期（小程序生命周期）
  import { onLaunch, onLoad } from '@dcloudio/uni-app'
  
  // ...
</script>

易错点：笔记表格中 onLauch 是拼写笔误，代码中应写 onLaunch；activated/deactivated 仅 H5 可用，不要当作全端通用。

API 调用：命名空间与 Promise ​

为什么需要：小程序 API 多以 wx. 开头，uni-app 要跨端统一。怎么想：把 wx.request 换成 uni.request；传了 success/fail/complete 任意回调就是 callback 方式，不返回 Promise；不传回调则返回 Promise。怎么做：

html
<script setup>
  import { onLoad } from '@dcloudio/uni-app'
  
  // 页面加载后获取接口数据
  onLoad(() => {
    // 原来的 wx.request 换成 uni.request
    uni.request({
      url: '',
      success(result) {
        console.log(result)
      }
    })
  })
</script>
javascript
// 回调方式，不返回 Promise
uni.request({
  url: 'https://your.api.com/xxx',
  success: (result) => {
    console.log(result)
  }
})

// 没有传入回调时返回 Promise
const result = uni.request({
  url: 'https://your.api.com/xxx'
})
console.log(result)

易错点：不要既写 success 又 await 返回值；H5 平台对部分 API 限制较多。

条件编译：处理平台差异 ​

为什么需要：一套代码跨端，但 uni.login 在 H5 不支持、keep-alive 只能用于 H5 等差异客观存在。怎么想：用特殊注释标记，让代码只在指定平台编译。怎么做：

html
<script setup>
  // #ifdef H5
  console.log('这段代码只在 H5 端才会运行')
  // #endif
</script>
<template>
  <!-- #ifdef H5 -->
  <view class="iconfont icon-search"></view>
  <!-- #endif -->
  
  <!-- #ifndef H5 -->
  <view class="iconfont icon-scan"></view>
  <!-- #endif -->
</template>
<style lang="scss" scoped>
  .iconfont {
    color: #666;
    font-size: 30rpx;
    /* #ifdef H5 */
    font-size: 28rpx;
    /* #endif */
  }
</style>

平台名包括 H5、MP-WEIXIN、APP-PLUS 等。易错点：注释位置要符合 script/template/style 各自语法；平台名称不要随意改写。

运行与调试：H5、小程序、真机 ​

为什么需要：uni-app 的价值是跨端，必须实际跑通。怎么想：HBuilderX 点“运行”可到浏览器；到微信小程序前，要先在微信开发者工具“设置→安全设置”打开服务端口，并在项目配置中填 AppID；真机运行要下载真机运行插件。怎么做：手机开启“开发者选项”和“USB 调试”，连接电脑；识别不到设备时换支持数据传输的数据线，必要时用 ADBDriverInstaller 安装驱动后重启 HBuilderX。易错点：转写稿里“manf”指项目配置文件 manifest.json；红色提示不一定是报错，要结合 HBuilderX 提示判断。

代码示例 ​

示例一：全局文件 —— uni.scss 与 App.vue ​

css
/* uni.scss */
/* 在原有 sass 变量基础上添加新的变量 */
$uni-bg-color: #f4f4f4;
html
<!-- App.vue -->
<script>
  // 相当于小程序的 app.js
  export default {
    onLaunch: function () {
      console.log('App Launch')
    },
    onShow: function () {
      console.log('App Show')
    },
    onHide: function () {
      console.log('App Hide')
    },
  }
</script>

<!-- 组件模板需要被省略 -->
<template></template>
<!-- 组件模板需要被省略 -->

<style>
  /* 相当于 app.wxss */
  page {
    background-color: $uni-bg-color;
  }
</style>

要点解释

  • uni.scss 会在运行时被自动注入到每个页面的样式中，因此适合放主色调、圆角这类全局 SASS 变量；上例新增了 $uni-bg-color，在任意页面都能直接引用。
  • App.vue 的 script 相当于小程序的 app.js，只能写应用级生命周期（onLaunch / onShow / onHide）。
  • 易错点 1：App.vue 的 <template></template> 必须保留但内容为空，不要在这里写页面结构。
  • 易错点 2：style 中若要用 SASS 变量，需给标签加 lang="scss"，此时 HBuilder X 会自动安装 dart-sass 插件；不加 lang 直接写变量会报错。
  • 易错点 3：page { } 选择器作用于全局页面容器，等价于小程序的 app.wxss，写在这里的样式会影响所有页面。

示例二：pages.json —— 页面配置 + 全局配置 + tabBar / 分包 ​

json
{
	"pages": [
		{
			"path": "pages/index/index",
			"style": {
				"navigationBarTitleText": "学习uni-app"
			}
		}
	],
	"globalStyle": {
		"navigationBarTextStyle": "black",
		"navigationBarTitleText": "uni-app",
		"navigationBarBackgroundColor": "#F8F8F8",
		"backgroundColor": "#F8F8F8"
	},
	"tabBar": {
		"color": "",
		"selectedColor": "",
		"borderStyle": "",
		"position": "",
		"list": [
			{
				"text": "",
				"pagePath": "",
				"iconPath": "",
				"selectedIconPath": ""
			}
		]
	},
	"subPackages": [
		{
			"root": "",
			"pages": [
				{
					"path": "",
					"style": {}
				}
			]
		}
	],
	"uniIdRouter": {}
}

要点解释

  • pages 数组对应【页面配置】：path 指定页面路径，style 是该页面的窗口配置（标题、背景色等）。数组第一项就是启动页。
  • globalStyle 对应小程序全局配置中的 window，用于全局统一导航栏与背景色。
  • 关键行：tabBar、subPackages 这些其它全局配置，都是与 globalStyle 平级书写，不是嵌套在 globalStyle 里——这是最常见的结构错误。
  • 易错点 1：tabBar 的 iconPath / selectedIconPath 图片必须放在 static 目录下，否则小程序端无法运行。
  • 易错点 2：tabBar.list 中的 pagePath 必须在 pages 数组里已注册过，否则点击报错。
  • 易错点 3：subPackages 中 root 是分包根目录，其下 pages 的 path 只写相对 root 的路径。

示例三：页面文件 —— 生命周期 + API 调用 + 条件编译 ​

html
<script setup>
  // Vue 组件生命周期
  import { onMounted } from 'vue'
  // 应用/页面生命周期（小程序生命周期）
  import { onLaunch, onLoad } from '@dcloudio/uni-app'

  // 页面加载后获取接口数据
  onLoad(() => {
    // 原来的 wx.request 换成 uni.request
    uni.request({
      url: 'https://your.api.com/xxx',
      success(result) {
        console.log(result)
      }
    })
  })

  // #ifdef H5
  console.log('这段代码只在 H5 端才会运行')
  // #endif
</script>

<template>
  <!-- #ifdef H5 -->
  <view class="iconfont icon-search"></view>
  <!-- #endif -->

  <!-- #ifndef H5 -->
  <view class="iconfont icon-scan"></view>
  <!-- #endif -->
</template>

<style lang="scss" scoped>
  .iconfont {
    color: #666;
    font-size: 30rpx;
    /* #ifdef H5 */
    font-size: 28rpx;
    /* #endif */
  }
</style>

要点解释

  • 关键行 1：onLoad 等页面生命周期必须从 @dcloudio/uni-app 引入，onMounted 等 Vue 生命周期从 vue 引入，两者来源不同，混用会直接报错。
  • 关键行 2：uni.request 中传入了 success 回调，因此这次调用走 callback 方式、不返回 Promise；只有不传 success / fail / complete 任意一个时，才返回 Promise，才能配合 async / await。
  • 关键行 3：条件编译标记是特殊注释，#ifdef H5 … #endif 之间的代码只编译进 H5 端；#ifndef H5 反之，即“除 H5 之外的所有平台”。
  • 易错点 1：onLaunch 属于应用级生命周期，只有写在 App.vue 中才生效，写在页面里不会触发（页面只支持 onLoad / onShow / onHide / onReady）。
  • 易错点 2：条件编译注释在 <template> 中要用 HTML 注释 <!-- #ifdef H5 -->，在 <script> / <style> 中要用对应语言的注释语法 // 或 /* */，注释符号写错则完全不生效。
  • 易错点 3：条件编译是编译期剔除代码，而不是运行期判断，因此被剔除的分支里即使有语法错误也不会影响其它平台，但也不要用它来做运行时分支逻辑。

常见错误 ​

  1. HBuilderX 启动异常或项目创建失败
    现象：双击无法启动、创建项目报错或后续编译异常。
    原因：HBuilderX 被解压/安装到中文目录或路径含特殊字符。
    修法：将 HBuilderX 移至纯英文、无空格目录后重新启动，并重新选择规范的项目目录。

  2. 运行到微信小程序时无法自动拉起开发者工具
    现象：HBuilderX 提示找不到微信开发者工具，或运行后无反应。
    原因：未配置微信开发者工具安装目录，或开发者工具“服务端口”未开启。
    修法：在 HBuilderX 中填写微信开发者工具安装目录（到目录层级，不带 .exe），并在微信开发者工具“设置→安全设置”中开启服务端口。

  3. 小程序运行时提示游客模式或 AppID 相关异常
    现象：微信开发者工具以游客模式运行，部分能力不可用。
    原因：manifest.json 中未填写微信小程序 AppID。
    修法：在 manifest.json 的微信小程序配置中填入 AppID，保存后重新运行到微信小程序。

  4. 运行到 Android 真机时 HBuilderX 看不到设备
    现象：点击“运行到手机或模拟器”后没有设备列表，或列表为空。
    原因：手机未开启开发者选项/USB 调试、数据线仅支持充电、ADB 驱动未安装。
    修法：连续点击版本号开启开发者选项，打开 USB 调试；更换可传输数据的数据线；使用 ADB Driver Installer 识别设备并安装驱动，重启 HBuilderX 后重试。

  5. 首次运行到 App 时没有“运行到 Android”选项
    现象：菜单中只提示下载真机运行插件，无法选择 Android 设备。
    原因：HBuilderX 尚未安装真机运行插件，或插件下载因网络失败。
    修法：按提示下载并安装真机运行插件；网络不稳定时重复尝试，必要时使用离线方式安装后再运行。

  6. 看到 HBuilderX 控制台红色信息就误判为报错
    现象：运行过程中出现红色提示，误以为项目失败并中断操作。
    原因：HBuilderX 会用红色突出部分提示信息，不一定代表错误。
    修法：结合提示内容和运行结果判断；若能正常编译并打开目标端，先继续验证页面是否正常运行。

练习 ​

  1. 使用 HBuilderX 创建一个 Vue3、默认模板的 uni-app 项目，项目目录放在纯英文路径下，并分别运行到 Chrome（H5）和微信小程序。
  2. 检查并配置微信开发者工具：开启服务端口，在 manifest.json 中填写微信小程序 AppID，然后重新运行到微信小程序，确认不再处于游客模式。
  3. 使用 Android 真机完成一次运行：开启开发者选项与 USB 调试，连接电脑，确保 HBuilderX 能识别设备后运行到 Android App。
  4. 故意制造一次“HBuilderX 看不到真机”的情况（如换用仅充电数据线或关闭 USB 调试），记录现象，再按“数据线→USB 调试→ADB 驱动→重启 HBuilderX”的顺序排查并恢复。
  5. 分别观察 H5、微信小程序、Android App 三端的运行结果，记录同一页面在三端启动方式和运行入口上的差异。

原视频对照 ​

#视频时长
1项目及课程介绍12:18
2HBuilderX安装03:17
3HBuilderX创建项目04:19
4HBuilderX运行项目13:04
5微信小程序运行问题03:07
6HBuilder真机运行环境-112:32
7HBuilder真机运行环境-202:36

小结 ​

  1. 环境搭建的核心不是记忆步骤，而是能独立完成“创建项目→运行 H5→运行小程序→运行真机”的闭环。
  2. HBuilderX 路径和项目路径要规范，优先使用纯英文、无特殊字符目录，能减少大量隐性问题。
  3. 微信小程序运行依赖两个关键配置：开发者工具服务端口开启、HBuilderX 正确填写开发者工具安装目录。
  4. AppID、真机运行插件、USB 调试、ADB 驱动和数据线质量，是 Android 真机运行的主要排查点。
  5. 运行到不同端时，失败原因通常来自“工具配置”和“设备连接”，应先按链路逐项排查，而不是反复改业务代码。
  6. 遇到红色提示先判断是否为错误信息；以目标端是否成功编译、页面是否正常打开作为最终判断依据。
  7. 练习时应保留每一步的操作结果和报错现象，形成可复用的排错顺序，这比单纯重复操作更有价值。