HBuilder 的命令行功能主要通过 HBuilderX.exe (Windows) 或 HBuilderX (macOS) 的命令行参数来提供。

下面我将为您详细梳理 HBuilder 的常用命令行操作。

命令行基础

你需要知道如何从终端启动 HBuilder 并传递参数。

启动命令

在终端（如 Windows 的 CMD/PowerShell，或 macOS 的 Terminal）中，导航到 HBuilderX 的安装目录,然后执行：

Windows:

cd "C:\Program Files\HBuilderX"
HBuilderX.exe [命令] [参数]

macOS:

cd /Applications/HBuilderX.app/Contents/MacOS
./HBuilderX [命令] [参数]

查看帮助

如果你想查看所有可用的命令和参数，可以使用 --help 参数。

HBuilderX.exe --help

这会列出所有支持的命令及其简要说明。

核心开发命令

这些命令是日常开发中最常用的，用于创建、运行和调试项目。

创建项目

使用 create 命令可以快速创建一个新的项目。

语法:

HBuilderX.exe create -p <项目路径> -t <项目类型> [其他参数]

常用参数:

• -p, --path: (必需) 指定项目创建的目录路径。
• -t, --type: (必需) 指定项目类型。
  • uni-app: 创建 uni-app 项目。
  • vue: 创建 Vue 项目。
  • react: 创建 React 项目。
  • mp: 创建微信小程序项目。
  • h5: 创建纯 HTML5 项目。
  • plugin: 创建插件项目。
• --template: 指定项目模板，vue-ts (Vue + TypeScript), vue3-ts (Vue3 + TypeScript) 等。
• --name: 指定项目名称（如果路径中未包含）。

示例:

# 在 D:\my-projects 目录下创建一个名为 my-vue-app 的 Vue3 + TypeScript 项目
HBuilderX.exe create -p "D:\my-projects\my-vue-app" -t vue --template vue3-ts

运行项目

使用 run 命令可以在指定的设备或浏览器中运行项目。

语法:

HBuilderX.exe run -p <项目路径> -t <运行目标> [其他参数]

常用参数:

• -p, --path: (必需) 指定项目的根目录路径。
• -t, --target: (必需) 指定运行目标。
  • browser: 在浏览器中运行。
  • weixin: 在微信开发者工具中运行。
  • app: 运行到手机或模拟器（需要配置好运行基座）。
  • mp-alipay: 运行到支付宝小程序开发者工具。
  • mp-baidu: 运行到百度小程序开发者工具。
• --port: 指定本地服务端口（默认 8080）。
• --mode: 指定运行模式，如 development 或 production。

示例:

# 运行 D:\my-projects\my-uni-app 项目到浏览器
HBuilderX.exe run -p "D:\my-projects\my-uni-app" -t browser
# 运行到微信开发者工具
HBuilderX.exe run -p "D:\my-projects\my-uni-app" -t weixin

打包/发布项目

使用 build 命令可以将项目打包成不同平台的发布包。

语法:

HBuilderX.exe build -p <项目路径> -t <发布目标> [其他参数]

常用参数:

• -p, --path: (必需) 指定项目的根目录路径。
• -t, --target: (必需) 指定发布目标。
  • app: 打包成原生 App (需要云打包或本地打包配置)。
  • h5: 打包成 H5 网站。
  • mp-weixin: 打包成微信小程序。
  • mp-alipay: 打包成支付宝小程序。
  • uni: 打包成所有支持的 uni-app 平台。
• --output: 指定打包文件的输出目录。
• --env: 指定环境变量。

示例:

# 将 D:\my-projects\my-uni-app 项目打包成 H5 网站
HBuilderX.exe build -p "D:\my-projects\my-uni-app" -t h5
# 打包成微信小程序
HBuilderX.exe build -p "D:\my-projects\my-uni-app" -t mp-weixin

插件和扩展命令

安装/管理插件

HBuilderX 的插件系统也可以通过命令行进行管理，但这通常是通过 DCloud 官方的插件市场命令来间接实现的，而不是直接操作 HBuilderX.exe，你可以使用 cli 模块来执行一些插件相关的操作。

语法:

HBuilderX.exe cli [插件命令]

示例 (安装官方插件): 这个功能可能不是所有版本都支持，或者有特定的命令格式，通常更推荐使用 DCloud 提供的独立 CLI 工具，安装 uni-app 官方脚手架：

# 首先需要全局安装 @dcloudio/uni-cli-shared
npm install -g @dcloudio/uni-cli-shared
# 然后使用它来创建项目，这比直接用 HBuilderX 命令更灵活
# vue create -p dcloudio/uni-preset-vue my-project

高级和自动化命令

静态代码分析

使用 lint 命令可以对项目进行代码风格检查。

语法:

HBuilderX.exe lint -p <项目路径> [其他参数]

示例:

# 对 D:\my-projects\my-vue-app 项目进行 ESLint 检查
HBuilderX.exe lint -p "D:\my-projects\my-vue-app"

自定义脚本

HBuilderX 允许你在 package.json 中定义脚本，并让 HBuilderX 来执行它们,这对于构建流程的自动化非常有用。

在 package.json 中定义:

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "prebuild": "echo '准备开始构建...'",
    "build:h5": "HBuilderX build -p ./ -t h5",
    "build:mp": "HBuilderX build -p ./ -t mp-weixin"
  }
}

在终端中执行:

# 执行 package.json 中定义的 "build:h5" 脚本
# HBuilderX 会自动找到项目路径并执行对应的命令
npm run build:h5

或者直接调用：

HBuilderX.exe cli run-script build:h5

实战场景：CI/CD 集成

命令行最大的价值在于自动化，下面是一个在 GitHub Actions 中使用 HBuilderX 命令自动打包和部署的示例。

.github/workflows/deploy.yml 文件:

name: Deploy H5 to Pages
on:
  push:
    branches: [ main ]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v3
    # 安装 Node.js 和 pnpm
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'
        cache: 'pnpm'
    - name: Install pnpm
      run: npm install -g pnpm
    # 安装项目依赖
    - name: Install dependencies
      run: pnpm install
    # 下载并解压 HBuilderX (以 Linux 版本为例)
    - name: Setup HBuilderX
      run: |
        wget https://download.dcloud.net.cn/HBuilderX.3.6.4.20251025-linux-x86_64.tar.gz -O hbuilderx.tar.gz
        tar -xzf hbuilderx.tar.gz
        # 将 HBuilderX 添加到 PATH
        echo "$(pwd)/HBuilderX" >> $GITHUB_PATH
    # 使用 HBuilderX 命令打包 H5
    - name: Build H5 with HBuilderX
      run: HBuilderX build -p . -t h5 --output ./dist
    # 部署到 GitHub Pages
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist

在这个例子中，我们下载了 HBuilderX，然后在 CI 环境中使用它的 build 命令自动将项目打包成 H5，最后部署到 GitHub Pages。

总结表格

希望这份详细的指南能帮助你更好地利用 HBuilder 的命令行功能！