uni-app 无独立 npm 版 cli，命令行打包必须依赖 HBuilderX 3.1.5+ 自带的 cli.exe（Windows）或 cli（macOS），需完整安装、正确配置 PATH、图形界面首次登录账号，并严格使用 build（H5）或 publish（App/小程序）配合 --platform、--type、--project 等必选参数。
uni-app 没有独立的 npm install -g uniapp-cli 可用 CLI，所谓“命令行打包”实际依赖 HBuilderX 自带的 cli 工具（Windows 为 cli.exe，macOS 为 cli），必须完整安装 HBuilderX 3.1.5+ 并正确配置 PATH 才能运行。直接 npm 安装或使用旧版/精简版 HBuilderX 均会失败。
确认 cli 是否真正可用
很多开发者卡在第一步：执行 cli --help 报错或提示 command not found。这不是项目问题，而是环境没就绪。
- Windows：检查
HBuilderX\cli.exe是否存在（注意不是plugins/cli下的脚本）；若报0xc000007b，说明缺少 VC++ 运行库，需单独安装 Microsoft Visual C++ Redistributable - macOS：检查
/Applications/HBuilderX.app/Contents/MacOS/cli是否存在且可执行；若报dyld: Library not loaded，需先chmod +x赋权，再确认是否已安装对应版本的 JDK（HBuilderX 3.8+ 需 JDK 17+） - 验证方式：新开终端，运行
cli --version，输出版本号（如v3.8.19）才算通过
打包 H5 必须用 build 而非 publish
publish 是为小程序/APP 云打包设计的，对 H5 无效；H5 打包唯一有效命令是 build，且 --platform h5 和 --env 缺一不可。
- 正确命令：
cli build --platform h5 --env production --project /path/to/your/project -
--env production决定是否压缩 JS/CSS、是否生成 source map；漏掉会默认走 development，资源不压缩、体积大、含调试信息 -
--project必须指向含manifest.json和pages.json的项目根目录；当前目录不是项目根时，即使路径写对也会报 “project not found” - 输出目录固定为
dist/build/h5（不可通过参数改名）；如需自定义路径，得靠后续脚本移动或用UNI_OUTPUT_DIR环境变量（仅对npm run build:h5类 Vue CLI 风格命令生效，cli build不识别）
App 和小程序打包必须显式指定 type 和 platform
cli publish 不像 Webpack 那样有默认行为，漏参数就会静默失败或报模糊错误，尤其容易忽略 --type。
- App 离线打包（本地生成 resources）：
cli publish --platform app --type appResource --project ./ - App 云打包（需登录、网络通畅）：
cli publish --platform app --type cloud --project ./ - 微信小程序：
cli build --platform mp-weixin --env production --project ./（注意是build，不是publish） - 所有命令都要求项目内已存在
unpackage/目录（首次运行会自动生成），若被误删会导致 “no output dir” 类报错
常见权限与路径陷阱
CLI 工具对路径和权限比图形界面敏感得多，稍不注意就卡在文件写入环节。
- Windows 下用 PowerShell 或 Git Bash 执行时，若提示 “拒绝访问”，优先检查是否以管理员身份运行——
cli.exe在生成 App 资源时会尝试写入系统临时目录 - macOS 上若输出目录在 iCloud 同步区（如
~/Desktop），可能因文件锁导致打包中断；建议输出到/tmp或项目同盘符的非同步路径 - 路径中含中文、空格或特殊字符（如
&、(）大概率触发解析失败；务必用英文路径，例如/Users/name/uni-projects/myapp - 首次使用前，必须在 HBuilderX 图形界面中完成账号登录；CLI 不会弹窗引导，未登录直接跑
publish会卡住或返回空结果
最易被忽略的一点：HBuilderX 的 CLI 和图形界面共享同一套缓存与插件状态。如果图形界面开着，CLI 打包可能被占用或读取到过期配置；每次执行前建议关闭 HBuilderX，尤其是涉及 App 或小程序打包时。
