安装 HBuilderX 开发工具

下载 HBuilderX

HBuilderX 是 DCloud 官方推出的 uni-app 开发工具，支持 Windows、macOS 和 Linux 系统。首先需要从官网下载对应版本的安装包：

• 官网下载地址：https://www.dcloud.io/hbuilderx.html
• Windows 用户选择 .exe 安装包
• macOS 用户选择 .dmg 镜像文件
• Linux 用户选择 .AppImage 或 .deb 包

下载完成后，Windows 用户双击安装包按向导完成安装；macOS 用户将应用拖到 Applications 文件夹；Linux 用户给 AppImage 文件添加执行权限后直接运行。

初次启动配置

首次启动 HBuilderX 会提示进行初始化设置：

1. 选择主题风格（推荐「深色」保护眼睛）
2. 设置默认项目存放路径
3. 安装必要插件：
   • 必须安装「uni-app 编译」插件
   • 推荐安装「ESLint」、「Prettier」代码规范工具
4. 配置 node.js 路径（如果已安装）

# 检查 node.js 是否安装成功
node -v
npm -v

创建 uni-app 项目

通过顶部菜单创建新项目：

1. 文件 → 新建 → 项目
2. 选择「uni-app」项目类型
3. 填写项目名称和存储路径
4. 选择模板（推荐「默认模板」）
5. 点击创建按钮

项目目录结构说明：

├── pages         # 页面目录
│   └── index     # 首页
│       ├── index.vue
│       └── index.json
├── static        # 静态资源
├── App.vue       # 应用入口
└── manifest.json # 配置应用信息

运行和调试

HBuilderX 提供多种运行方式：

1. 浏览器运行：点击工具栏「运行」→「运行到浏览器」
2. 真机调试：
   • Android：连接手机开启 USB 调试
   • iOS：需要 macOS 系统
3. 模拟器运行：
   • 安卓模拟器推荐使用「夜神模拟器」
   • iOS 模拟器需要 Xcode

调试技巧：

• 使用 console.log() 输出日志
• 在「调试控制台」查看运行时信息
• 使用「元素审查」功能查看页面结构

// 示例：打印当前页面路由
onLoad() {
  console.log('当前页面路径：', this.$route.path)
}

常用功能配置

代码提示增强

1. 安装「Vetur」插件获得更好的 Vue 语法支持
2. 配置 jsconfig.json 实现路径别名提示：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

快捷键设置

推荐修改的快捷键配置（文件 → 首选项 → 快捷键）：

• 格式化文档：Ctrl+Alt+L
• 快速注释：Ctrl+/
• 重命名：F2

代码片段

创建自定义代码片段提高效率：

1. 工具 → 代码片段设置 → vue.json
2. 添加常用模板：

{
  "uni-page": {
    "prefix": "upage",
    "body": [
      "<template>",
      "  <view class=\"container\">",
      "    $1",
      "  </view>",
      "</template>",
      "",
      "<script>",
      "export default {",
      "  data() {",
      "    return {",
      "      $2",
      "    }",
      "  }",
      "}",
      "</script>",
      "",
      "<style scoped>",
      ".container {",
      "  padding: 20rpx;",
      "}",
      "</style>"
    ]
  }
}

项目打包发布

微信小程序打包

1. 配置 manifest.json 中的微信小程序 AppID
2. 运行 → 发行 → 微信小程序
3. 生成的 dist 目录用微信开发者工具打开

APP 打包

1. 需要配置证书（Android 为 keystore，iOS 为 p12）
2. 选择「原生 APP-云打包」
3. 等待 DCloud 服务器完成编译

// 示例：获取应用版本号
plus.runtime.getProperty(plus.runtime.appid, (info) => {
  console.log('当前版本：', info.version)
})

插件生态

HBuilderX 支持丰富的插件扩展：

1. UI 库插件：
   • uView UI
   • colorUI
2. 工具插件：
   • Git 版本控制
   • 代码美化
3. 调试插件：
   • 网络请求抓包
   • 性能分析器

安装方法：

• 工具 → 插件安装
• 搜索需要的插件点击安装
• 重启生效

性能优化技巧

1. 使用「运行时压缩」减少包体积
2. 配置「图片压缩」自动处理静态资源
3. 开启「摇树优化」移除未使用代码
4. 分包加载处理大型项目：

// manifest.json
{
  "optimization": {
    "subPackages": true
  }
}

问题排查

常见问题解决方法：

1. 无法识别 node_modules：

   • 删除项目下的 package-lock.json
   • 重新 npm install

2. 真机调试白屏：

   • 检查手机是否开启 USB 调试
   • 重新插拔数据线

3. 样式不生效：

   • 检查是否添加 scoped 属性
   • 使用深度选择器：

/* 穿透组件样式 */
::v-deep .custom-class {
  color: red;
}