hbuilderx-cli

name: hbuilderx-cli description: "Use HBuilderX CLI to deploy uniCloud cloud functions, upload frontend hosting files, manage projects, build uni-app applications, and package native Apps. USE FOR: deploying uni-ssr cloud function, uploading SSR client assets to frontend hosting, uploading/downloading cloud functions, managing cloud spaces, database schema operations, Android/iOS cloud packaging (APK/IPA), HarmonyOS local packaging (HAP), generating local appResource for offline builds, making wgt hot-update packages. Invokes terminal commands via HBuilderX CLI."

HBuilderX CLI Skill

通过 HBuilderX 命令行工具（CLI）自动化 uniCloud 云函数部署、前端网页托管上传、原生 App 打包（云打包/本地打包/wgt）等操作。

环境信息

• CLI 路径 (macOS 正式版): /Applications/HBuilderX.app/Contents/MacOS/cli
• CLI 路径 (macOS Alpha版): /Applications/HBuilderX-Alpha.app/Contents/MacOS/cli
• CLI 路径 (Windows): HBuilderX 安装目录下的 cli.exe
• CLI 路径 (Linux): HBuilderX 安装目录下的 cli
• 最低版本要求: HBuilderX 3.1.5+（uniCloud 操作需 3.1.9+）

前置条件

1. HBuilderX 必须处于启动状态（cli open）
2. 必须已登录 DCloud 账号（cli user info 检查）
3. 项目必须已导入到 HBuilderX（cli project list 检查）
4. uniCloud 前端网页托管需已开通

命令参考

以下所有命令中 cli 代表 CLI 可执行文件的完整路径。

基础操作

# 启动 HBuilderX
cli open

# 关闭 HBuilderX
cli app quit

# 查看 CLI 版本
cli ver

# 查看帮助
cli --help

用户操作

# 查看当前登录用户
cli user info

# 登录
cli user login --username <用户名> --password <密码>

# 退出登录
cli user logout

项目操作

# 列出所有已导入项目
cli project list

# 打开/导入项目
cli project open --path <项目绝对路径>

# 关闭项目
cli project close --path <项目绝对路径>

uniCloud 云函数操作

列举资源

cli cloud functions --list <资源类型> --prj <项目名称或序号> --provider <云服务商> [--unimod <uni_module名称>] [--cloud]

资源类型代号：

• cloudfunction — 云函数/云对象
• common — 公共模块
• db — 数据集合 Schema
• vf — 数据库校验函数
• action — 数据库触发条件
• space — 云空间

云服务商代号：

• aliyun — 阿里云
• tcb — 腾讯云

--cloud 参数：加上则列举云端资源，不加则列举本地资源。

# 列举项目关联的腾讯云空间
cli cloud functions --list space --prj website --provider tcb

# 列举本地云函数
cli cloud functions --list cloudfunction --prj website --provider tcb

# 列举云端云函数
cli cloud functions --list cloudfunction --prj website --provider tcb --cloud

上传资源

cli cloud functions --upload <资源类型> --prj <项目名称或序号> --provider <云服务商> --name <资源名称> [--unimod <uni_module名称>] [--force]

注意：当使用 CLI 云开发方式操作时，上传/下载默认使用“强制跳过”模式；如果目标已存在同名资源，CLI 会自动跳过。

⚠️ 关键警告：--upload 后面必须跟资源类型（如 cloudfunction）！如果省略资源类型，CLI 会返回 0:cloud functions:OK 但不会实际上传任何内容，也不会报错。这会导致云端一直运行旧版本代码而不自知。

正确验证方式：上传成功时会输出 正在上传云对象xxx... 和 云对象xxx上传完成 的日志。如果没有这些日志，说明上传没有执行。

• --force：强制覆盖，无提示
• 资源类型可以是 all（上传所有云函数、公共模块及 actions）
• 资源名称：上传云函数时为云函数目录名；上传 Schema 时为文件名（如 book.schema.json）；上传校验函数时为对应文件名

# 上传所有云函数
cli cloud functions --upload all --prj website --provider tcb

