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

1 下载 HBuilderX

1.1 官方下载地址

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

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

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

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

1.2 选择对应系统的版本

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

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

2 Windows 安装 HBuilderX

2.1 解压下载的文件

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

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

复制D:\HBuilderX

2.2 启动 HBuilderX

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

3 macOS 安装 HBuilderX

3.1 安装步骤

1. 下载完成后，你得到一个 .dmg 文件。

2. 双击 .dmg 文件，会弹出一个安装窗口。

3. 将 HBuilderX 图标拖动到右边的 Applications（应用程序） 文件夹中。

4. 等待复制完成。

3.2 首次启动（重要）

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

⚠️ macOS 安全提示处理：

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

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

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

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

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

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

4 首次启动与界面介绍

4.1 欢迎界面

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

4.2 界面布局介绍

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

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

5 创建第一个项目

5.1 什么是 uni-app

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

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

5.2 创建 uni-app 项目

1. 点击顶部菜单「文件」→「新建」→「项目」（快捷键 Ctrl+N）。

2. 在弹出的窗口中，进行以下配置：

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

3. 点击「创建」按钮。

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

5.3 项目目录结构解释

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

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

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

6 运行项目到浏览器（H5）

6.1 运行步骤

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

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

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

7 运行项目到微信小程序

7.1 前提准备

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

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

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

1. 在 HBuilderX 中，点击顶部菜单「工具」→「设置」。

2. 在设置界面左侧选择「运行配置」。

3. 找到「微信开发者工具路径」，点击右侧的「浏览」按钮。

4. 找到你安装的微信开发者工具的 .exe 文件：

   • Windows：通常在 C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat 或直接选择安装目录下的 cli.bat
   • macOS：通常在 /Applications/wechatwebdevtools.app → 右键选择「显示包内容」，路径一般为 /Applications/wechatwebdevtools.app/Contents/MacOS/cli

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

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

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

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

7.4 获取微信小程序 AppID

1. 访问微信公众平台：

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

2. 注册或登录你的小程序账号。

3. 在左侧菜单「开发」→「开发管理」→「开发设置」中，找到你的 AppID。

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

7.5 运行到微信小程序

1. 在 HBuilderX 中，点击顶部工具栏「运行」→「运行到小程序模拟器」→「微信开发者工具」。

2. 等待编译完成后，微信开发者工具会自动打开，你可以在里面看到小程序运行效果。

3. 如果你有 AppID，在项目 manifest.json 中填入你的小程序 AppID。

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

8 总结

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

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

最后更新时间：2025 年 6 月

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