一篇搞定：零基础也能5分钟跑起第一个HBuilderX项目（含uni-app、Vue3、TS、原生小程序全流程示例）
一、HBuilderX 是什么？
| 定位 | 亮点 |
|---|---|
| 国产「前端·全端」IDE | 一套代码编到 6 端（H5、小程序、App、iOS、Android、桌面） |
| uni-app 官方唯一指定工具 | 内置语法提示、云端打包、真机调试、插件市场 |
| 轻量极速 | 安装包 < 200 MB，冷启动 < 2 s，VS Code 同款 Monaco 内核 |
二、下载与安装（1 分钟）
1. 下载
https://www.dcloud.io/hbuilderx.html
选择对应平台（Windows、macOS、Linux）→ 标准版（无需登录即可用）
2. 安装
- Windows：解压后双击
HBuilderX.exe→ 可选“发送到桌面快捷方式” - macOS：拖入 Applications 即可
- Linux：解压后运行
HBuilderX/hbuilderx
绿色版，不写注册表，删文件夹即卸载
三、第一次启动（30 秒）
- 打开 IDE → 欢迎页 → 勾选 “不再提示” → 进入主界面
- 底部 “终端” 内置 node、npm、git，无需额外配置
四、创建第一个项目（2 分钟）
➤ 场景 A：uni-app（Vue3 + TS）—— 一次编译，全端发布
- 菜单 文件 → 新建 → 项目
- 左侧选 uni-app → 填写：
- 项目名称：
hello-uni - 模板：uni-app(Vue3 + TS)（默认带 pinia、uni-ui）
- 保存路径：任意
- 项目名称：
- 点击 创建 → 自动生成目录结构：
hello-uni
├─ pages/index/index.vue // 首页
├─ manifest.json // 跨端配置
├─ pages.json // 路由+导航条
└─ uni.scss // 公共样式
- 运行
- Web：顶部工具栏 → 运行 → 运行到浏览器
- 小程序：运行 → 运行到小程序模拟器（自动检测微信开发者工具）
- 真机 App：手机开 USB 调试 → 运行 → 真机运行 → 自动装基座 & 热更新
➤ 场景 B：原生微信小程序——不依赖 uni-app
- 文件 → 新建 → 项目 → 原生小程序
- 目录指向微信开发者工具的空项目 → 自动生成
app.json/pages/index/index.wxml - 顶部 “运行” → “运行到小程序模拟器” → 实时同步代码
➤ 场景 C：纯 H5 / Vue3 项目——轻量脚手架
- 文件 → 新建 → 项目 → 普通项目 → Vue3
- 内置 Vite 模板，终端执行
npm i→npm run dev即可|新视讯
五、必装插件 & 主题（30 秒）
| 插件 | 作用 | 安装路径 |
|---|---|---|
| uni-app 编译器 | 发行打包 | 工具 → 插件安装 → 搜索 |
| Prettier | 保存即格式化 | 同上 |
| GitLens | 行级 blame | 同上 |
| Material Theme | 护眼配色 | 工具 → 主题 |
六、常用快捷键（10 条记住够用）
| Win / macOS | 功能 |
|---|---|
Ctrl + P / ⌘ + P |
快速打开文件 |
Alt + Click |
多光标 |
Ctrl + Shift + F |
全局搜索 |
Ctrl + \ |
左右分栏 |
Ctrl + R |
运行到浏览器 |
Ctrl + Alt + R |
重新运行 |
Ctrl + Shift + S |
发行（打包） |
七、发行与打包（1 分钟）
1. H5 站点
顶部 发行 → 网站-PC Web 或手机 H5 → 生成 dist/build/h5/ 静态文件 → 丢到 Nginx/Apache 即可|OpenSpeedy
2. 小程序
发行 → 小程序-微信 → 自动打开微信开发者工具 → 点击「上传」即可提交体验版|Byrutor
3. App（Android 示例）
- 注册 dcloud 账号（免费）
- 左侧 manifest.json → 填写应用名称、包名
- 发行 → 原生 App-云打包 → 选「公共测试证书」→ 5 分钟后下载
.apk
iOS 需 Mac + Xcode，但步骤相同（生成 ipa）
八、调试技巧（真机 & 模拟器）
- 控制台：底部 Console → 支持
console.log/uni.request网络日志|SeedHub - 调试器：小程序 → 自动唤起微信 DevTools；App → 运行 → 调试模式 会在电脑端开 Chrome Inspector（与 Safari 一致）
- 热重载：默认开启，保存即刷新，状态保持（HMR）与 Vite 同级
九、常见问题 30 秒速查
| 问题 | 解决 |
|---|---|
| 找不到微信开发者工具 | 设置 → 运行设置 → 填入 cli 路径（微信安装目录/cli.bat） |
| Android 真机提示“未信任应用” | 手机 → 开发者选项 → 关闭“监控 ADB” |
| 云打包排队 | 免费版并发有限；本地装 Android Studio 可切「本地打包」 |
| ESLint 报错 | 插件市场装 eslint-plugin-vue，一键自动修复 |
十、1 分钟总结
- 下载 → 解压 → 打开，0 配置
- 新建 uni-app = Vue3 + TS，运行/发行一键直达 6 端
- 内置终端、Git、node，插件+主题随装随用
- 真机热重载 + 云打包，5 分钟完成从编码到上架
现在，打开 HBuilderX，创建你的第一个
hello-uni，F5 一键运行吧！
)