# 上传指定云函数（如 uni-ssr）
cli cloud functions --upload cloudfunction --prj website --provider tcb --name uni-ssr

# 上传 uni_modules 下的云函数
cli cloud functions --upload cloudfunction --prj website --provider tcb --name uni-ssr --unimod uni-ssr

# 上传公共模块
cli cloud functions --upload common --prj website --provider tcb --name <模块名>

# 上传 action 文件
cli cloud functions --upload action --prj website --provider tcb --name <action文件名>.js

# 上传数据库 Schema
cli cloud functions --upload db --prj website --provider tcb --name <schema文件名>.schema.json

# 上传数据库校验函数
cli cloud functions --upload vf --prj website --provider tcb --name <校验函数文件名>.js

# 强制覆盖上传
cli cloud functions --upload cloudfunction --prj website --provider tcb --name uni-ssr --force

下载资源

cli cloud functions --download <资源类型> --prj <项目名称或序号> --provider <云服务商> --name <资源名称> [--unimod <uni_module名称>] [--force]

注意：当使用 CLI 云开发方式操作时，上传/下载默认使用“强制跳过”模式；如果目标已存在同名资源，CLI 会自动跳过。

• 资源类型可以是 cloudfunction、common、db、vf、action 或 all
• all：下载所有云函数、公共模块及 actions，此时无需 --name
• --force：强制覆盖本地文件，无提示

# 下载所有云函数、公共模块及 actions
cli cloud functions --download all --prj website --provider tcb

# 下载指定云函数
cli cloud functions --download cloudfunction --prj website --provider tcb --name website-careers

# 下载 uni_modules 下的云函数
cli cloud functions --download cloudfunction --prj website --provider tcb --name uni-ssr --unimod uni-ssr

# 下载公共模块
cli cloud functions --download common --prj website --provider tcb --name <模块名>

# 下载 action 文件
cli cloud functions --download action --prj website --provider tcb --name <action文件名>.js

# 下载数据库 Schema
cli cloud functions --download db --prj website --provider tcb --name <schema文件名>.schema.json

# 下载数据库校验函数
cli cloud functions --download vf --prj website --provider tcb --name <校验函数文件名>.js

指定云空间

cli cloud functions --prj <项目名称或序号> --provider <云服务商> --assignspace <空间名称/id/序号>

# 按空间序号指定
cli cloud functions --prj website --provider tcb --assignspace 1

# 按空间 ID 指定
cli cloud functions --prj website --provider tcb --assignspace tcb-ehabi7a2zjmk5nn-3cs272684b04

# 按空间名称指定
cli cloud functions --prj website --provider tcb --assignspace lktop

初始化数据库

cli cloud functions --prj <项目名称或序号> --provider <云服务商> --initdatabase

# 初始化项目关联云空间中的数据库
cli cloud functions --prj website --provider tcb --initdatabase

前端网页托管操作

上传文件/目录

cli hosting deploy --provider <服务商> --space <空间名称或id> [--prj <项目名称>] [--source <源路径>] [--prefix <云端目录前缀>]

• 指定 --prj 时，--source 不填则上传项目根目录所有内容
• 不指定 --prj 时，--source 必须为文件或目录的绝对路径

# 上传整个项目到云端根目录
cli hosting deploy --provider tcb --space <空间名> --prj website --prefix /

# 上传指定目录到云端
cli hosting deploy --provider tcb --space <空间名> --source /path/to/dist/ --prefix /

# 上传到云端指定子目录
cli hosting deploy --provider tcb --space <空间名> --source /path/to/dist/ --prefix /ssr-assets/

# 上传单个文件
cli hosting deploy --provider tcb --space <空间名> --source /path/to/file.js --prefix /static/

单文件重命名注意事项：hosting deploy --source <单文件> 上传时会保留源文件的 basename。若你希望云端文件名不同于原文件名，不要只在心里拼目标 URL；应先在本地创建一个已重命名的副本，再上传该副本。

