一、前期准备：HBuilderX安装与配置
1. 工具下载（官方正版，无额外捆绑）
打开HBuilderX官网：www.dcloud.io/hbuilderx.h…，Win11 64位系统优先选择 Windows 64位 App开发版，该版本内置uni-app全套编译环境，无需额外配置Node.js，开箱即用。
可选安装方式：
- 安装版：双击安装包，按指引下一步，安装路径建议选择非C盘（如D:\HBuilderX），避免权限问题；
- 免安装版：下载压缩包后直接解压，双击HBuilderX.exe即可启动，无需安装。
2. 首次启动配置
- 启动软件后，登录DCloud账号（免费注册，用于后续真机调试、云打包）；
- 软件会自动检测缺失插件，首次打开uni-app项目时，按需自动安装编译器，无需手动单独下载；
- 关闭不必要的弹窗，保留核心编辑区与项目目录区即可。
⚠️ 新手注意：项目保存路径、软件安装路径，禁止出现中文、空格、特殊字符，否则会导致编译报错、运行失败。
二、新建uni-app项目（核心步骤）
1. 打开项目创建窗口
点击HBuilderX顶部菜单栏：文件 → 新建 → 项目，进入项目创建界面。
2. 项目参数设置
-
左侧项目类型：务必选择 uni-app，切勿选错成5+App、Wap2App；
-
项目名称：自定义，建议用英文、数字、下划线组合，不要用中文；
-
保存路径：选择纯英文无特殊字符的本地文件夹，切记避开中文路径；
-
启用uniCloud：新手前期纯前端开发，取消勾选，后续需要后端云服务再开启；
-
模板选择（新手必看）：
- 默认模板：空白项目，适合从零开始手写代码，轻量化无冗余；
- Hello uni-app：官方示例项目，包含各类组件、API演示，适合学习上手；
- uni-ui项目模板：内置常用UI组件，适合直接开发业务项目，效率更高；
- Hello uvue：uni-app x原生渲染模板，性能更强，适合进阶开发。
3. 完成项目创建
确认所有参数无误后，点击右下角创建，等待几秒，项目目录自动生成，即可进入开发阶段。
三、项目核心目录说明（新手快速看懂）
| 文件/文件夹 | 核心作用 |
|---|---|
| pages | 存放所有页面文件（.vue格式），所有业务页面都在此新建 |
| static | 存放静态资源，如图片、字体、音频等 |
| pages.json | 页面路由配置、导航栏、tabBar样式设置 |
| manifest.json | 应用全局配置，包含AppID、权限、多端发布配置 |
| main.js | 项目入口文件，全局逻辑、插件挂载 |
四、项目运行（多端调试）
1. 运行到浏览器（快速调试）
- 选中项目根目录，或打开任意pages下的vue页面；
- 点击顶部菜单栏：运行 → 运行到浏览器 → 选择Chrome/默认浏览器；
- 等待编译完成，浏览器自动打开项目页面，代码保存后自动热更新，无需手动刷新。
2. 运行到Android真机（实操调试）
- 手机用数据线连接电脑，开启USB调试（设置→关于手机→连续点击版本号开启开发者模式，返回设置打开开发者选项→开启USB调试）；
- 手机弹出USB调试授权，点击允许；
- HBuilderX顶部：运行 → 运行到手机或模拟器；
- 在设备列表中选中自己的手机，点击运行，首次会自动安装调试基座；
- 安装完成后，手机自动打开项目，支持热更新调试。
3. 运行到小程序（以微信为例）
- 安装微信开发者工具，登录并开启服务端口；
- HBuilderX中：运行 → 运行到小程序模拟器 → 微信开发者工具；
- 首次运行需配置微信开发者工具安装路径，配置后自动跳转调试。
五、新手常见问题与避坑指南
- 编译报错、页面无法打开：优先检查项目路径是否含中文、特殊字符，修改路径后重新创建；
- 真机无法识别：检查USB调试是否开启、数据线是否正常、手机驱动是否安装，重新插拔数据线；
- 插件缺失报错：点击顶部工具 → 插件安装，搜索uni-app编译器，手动安装重启；
- 页面不显示：检查pages.json中路由配置是否正确，页面路径是否匹配。
六、新建页面基础操作
- 在pages文件夹下，新建文件夹（对应页面名称）；
- 右键文件夹 → 新建 → vue文件，选择简单模板（新手首选，自带标准页面结构）；
- 打开pages.json，在pages数组中注册新建页面，配置页面路由与导航栏标题；
- 保存配置，重新运行项目，即可访问新建页面。
