uni-app 没有独立的 npm 安装版 uniapp-cli，实际可用的是 HBuilderX 自带的 cli 工具（Windows 为 cli.exe，macOS 为 cli），需完整安装 HBuilderX 3.1.5+ 版本，配置其路径至系统 PATH 后方可使用 cli --help 验证，并严格指定 --platform 等必要参数执行打包。
uni-app 不能直接用 npm 安装的 uniapp-cli 打包 —— 它根本不存在独立 CLI 包。真正可用的命令行工具是 HBuilderX 自带的 cli.exe（Windows）或 cli（macOS），必须依赖完整安装的 HBuilderX。
确认 HBuilderX 是否自带可用的 cli 工具
很多开发者误以为 npm install -g uniapp-cli 就能启动打包，实际会报错 command not found。HBuilderX 从 3.1.5 版本起才在安装目录内嵌 cli 可执行文件，且仅随完整版分发（非“精简版”或“绿色版”）。
- Windows：检查
HBuilderX\cli.exe是否存在（不是HBuilderX\plugins\cli下的脚本） - macOS：检查
/Applications/HBuilderX.app/Contents/MacOS/cli是否可执行（需chmod +x） - 运行
cli --help成功输出帮助信息，才算通过基础验证 - 若提示
0xc000007b（Windows）或dyld: Library not loaded（macOS），说明运行库缺失，不是配置问题，而是环境未就绪
正确配置 PATH 并验证 cli 环境变量
PATH 配置错误是 Windows 下最常见失败原因。不要把 HBuilderX 根目录加进 PATH，而应精确指向 cli.exe 所在目录（即同级于 HBuilderX.exe 的位置）。
- Windows 示例路径：
C:\Program Files\HBuilderX\（注意结尾无\cli.exe） - macOS 示例路径：
/Applications/HBuilderX.app/Contents/MacOS - 配置后必须新开终端（cmd / Terminal），再执行
cli --version；旧窗口不会自动继承新 PATH - 如果
cli --help正常但cli publish --platform APP报错 “project not found”，说明当前工作目录不是 uni-app 项目根目录（即含manifest.json和pages.json的目录）
打包命令必须带明确平台与类型参数
cli 不像 Vue CLI 那样有默认行为，所有关键参数都不可省略，漏一个就会静默失败或报模糊错误。
- H5 打包用：
cli build --platform h5 --env production（--env决定是否压缩、source map 等） - 小程序打包（如微信）：
cli build --platform mp-weixin --env production - App 本地资源生成（用于离线打包）：
cli publish --platform app --type appResource --project ./ - App 全量云打包（需登录且网络通畅）：
cli publish --platform app --type cloud --project ./ - 参数顺序无关，但
--platform和--type（对publish）或--env（对build）必须显式声明
App 打包失败常卡在证书或基座匹配
App 平台命令行打包最容易卡在签名环节，错误往往不直接提示“证书问题”，而是表现为构建中途退出、无输出、或生成空 apk。
- Android：确保
manifest.json中"android":{"sign":"xxx"}指向正确的.jks路径，且gradle.properties里已配置RELEASE_STORE_FILE等四条密钥参数 - iOS：macOS 环境下才支持本地打包；
.p12和.mobileprovision必须成对匹配，且manifest.json中"ios":{"certificate":"xxx.p12","profile":"xxx.mobileprovision"}路径为绝对路径 - 基座类型必须一致：若项目含
nvue文件，必须使用自定义基座；标准基座打nvue项目会编译通过但运行白屏 - 云打包时若提示 “证书无效”，大概率是 DCloud 后台未同步最新证书指纹，需在 HBuilderX 图形界面中重新上传一次
真正麻烦的从来不是命令怎么写，而是 cli 这个工具本身是 HBuilderX 的附属品 —— 它不提供独立安装包、不校验依赖、不打印详细错误栈。一旦出问题，得先确认 HBuilderX 版本、运行库、证书路径、项目结构四个层面全部到位，缺一不可。