cp /path/to/original.hap /tmp/app-v1.2.3-20260516.hap
cli hosting deploy --provider tcb --space <空间名> --source /tmp/app-v1.2.3-20260516.hap --prefix /downloads/assets/

上传后验证：

1. 用 cli hosting list --provider <服务商> --space <空间名> --prefix <目录> 确认云端文件名实际是什么。
2. 再用 curl -I -L <直链URL> 校验是否返回 200 OK 与预期 Content-Length，避免把站点路由地址误当成原始文件直链。

列举云端文件

cli hosting list --provider <服务商> --space <空间名称或id> [--prefix <目录前缀>]

# 列出根目录
cli hosting list --provider tcb --space <空间名>

# 列出指定目录
cli hosting list --provider tcb --space <空间名> --prefix /ssr-assets/

删除云端文件

cli hosting delete --provider <服务商> --space <空间名称或id> --path <文件或文件夹路径>

注意：文件夹路径须以 / 结尾。

# 删除文件夹
cli hosting delete --provider tcb --space <空间名> --path /old-assets/

# 删除文件
cli hosting delete --provider tcb --space <空间名> --path /index.html

SSR 部署工作流

一步部署（推荐）

HBuilderX CLI 支持一条命令完成 SSR 编译 + 云函数上传 + 前端托管上传：

cli publish web --project <项目名称> --ssr true --webHosting true --provider tcb --spaceId <空间ID>

以 website 项目为例：

$CLI publish web --project website --ssr true --webHosting true --provider tcb --spaceId tcb-ehabi7a2zjmk5nn-3cs272684b04

此命令会自动：

1. 编译 SSR 产物
2. 上传 uni-ssr 云函数（部署到云端）
3. 上传客户端资源到前端网页托管

注意：此命令不适用于单独上传非 SSR 云函数（如 website-page-editor），非 SSR 云函数仍需用 cloud functions --upload cloudfunction 命令。

分步部署（手动控制）

以下是 uni-app SSR 项目（website）的完整部署流程，必须严格按顺序执行：

步骤 1：编译 SSR

cli publish web --project <项目绝对路径> --ssr true --webTitle "网站标题" --ssrProvider tcb

编译成功后会在 <项目>/unpackage/dist/build/web/ 下生成：

• client/ — 客户端资源（JS/CSS/图片等）
• server/ — 服务端渲染产物（entry-server.js 等）

步骤 2：复制 server 产物到云函数目录（关键！）

编译产物的 server/ 文件夹必须先覆盖到云函数的 server/ 目录，否则云函数运行的是旧版本代码。

# 删除云函数中的旧 server 目录，然后用编译产物覆盖
rm -rf <项目>/uni_modules/uni-ssr/uniCloud/cloudfunctions/uni-ssr/server/
cp -r <项目>/unpackage/dist/build/web/server/ <项目>/uni_modules/uni-ssr/uniCloud/cloudfunctions/uni-ssr/server/

以 website 项目为例：

PROJ=/Users/chester/Code/lktop/website
rm -rf "$PROJ/uni_modules/uni-ssr/uniCloud/cloudfunctions/uni-ssr/server/"
cp -r "$PROJ/unpackage/dist/build/web/server/" "$PROJ/uni_modules/uni-ssr/uniCloud/cloudfunctions/uni-ssr/server/"

步骤 3：上传 uni-ssr 云函数

cli cloud functions --upload cloudfunction --prj website --provider tcb --name uni-ssr --unimod uni-ssr --force

如果遇到 "当前函数处于Updating状态" 错误，等待 30-60 秒后重试。

步骤 4：上传客户端资源到前端网页托管

cli hosting deploy --provider tcb --space lktop --source <项目>/unpackage/dist/build/web/client/ --prefix /ssr-assets/

步骤 5：验证

部署完成后访问 SSR 域名验证是否正常工作。

快速部署脚本（完整流程）

# 设置变量
PROJ=/Users/chester/Code/lktop/website
CLI=/Applications/HBuilderX.app/Contents/MacOS/cli

# 1. 编译 SSR
$CLI publish web --project "$PROJ" --ssr true --webTitle "立可拓官网" --ssrProvider tcb

