序言

本教程由「小荣的网络开发日志」实操整理编写，实操踩坑验证，内容真实可靠。

遇到操作问题可直接联系作者，转载需标注原文出处，禁止私自篡改商用。

承接网站、APP、小程序、各类脚本定制开发；

AI 编程教学、一对一项目全程陪跑，提供免费技术咨询。

联系方式：微信：rongyaolg 电话：18375295913

二、下载 HBuilderX

2.1 官方下载地址

HBuilderX 完全免费，请务必从官网下载，确保安全无毒。

官方地址：https://www.dcloud.io/hbuilderx.html

打开页面后，你会看到两个版本：

版本	说明	适合人群
正式版（推荐）	经过充分测试，稳定可靠	✅ 普通用户、学习者、项目开发
Alpha 版	尝鲜版，包含最新功能但可能有 Bug	想提前体验新功能的用户

✅ 推荐：选择正式版，稳定最重要。

2.2 选择对应系统的版本

页面会根据你的操作系统自动推荐对应版本：

系统	下载文件
Windows	`.zip` 压缩包（绿色版，解压即用）
macOS Intel 芯片	`.dmg` 安装包
macOS Apple 芯片（M1/M2/M3/M4）	`.dmg` 安装包
Linux	`.tar.gz` 压缩包

（此处插入图片：官网下载页面截图，箭头指向对应系统的下载按钮）

三、Windows 安装 HBuilderX

3.1 解压下载的文件

下载完成后，你得到一个 .zip 压缩包（例如 HBuilderX.zip）。
右键点击压缩包，选择「解压到当前文件夹」或「全部解压缩」。

⚠️ 注意：解压路径中不要包含中文字符！推荐直接解压到某个盘的根目录下，例如：
D:\HBuilderX

3.2 启动 HBuilderX

进入解压后的文件夹，找到 HBuilderX.exe。
双击运行。

四、macOS 安装 HBuilderX

4.1 安装步骤

下载完成后，你得到一个 .dmg 文件。
双击 .dmg 文件，会弹出一个安装窗口。
将 HBuilderX 图标拖动到右边的 Applications（应用程序） 文件夹中。
等待复制完成。

4.2 首次启动（重要）

打开 Launchpad 或在「应用程序」文件夹中，找到 HBuilderX，双击启动。

⚠️ macOS 安全提示处理：

双击 HBuilderX 后，macOS 可能会弹出以下提示：

"HBuilderX" 已损坏，无法打开。您应该将它移到废纸篓。

这不是真的损坏！ 是因为 macOS 的安全机制阻止了非 App Store 软件。解决方法：

# 打开终端（Terminal），执行以下命令：
sudo xattr -rd com.apple.quarantine /Applications/HBuilderX.app

输入电脑密码（屏幕不会显示，这是正常的），回车。然后重新打开 HBuilderX 即可。

💡 这行命令是什么意思？ macOS 会给从网上下载的软件打上一个"隔离"标签。xattr 命令就是去掉这个标签，让系统信任这个软件。

五、首次启动与界面介绍

5.1 欢迎界面

首次启动 HBuilderX，你会看到欢迎页面。这里可以快速创建项目、打开最近的项目。

5.2 界面布局介绍

HBuilderX 的主界面分为几个区域：

区域	位置	作用
工具栏	顶部	新建文件、运行项目、Git 操作等
项目管理器	左侧	显示当前项目的文件目录结构
代码编辑区	中间（最大区域）	写代码的地方
终端面板	底部	命令行操作、运行日志输出

六、创建第一个项目

6.1 什么是 uni-app

在创建项目之前，先了解一下 uni-app——它是 HBuilderX 最重要的搭档。

💡 uni-app 是一个前端框架，让你用写网页的技术（HTML、CSS、JavaScript/Vue）来开发小程序和手机 App。写一套代码，可以同时发布到微信小程序、支付宝小程序、H5 网页、iOS App、Android App 等十几个平台。

6.2 创建 uni-app 项目

点击顶部菜单「文件」→「新建」→「项目」（快捷键 Ctrl+N）。
在弹出的窗口中，进行以下配置：

选项	填写内容
项目类型	选择 uni-app
项目名称	填写你的项目名，如 `my-first-app`（英文，不要用中文）
模板	选择默认模板（适合新手）
路径	选择项目存放的文件夹

