前言

在 UniApp 课程的项目基础搭建章节，HBuilderX 是官方指定唯一开发工具，内置编译器、模拟器、多端打包、云开发全套能力，不用手动配置 Node、Vue 环境，零基础学员也能快速完成跨端项目初始化。下面按照课程实操步骤，完整拆解安装、全局配置、多端联动调试的全流程。

一、HBuilderX 下载与安装（课程第一步实操）

1. 官方下载渠道（课程推荐，无捆绑）

打开 DCloud 官方网站：https://www.dcloud.io/hbuilderx.html 提供两个版本，课程区分选择：

1. 标准版（推荐学生使用）：体积小，基础 UniApp 开发全部够用，适合课堂作业、实训小程序；
2. App 开发版：内置 Android 模拟器、原生打包环境，需要开发安卓 /iOS APP 的实训项目选择。

课程提示：Windows/Mac 系统安装包分开下载，不要混用。

2. Windows 系统安装步骤

1. 下载 .zip 绿色压缩包，无需安装程序，直接解压（课程重点：不要解压到中文路径！如 D:/软件/HBuilderX 错误，D:/dev/HBuilderX 正确）；
2. 解压完成后，找到根目录 HBuilderX.exe，右键「发送到桌面快捷方式」；
3. 首次右键打开软件，选择「以管理员身份运行」，避免后续模拟器、文件读写权限报错。

3. Mac 系统安装步骤

1. 下载 .dmg 镜像文件，双击挂载；
2. 将 HBuilderX 图标拖拽到「应用程序」文件夹；
3. 启动时若弹出 “无法验证开发者”，打开「系统设置 - 安全性与隐私」，点击「仍要打开」即可。

4. 课程必做校验：首次启动验证

打开软件后，顶部菜单栏点击「帮助 - 关于 HBuilderX」，确认版本号≥3.8+，过低版本会缺少 UniApp3、uniCloud 新特性，课堂项目会出现兼容 bug。

---

二、UniApp 核心插件安装（课程基础配置核心环节）

刚安装的 HBuilderX 不自带 UniApp 开发插件，这是课堂最容易踩坑的步骤，按照课程顺序安装：

1. 顶部菜单：「工具 → 插件安装」，打开插件市场；
2. 在搜索框分别安装以下 3 个课程必备插件：
   1. uni-app 编译：核心编译插件，用于将 Vue 代码转译成小程序、H5、APP 代码；
   2. App 模拟器：可视化手机模拟器，实时预览页面效果，不用真机；
   3. uniCloud 云开发：实训后台、数据库操作必备插件。
3. 安装完成后重启 HBuilderX，插件生效。

补充可选插件（课程拓展内容）

• scss/sass 编译：全局样式、uni.scss 样式文件编译；
• 微信开发者工具集成：一键唤起小程序调试工具；
• 代码提示增强：Vue、uni 内置 API 智能补全。

---

三、全局基础环境配置（课程统一标准配置）

1. 字体、代码格式化配置

1. 打开「工具 → 设置 → 编辑器设置」；
2. 课程统一规范：
   • 字体：微软雅黑 / Menlo，字号 14；
   • 缩进：2 个空格（UniApp 官方规范，所有课堂作业强制统一）；
   • 保存自动格式化：勾选「保存时自动格式化代码」，统一团队代码风格。

2. 浏览器运行配置（H5 端调试）

1. 设置页面搜索「运行配置」；
2. 配置外部浏览器路径：Chrome/Edge 安装路径，后续点击「运行到浏览器」可直接打开 H5 页面；
3. 勾选「启动调试控制台」，方便打印日志排查报错。

3. 全局 uni.scss 样式预设

「文件 → 新建 → uni.scss」，课程统一预设基础全局样式，统一多端页面字体、边距，避免每个页面重复写样式。

1. 创建文件：`文件 → 新建 → uni.scss`  
2. 预设全局样式：包括字体、边距等基础配置  
3. 引用文件：在页面中直接调用预设样式，避免重复编写  
 

/* uni.scss 示例 */  
$base-font: 14px "PingFang SC", sans-serif;  
$page-padding: 20rpx;  
body { font: $base-font; margin: $page-padding; }  
 

---

四、多端联动工具配置（课程实训核心配置）

UniApp 一套代码要编译小程序、APP、H5，需要联动对应官方工具，课堂分三类配置教学：

配置 1：微信开发者工具（小程序调试必考）

1. 提前下载安装「微信开发者工具」，登录小程序账号；
2. 打开 HBuilderX「工具 → 设置 → 运行配置」，找到「微信开发者工具路径」；
3. 选择微信工具安装目录下的 cli.bat（Windows）/ cli（Mac）；
4. 关键一步：打开微信开发者工具，「设置 → 安全设置」，开启「服务端口」，否则 HBuilder 无法自动编译预览小程序；
5. 课堂实操验证：新建 uni-app 项目，点击顶部「运行 → 运行到微信开发者工具」，自动唤起工具并预览页面。

配置 2：APP 模拟器配置（安卓 APP 实训）

1. 安装 App 开发版 HBuilderX，插件市场安装「App 模拟器」；
2. 菜单「运行 → 运行到 App 模拟器」，自动启动内置安卓虚拟手机；
3. 课程常用调试：切换模拟器手机尺寸（4.7 寸 / 6.7 寸），查看页面 rpx 自适应效果。

配置 3：真机调试配置（课堂实操加分项）

1. 安卓手机：开启「开发者选项 - USB 调试」，数据线连接电脑；
2. Mac 连接 iPhone：安装 iTunes 驱动，开启设备信任；
3. HBuilder 点击「运行到手机 / 真机」，实时在物理手机预览页面，测试拍照、定位等设备 API。

---

五、创建第一个 UniApp 项目（配置验收实操）

全部环境配置完成后，用课堂示例项目校验环境是否正常：

1. 顶部菜单「文件 → 新建 → 项目」；
2. 项目类型选择 uni-app，模板勾选「默认模板（uni3）」；
3. 项目名称、存放路径禁止中文，点击创建；
4. 项目创建成功后，左侧目录出现标准 pages、static、components 文件夹，代表环境全部配置完成；
5. 课堂验证操作：打开 pages/index/index.vue，修改页面文字，运行到模拟器 / 浏览器，查看页面实时刷新，即安装配置全部生效。

---

六、课程高频配置踩坑汇总

1. 解压路径含中文：插件失效、项目编译报错，解决：全部使用纯英文路径；
2. 微信工具未开启服务端口：无法自动预览小程序，报错 “连接失败”；
3. 未安装 uni-app 编译插件：新建项目无运行菜单；
4. 缩进使用 4 个空格：课堂作业会判定格式不规范，统一改为 2 空格；
5. 低版本 HBuilderX：不支持 Vue3 语法、分包加载等课程知识点，必须升级 3.8 以上版本。