# 2. 复制 server 产物到云函数目录
rm -rf "$PROJ/uni_modules/uni-ssr/uniCloud/cloudfunctions/uni-ssr/server/"
cp -r "$PROJ/unpackage/dist/build/web/server/" "$PROJ/uni_modules/uni-ssr/uniCloud/cloudfunctions/uni-ssr/server/"

# 3. 上传云函数
$CLI cloud functions --upload cloudfunction --prj website --provider tcb --name uni-ssr --unimod uni-ssr --force

# 4. 上传客户端资源
$CLI hosting deploy --provider tcb --space lktop --source "$PROJ/unpackage/dist/build/web/client/" --prefix /ssr-assets/

App 打包

HBuilderX CLI 支持三种打包方式，产物不同：

Android/iOS 云打包（直接出 APK/IPA）

云打包将代码上传到 DCloud 服务器编译，成功后返回下载链接。这是唯一能通过 CLI 直接得到 APK/IPA 的方式。

需要 HBuilderX 3.1.5+。

命令行参数方式

cli pack --project <项目名称或绝对路径> --platform <android|ios> [选项]

通用参数：

Android 专用参数：

iOS 专用参数：

⚠️ CLI 读取 manifest.json 的 apple 节点，不是 ios.bundleIdentifier： 如果命令行未传 --ios.bundle，CLI 会从 manifest.json → plus.distribute.apple.appid 读取 Bundle ID。这是 minified 插件代码中确认的读取路径，与 setting.json 或 manifest.json 的 ios.bundleIdentifier 无关。如果报 Bundle ID(AppID)不能为空，优先在 manifest.json 中添加 "plus.distribute.apple" 节点：

"apple": {
    "appid": "com.example.app",
    "password": "证书密码",
    "p12": "/path/to/cert.p12",
    "mobileprovision": "/path/to/profile.mobileprovision"
}

⚠️ CLI 云打包依赖本地 manifest.json 完整配置：cli pack 从本地 manifest.json 的 app-plus.distribute.android 读取打包配置（包名、证书类型等）。如果项目只通过 HBuilderX GUI 配置过云打包，这些配置可能仅保存在 DCloud 云端项目设置中，而未写入本地 manifest.json，导致 CLI 因缺少必要配置而失败（症状：长时间无响应、云端队列阻塞、或静默退出）。

诊断方法：检查 manifest.json 中 app-plus.distribute.android 是否包含 packagename、androidpacktype 等字段。如果该节点只有 permissions/minSdkVersion，说明配置缺失。

修复方法：

1. 在 HBuilderX GUI 中重新执行一次云打包，确保「包名」「证书」等配置写入 manifest.json，或
2. 手动补全 manifest.json 的 app-plus.distribute.android 节点：

"android": {
    "packagename": "com.example.app",
    "androidpacktype": "1",
    "minSdkVersion": 21,
    "targetSdkVersion": 33,
    "permissions": [...]
}

其中 androidpacktype：0=自有证书、1=公共证书、2=老版证书、3=云端证书。使用自有证书时还需补充 certalias/certfile/certpassword/storePassword。即使 CLI 通过命令行参数传入了这些值，manifest.json 缺失基础节点仍可能导致打包流程异常。

使用示例：

# Android 云打包（自有证书）
cli pack --project /Users/chester/Code/lktop/app \
  --platform android \
  --safemode false \
  --android.packagename com.lktop.app \
  --android.androidpacktype 0 \
  --android.certalias <别名> \
  --android.certfile /path/to/keystore.jks \
  --android.certpassword <密码> \
  --android.storepassword <库密码>

# Android 云打包（公共证书，无需自有证书参数）
cli pack --project app --platform android --android.packagename com.lktop.app --android.androidpacktype 1

# iOS 云打包
cli pack --project /Users/chester/Code/lktop/app \
  --platform ios \
  --safemode false \
  --ios.bundle com.lktop.app \
  --ios.supporteddevice iPhone,iPad \
  --ios.profile /path/to/profile.mobileprovision \
  --ios.certfile /path/to/cert.p12 \
  --ios.certpassword <密码>