点击「创建」按钮。

HBuilderX 会自动帮你生成一个完整的 uni-app 项目结构。

6.3 项目目录结构解释

创建完成后，左侧项目管理器会显示项目的文件结构：

my-first-app/
├── pages/              ← 页面文件夹（每个页面放这里）
│   └── index/          ← 首页文件夹
│       └── index.vue   ← 首页代码
├── static/             ← 静态资源文件夹（图片、字体等）
├── App.vue             ← 应用入口文件
├── main.js             ← 主逻辑文件
├── manifest.json       ← 应用配置文件（App 名称、图标等）
├── pages.json          ← 页面路由配置
└── uni.scss            ← 全局样式文件

💡 不用慌张，刚开始只需要关注 pages/ 文件夹，你的大部分开发工作都在这里。

七、运行项目到浏览器（H5）

7.1 运行步骤

这是最快看到效果的方式，不需要任何额外安装。

确保你的项目在 HBuilderX 中已打开。
点击顶部工具栏「运行」→「运行到浏览器」→ 选择你的浏览器（如 Chrome）
HBuilderX 会自动编译项目，然后在浏览器中打开一个网页。

如果你看到浏览器中出现一个页面，说明项目运行成功！

八、运行项目到微信小程序

8.1 前提准备

要把项目跑在微信小程序中，你需要提前安装好以下工具：

工具	说明
✅ 微信开发者工具	微信官方提供的小程序开发和预览工具
✅ 微信小程序 AppID	在微信公众平台注册获取

如果你还没有安装微信开发者工具，请访问官方地址下载学习并安装：微信开发者工具 — 安装和使用教程

8.2 配置微信开发者工具路径

在 HBuilderX 中，点击顶部菜单「工具」→「设置」。
在设置界面左侧选择「运行配置」。
找到「微信开发者工具路径」，点击右侧的「浏览」按钮。
找到你安装的微信开发者工具的 .exe 文件：
- Windows：通常在 C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat 或直接选择安装目录下的 cli.bat
- macOS：通常在 /Applications/wechatwebdevtools.app → 右键选择「显示包内容」，路径一般为 /Applications/wechatwebdevtools.app/Contents/MacOS/cli

（此处插入图片：HBuilderX 设置中配置微信开发者工具路径截图）

8.3 开启微信开发者工具的服务端口

这一步很重要，如果不做，HBuilderX 无法自动打开微信开发者工具。

打开微信开发者工具。
点击顶部菜单「设置」→「安全设置」。
找到「服务端口」，点击「开启」。

8.4 获取微信小程序 AppID

访问微信公众平台：

官方地址：https://mp.weixin.qq.com

注册或登录你的小程序账号。
在左侧菜单「开发」→「开发管理」→「开发设置」中，找到你的 AppID。

⚠️ 没有 AppID 也可以开发和预览，但无法使用微信登录、微信支付等功能。测试阶段可以先用测试号。

8.5 运行到微信小程序

在 HBuilderX 中，点击顶部工具栏「运行」→「运行到小程序模拟器」→「微信开发者工具」。
等待编译完成后，微信开发者工具会自动打开，你可以在里面看到小程序运行效果。
如果你有 AppID，在项目 manifest.json 中填入你的小程序 AppID。

打开 manifest.json → 找到「微信小程序配置」→ 填入 AppID。

九、总结

恭喜你完成了 HBuilderX 的安装和第一个项目的运行！来回顾一下：

步骤	做了什么	为什么
了解 HBuilderX	知道它是什么、能做什么	确认这是你需要的开发工具
下载安装	从官网下载对应版本并安装	获得安全、最新版本的开发工具
创建项目	用 uni-app 模板创建了第一个项目	拥有了一套完整的项目骨架
运行到浏览器	在浏览器中看到了你的项目	验证项目可以正常运行
运行到小程序	在微信开发者工具中预览	体验了跨端开发的能力

版权声明：本教程由「小荣的网络开发日志」原创整理，免费分享。转载需标注原文出处，禁止私自篡改商用。

最后更新时间：2025 年 6 月

适用版本：HBuilderX 正式版（支持 Windows / macOS / Linux）

HBuilderX 安装与使用教程（Windows / macOS）

序言