# 同时打 Android + iOS
cli pack --project app --platform android,ios ...

打包成功后会输出下载链接（临时地址，只能下载 5 次）。安心打包模式会输出本地路径。

配置文件方式

可将所有参数写入 JSON 配置文件，避免命令行过长：

cli pack --config /path/to/pack-config.json

配置文件格式（UTF-8 编码）。CLI 自动化场景强烈建议 safemode: true——安心打包绕过队列交互，是唯一经过实测验证可靠的 CLI 云打包模式：

{
    "project": "app",
    "platform": "ios,android",
    "iscustom": false,
    "safemode": true,
    "android": {
        "packagename": "com.lktop.app",
        "androidpacktype": "0",
        "certalias": "别名",
        "certfile": "/path/to/keystore.jks",
        "certpassword": "密码",
        "storePassword": "库密码",
        "channels": ""
    },
    "ios": {
        "bundle": "com.lktop.app",
        "supporteddevice": "iPhone,iPad",
        "profile": "/path/to/profile.mobileprovision",
        "certfile": "/path/to/cert.p12",
        "certpassword": "密码"
    },
    "isconfusion": false,
    "splashads": false,
    "rpads": false,
    "pushads": false,
    "exchange": false
}

如果配置文件与命令行参数同时指定了相同参数，以命令行参数为准。

stdin 交互确认

⚠️ 推荐：使用 --safemode true（安心打包）可完全绕过此交互提示。 安心打包模式下 CLI 从「检查云端打包状态」直接跳到「检查打包资源」，不触发队列确认。这是 CLI 自动化场景的首选模式。

**传统打包模式（--safemode false / 默认值）**才需要以下交互处理：

云端已有打包队列时，cli pack 会输出以下提示并等待用户输入 Y/N：

云端已有打包队列时，cli pack（仅传统打包模式，--safemode false）会输出以下提示并等待用户输入 Y/N：

检测到本项目已有正在制作的安装包在云端队列中,继续打包将取消云端队里中的制作并重新排队,是否继续提交？

CLI 此时阻塞等待 stdin，必须传入 Y 才能继续：

echo Y | cli pack --project app --platform android ...

或使用 yes Y |（持续发送 Y，适合可能有多次确认的场景）。

输出捕获

cli pack 的输出直接写入终端，常规的进程管理器（如 Hermes 的 process(action='log')）可能无法实时捕获。推荐将输出重定向到文件，通过监控文件来跟踪进度：

# 后台运行 + 输出到文件
yes Y | cli pack --project app --platform android ... > /tmp/pack_output.log 2>&1 &

# 监控进度
tail -f /tmp/pack_output.log

这样即使进程在后台运行，也能可靠地读取每一步的输出。

⚠️ CLI 云打包静默挂起（两种原因）

cli pack 静默挂起有两种根因，诊断方法不同：

原因 A：RPC 超时（输出完全为空）

症状：cli pack 命令执行后从第一秒开始就无任何输出、进程挂起不退出。

根因：cli pack 通过 HBuilderX IDE 的内部 RPC 机制触发云打包。当 IDE 的 RPC 通道积累超时后（日志出现 rpc request ... for method: "log" occur timeout!），CLI 无法将打包指令送达 IDE。GUI 云打包走 IDE 内部线程直接执行（apppackagejob run），不依赖 RPC。

诊断：

grep -c "rpc request.*timeout" ~/Library/Application\ Support/HBuilder\ X/.log

计数持续增长（每 ~55 秒一条）→ RPC 卡死。

修复：重启 HBuilderX。

/Applications/HBuilderX.app/Contents/MacOS/cli app quit
sleep 3
/Applications/HBuilderX.app/Contents/MacOS/cli open

详见 references/rpc-debugging.md。

原因 B：云端队列残留（有输出但 Y 确认后挂起）

症状：cli pack 有输出——「检查云端打包状态...」+ 队列确认提示，传入 Y 确认后挂起无进展。

诊断：查看 IDE 日志是否有 checkstatusandcancelpack → false → [return result] cancel：

grep "checkstatusandcancelpack" ~/Library/Application\ Support/HBuilder\ X/.log | tail -5

出现 [return false] + [return result] cancel 即为队列阻塞。

修复：

1. 首先尝试 --safemode true（安心打包）——安心打包完全绕过队列确认，实测即使云端有残留队列也能正常提交。

   cli pack --config /path/to/config.json  # 配置中 safemode: true
   

2. 若安心打包也失败，登录 DCloud 后台手动清除残留队列，或用 GUI 重新打包覆盖。

详见 references/cloud-queue-stuck.md。

打包后：上传到 CDN（LKTOP 项目）

云打包产出本地 APK 后，通常需要上传到腾讯云 COS 通过 CDN 分发。上传脚本的 COS 凭据必须从 scripts/deploy-new-stack.sh 获取完整值（本地缓存脚本中密钥可能被截断导致 SignatureDoesNotMatch）。详见 references/cos-upload-apk.md。

生成本地打包资源（appResource）

不会直接输出 APK/IPA/HAP。只生成编译后的 JS/CSS/HTML 等前端资源，需要导入到对应原生工程中再用 Android Studio / Xcode / DevEco Studio 完成最终签名打包。

产物路径：<项目>/unpackage/resources/

# 通用（Android + iOS 资源）
cli publish --platform APP --type appResource --project <项目名称或绝对路径>

# 仅 Android（HBuilderX 4.67+）
cli publish app-android --type appResource --project <项目名称或绝对路径>

# 仅 iOS（HBuilderX 4.67+）
cli publish app-ios --type appResource --project <项目名称或绝对路径>

# 鸿蒙
cli publish app-harmony --type appResource --project <项目名称或绝对路径>

以 app 项目为例：

CLI=/Applications/HBuilderX.app/Contents/MacOS/cli

# Android
$CLI publish app-android --type appResource --project /Users/chester/Code/lktop/app

# iOS
$CLI publish app-ios --type appResource --project /Users/chester/Code/lktop/app

# 鸿蒙
$CLI publish app-harmony --type appResource --project /Users/chester/Code/lktop/app

鸿蒙本地打包（直接出 HAP / APP）

可以直接输出 HAP/APP 安装包，CLI 内部调用 DevEco Studio 的 hvigorw 工具链完成本地编译签名。

前提：本机已安装 DevEco Studio 且鸿蒙工程已配置好签名。

cli pack app-harmony --project <项目名称或绝对路径>

以 app 项目为例：

$CLI pack app-harmony --project /Users/chester/Code/lktop/app

构建后验证（推荐）：

1. 先检查 release 目录：

ls -la <项目>/unpackage/dist/build/app-harmony/build/outputs/release/

2. 用 pack.info 验证 bundle/version/releaseType：

cat <项目>/unpackage/dist/build/app-harmony/build/outputs/release/pack.info

3. 如需确认是否真为正式包，可继续检查 .app 内部的 .hap 与 module.json：

python3 - <<'PY'
import zipfile, io, json
app = '<项目>/unpackage/dist/build/app-harmony/build/outputs/release/app-harmony-release-signed.app'
with zipfile.ZipFile(app) as z:
    hap = next(n for n in z.namelist() if n.endswith('.hap'))
    with zipfile.ZipFile(io.BytesIO(z.read(hap))) as hz:
        mod = json.loads(hz.read('module.json'))
        print(json.dumps({
            'bundleName': mod.get('app', {}).get('bundleName'),
            'versionCode': mod.get('app', {}).get('versionCode'),
            'versionName': mod.get('app', {}).get('versionName'),
            'debug': mod.get('app', {}).get('debug'),
        }, ensure_ascii=False, indent=2))
PY

pack.info 是确认 Harmony release 包版本号、bundleName、releaseType 的稳定落盘文件；.app 本质上是 zip 容器，内部通常还会包含签名后的 .hap。

已验证的重要约束：

• cli pack app-harmony --help 当前仅暴露 --project 参数，没有文档化的 --mode debug / --buildMode debug / --product 之类开关。
• 在 HBuilderX 5.07 / DevEco Studio 6.0.2.640 上实测，cli pack app-harmony --project ... 默认产物落在 unpackage/dist/build/app-harmony/build/outputs/release/，输出的是 release .app（内部再包含 release HAP）。
• 因此：不要假设 HBuilderX CLI 能直接通过额外参数产出 Harmony debug/dev 安装包。 如果目标是 debug/dev HAP，需要转到 HBuilderX 生成的临时 Harmony 工程（如 unpackage/dist/dev/app-harmony）或 DevEco Studio / hvigor 工具链继续处理。
• 在 ~/Code/lktop/app 这类已验证仓库中，优先直接运行仓库脚本 bash scripts/build-harmony-debug-hap.sh；脚本会优先使用工程内 hvigorw，不存在时自动回退到 DevEco Studio 自带的 /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw。

制作 wgt 热更新包

wgt 包用于应用内热更新，无需重新提交应用商店。所有平台通用。

产物路径：<项目>/unpackage/release/<AppID>.wgt（默认）

# 默认选项
cli publish --platform APP --type wgt --project <项目名称或绝对路径>

# 自定义导出名称和路径
cli publish --platform APP --type wgt --project <项目名称> --name <名称.wgt> --path <导出目录>

# 启用原生混淆
cli publish --platform APP --type wgt --project <项目名称> --confuse true

# 平台专用 wgt（HBuilderX 4.67+）
cli publish app-android --type wgt --project <项目名称>
cli publish app-ios --type wgt --project <项目名称>
cli publish app-harmony --type wgt --project <项目名称>

以 app 项目为例：

$CLI publish --platform APP --type wgt --project /Users/chester/Code/lktop/app
# 产物：/Users/chester/Code/lktop/app/unpackage/release/__UNI__7908A29.wgt

注意事项

1. 上传命令必须指定资源类型：--upload 后面必须跟 cloudfunction、common、db、vf、action 或 all。省略资源类型会静默成功但不执行任何操作。正确的日志应包含 正在上传云对象xxx... 和 云对象xxx上传完成。
2. 上传下载默认行为：CLI 默认使用「强制跳过」模式——如果目标存在同名资源会自动跳过。使用 --force 可强制覆盖。
3. 项目名称：可以使用 cli project list 中显示的项目名称或序号。
4. 云空间：使用 cli cloud functions --list space 获取空间名称/id/序号。
5. 错误处理：操作失败会输出错误信息并中断，成功返回 0:xxx:OK。
6. HBuilderX 必须运行：所有 CLI 命令都需要 HBuilderX 在后台运行。
7. 云打包排队：周五傍晚等高峰期打包排队较长，需耐心等待。打包成功后下载链接为临时地址，只能下载 5 次。
8. wgt 版本匹配：wgt 文件运行的基座 SDK 版本必须与生成时的 HBuilderX 版本一致，否则部分功能可能异常。
9. appResource ≠ 安装包：--type appResource 只生成前端编译资源，不是 APK/IPA/HAP。需要导入原生离线工程再打包。
10. uniCloud 云对象 _ 前缀方法限制：云对象中 _ 前缀的方法（除 _before/_after 生命周期钩子外）会被 uniCloud 运行时从 this 上下文中剥离，无法通过 this._methodName() 调用。解决方案：将此类内部方法提取为模块级独立函数直接调用。
11. 共享云函数同步：admin 和 website 项目共用的云函数（如 website-page-editor），修改后需同步到两个项目目录再上传，确保代码一致。从任一项目上传效果相同（目标是同一个云空间）。
12. 登录状态检查：使用 cli user info（返回用户名），不要用 cli islogin（部分 CLI 版本不支持此命令，返回 命令不存在或缺少参数）。
13. CLI 云打包静默挂起（两种诊断路径）：有输出但 Y 确认后挂起 → 云端队列残留（references/cloud-queue-stuck.md）；从第一秒就无输出 → RPC 超时（references/rpc-debugging.md）。