AutoMan CLI 命令使用

当前 CLI 仅 Windows 端支持，适合批处理、CI 或需要重复执行固定流程的场景。

AutoMan CLI 可以在命令行执行 GUI 中的主要能力：SDK 模板更新、广告配置更新、Cocos 授权、Cocos 解密资源生成、资源导入模板工程、Android Gradle 打包，以及环境检查/配置。

调用方式

Windows 端 AutoMan 安装完成后的程序目录中，BestBuildTools.exe 用于启动 GUI，BestBuildToolsCLI.exe 用于命令行：

powershell

BestBuildToolsCLI.exe --help
BestBuildToolsCLI.exe android-pack --project "D:\game\proj.android"

BestBuildToolsCLI.exe 是实际可执行文件名，命令示例中请保持该名称，不要改成 AutoManCLI.exe。

Windows 安装包会生成控制台子系统的 BestBuildToolsCLI.exe。从 CMD 或 PowerShell 直接运行时，当前命令行会等待 CLI 结束并保留退出码。

如确实不希望 CLI 自动切换当前控制台代码页，可设置 BBT_SKIP_CHCP=1。

不要在 Electron CLI 模式下设置 ELECTRON_RUN_AS_NODE=1，否则 Electron 会按 Node 兼容模式启动，无法正常取得 app 运行时。

环境要求

环境	要求	检查/配置命令
Python	Python 3.12+	`BestBuildToolsCLI.exe doctor` 或 `BestBuildToolsCLI.exe config set --python <python.exe>`
Python 依赖	`requirements.txt` 中的依赖，当前为 `cryptography`	`BestBuildToolsCLI.exe env setup`
JDK	JDK 17+	`BestBuildToolsCLI.exe config set --java-home <dir>`
Gradle	推荐 Gradle 8.10.1	`BestBuildToolsCLI.exe config set --gradle-home <dir>`
Android SDK	可用 Android SDK 根目录	`BestBuildToolsCLI.exe config set --android-sdk-home <dir>`

快速开始

powershell

# 1. 检查运行环境
BestBuildToolsCLI.exe doctor

# 2. 首次命令行使用前，安装 Python 依赖
BestBuildToolsCLI.exe env setup

# 3. 持久化 JDK / Gradle / Android SDK 路径
BestBuildToolsCLI.exe config set `
  --java-home "D:\AutoMan\jdk\jdk-17" `
  --gradle-home "D:\AutoMan\gradle\gradle-8.10.1" `
  --android-sdk-home "D:\AutoMan\android-sdk\android_sdk"

# 4. 执行一个功能
BestBuildToolsCLI.exe sdk-update --project "D:\projects\game-template"

全局参数

这些参数可用于所有命令。

参数	必填	默认值	说明
`-h, --help`	否	-	显示帮助。可配合 `help <command>` 查看单个命令。
`-v, --version`	否	-	显示当前版本。
`-c, --config <file>`	否	Electron `userData/bestbuild.config.json`	指定配置文件路径；默认与 GUI 共用配置。
`--python <exe>`	否	配置/环境自动探测	本次运行使用的 Python 解释器。要求 Python 3.12+。
`--java-home <dir>`	否	配置/环境自动探测	本次运行使用的 JDK 根目录。
`--gradle-home <dir>`	否	配置/环境自动探测	本次运行使用的 Gradle 根目录。
`--android-sdk-home <dir>`	否	配置/环境自动探测	本次运行使用的 Android SDK 根目录，会写入子进程 `ANDROID_HOME` / `ANDROID_SDK_ROOT`。
`--no-backup`	否	按配置启用	本次脚本运行关闭自动备份。
`--dry-run`	否	`false`	只打印将执行的 Python 脚本命令，不真正执行。
`--log-file <file>`	否	-	将命令输出同步写入指定日志文件。
`-j, --json`	否	`false`	对 `doctor` / `validate` / `config show` 输出 JSON。

环境与配置命令

`doctor`

检查 Python、JDK、Gradle、Android SDK。

powershell

BestBuildToolsCLI.exe doctor
BestBuildToolsCLI.exe doctor --json

`env setup`

安装 Python 依赖。会优先使用项目内 wheels/ 离线安装 requirements.txt，未命中时回退在线安装。

powershell

BestBuildToolsCLI.exe env setup
BestBuildToolsCLI.exe env setup --force
BestBuildToolsCLI.exe env setup --python "C:\Python312\python.exe"

参数	必填	默认值	说明
`--force`	否	`false`	即使当前 Python 已记录为依赖安装完成，也重新执行 `ensurepip` 和 `pip install`。
`--python <exe>`	否	自动探测	指定 Python 解释器。

可选环境变量：

变量	说明
`BESTBUILD_PYTHON`	指定 Python 解释器路径。
`BESTBUILD_PYTHON_DIR`	将指定目录加入 Python 探测 PATH。
`BESTBUILD_PYPI_MIRROR`	在线重试时使用的 PyPI 镜像，默认 `https://pypi.org/simple`。

`config show`

查看当前配置文件路径和内容。

powershell

BestBuildToolsCLI.exe config show
BestBuildToolsCLI.exe config show --json

`config set`

写入 CLI/GUI 共用配置。

powershell

BestBuildToolsCLI.exe config set --python "C:\Python312\python.exe"
BestBuildToolsCLI.exe config set --java-home "D:\AutoMan\jdk\jdk-17"
BestBuildToolsCLI.exe config set --gradle-home "D:\AutoMan\gradle\gradle-8.10.1"
BestBuildToolsCLI.exe config set --android-sdk-home "D:\AutoMan\android-sdk\android_sdk"
BestBuildToolsCLI.exe config set --auto-backup false

参数	必填	默认值	说明
`--python <exe>`	否	-	保存 Python 解释器。默认会校验版本。
`--java-home <dir>`	否	-	保存 JDK 根目录。默认会校验目录结构。
`--gradle-home <dir>`	否	-	保存 Gradle 根目录。默认会校验目录结构。
`--android-sdk-home <dir>`	否	-	保存 Android SDK 根目录。默认会校验目录结构。
`--auto-backup <true	false>`	否	-
`--skip-verify`	否	`false`	跳过路径校验，直接写入配置。

`install`

下载工具链。此命令会访问 CDN，Android SDK 包体可能很大。

powershell

BestBuildToolsCLI.exe install gradle
BestBuildToolsCLI.exe install android-sdk
BestBuildToolsCLI.exe install jdk --save-dir "D:\AutoMan\jdk-installer"

命令	参数	说明
`install gradle`	`--no-save`	下载并解压 Gradle 8.10.1；成功后默认写入 `gradleHome`。
`install android-sdk`	`--no-save`	下载并解压 Android SDK 离线包；成功后默认写入 `androidSdkHome`。
`install jdk`	`--save-dir <dir>`	下载 JDK 17 MSI 到指定目录；需手动完成安装后再 `config set --java-home`。默认保存到用户 Downloads。

项目校验

validate 只做结构检查，不执行脚本。

powershell

BestBuildToolsCLI.exe validate sdk-update --project "D:\projects\template"
BestBuildToolsCLI.exe validate cocos-decrypt --project "D:\projects\cocos-game"
BestBuildToolsCLI.exe validate resource-import --project "D:\projects\template" --json

参数	必填	说明
`<module>`	是	支持 `sdk-update`、`ad-config`、`cocos-license`、`cocos-decrypt`、`resource-import`、`android-pack`。
`-p, --project <dir>`	是	要校验的工程目录。
`--json`	否	输出结构化 JSON。

功能命令

所有功能命令都支持 --dry-run、--log-file <file>、--no-backup。

`sdk-update`

SDK 模板工程更新。

powershell

BestBuildToolsCLI.exe sdk-update --project "D:\projects\game-template"

参数	必填	默认值	说明
`-p, --project <dir>`	是	-	Android 模板工程根目录，需含 `AndroidManifest.xml` 与 `libs`。

`ad-config`

广告配置更新。

powershell

BestBuildToolsCLI.exe ad-config --project "D:\projects\game-template"

参数	必填	默认值	说明
`-p, --project <dir>`	是	-	Android 工程根目录，需含 `AndroidManifest.xml` 与 `assets`。

`cocos-license`

Cocos 加密授权。

powershell

BestBuildToolsCLI.exe cocos-license --project "D:\projects\game-template"

参数	必填	默认值	说明
`-p, --project <dir>`	是	-	Android 工程根目录，`AndroidManifest.xml` 需能读取 `package`。

`cocos-decrypt`

Cocos 解密资源生成。

powershell

BestBuildToolsCLI.exe cocos-decrypt --project "D:\projects\cocos-game"

参数	必填	默认值	说明
`-p, --project <dir>`	是	-	Cocos Creator 工程根目录，不要选择 Android 壳工程、Gradle 模板或单独导出目录。

`resource-import`

将 Unity/Cocos 资源导入 Android 模板工程。

powershell

# 自动从模板 project.properties 识别 mode
BestBuildToolsCLI.exe resource-import `
  --project "D:\projects\game-template" `
  --export "D:\exports\unity-game"

# 手动指定 Cocos 3.x
BestBuildToolsCLI.exe resource-import `
  --project "D:\projects\game-template" `
  --export "D:\projects\cocos-game" `
  --mode cocos3

参数	必填	默认值	说明
`-p, --project <dir>`	是	-	Android 模板工程根目录，需含 `AndroidManifest.xml`、`assets`、`libs`。
`-e, --export <dir>`	是	-	Unity 导出根目录，或 Cocos Creator 工程根目录。
`--mode <unity	cocos3	cocos2>`	否

`android-pack`

Android Gradle 打包。默认会先执行广告配置更新，成功后再打包。

powershell

BestBuildToolsCLI.exe android-pack --project "D:\projects\game-template"

BestBuildToolsCLI.exe android-pack `
  --project "D:\projects\game-template" `
  --artifact aab `
  --build-type release `
  --version-code 10012 `
  --version-name "1.0.12"

BestBuildToolsCLI.exe android-pack `
  --project "D:\projects\game-template" `
  --artifact apk `
  --build-type debug `
  --no-pre-ad-config

参数	必填	默认值	说明
`-p, --project <dir>`	是	-	Android 工程根目录。
`--artifact <apk	aab>`	否	`apk`
`--build-type <debug	release>`	否	`release`
`--version-code <N>`	否	不修改	打包前写回 `AndroidManifest.xml` 的 `android:versionCode`，必须为正整数。
`--version-name <TEXT>`	否	不修改	打包前写回 `AndroidManifest.xml` 的 `android:versionName`。
`--gradle-home <dir>`	否	配置/环境自动探测	Gradle 根目录。
`--java-home <dir>`	否	配置/环境自动探测	JDK 根目录。
`--android-sdk-home <dir>`	否	配置/环境自动探测	Android SDK 根目录。
`--pre-ad-config`	否	开启	打包前先跑广告配置更新。
`--no-pre-ad-config`	否	-	跳过前置广告配置更新。

别名

标准命令	可用别名
`sdk-update`	`sdk_update`、`sdk`
`ad-config`	`ad_config`、`ad`
`resource-import`	`resource_import`、`import`
`android-pack`	`android-gradle-pack`、`android_pack`、`android_gradle_pack`、`pack`
`cocos-license`	`cocos_license`、`license`
`cocos-decrypt`	`cocos-encryption`、`cocos_decrypt`、`cocos_encryption`、`decrypt`

也可以使用统一形式：

powershell

BestBuildToolsCLI.exe run sdk-update --project "D:\projects\game-template"
BestBuildToolsCLI.exe run android-pack --project "D:\projects\game-template"

退出码

退出码	说明
`0`	命令成功。
`1`	参数错误、环境缺失、校验失败或脚本执行失败。
其他非零值	Python 脚本或 Gradle 子进程返回的退出码。

注意事项

sdk-update、ad-config、resource-import、cocos-decrypt 默认会触发工程备份；可用 --no-backup 关闭本次备份，或 config set --auto-backup false 修改默认配置。
android-pack 默认先执行 ad-config；如果只想打包，使用 --no-pre-ad-config。
cocos-decrypt 必须选择 Cocos Creator 工程根目录，不要选择 Android 壳工程。
resource-import --mode 省略时依赖模板工程的 project.properties，识别失败时请手动传 --mode unity|cocos3|cocos2。
Windows PowerShell 路径中有空格时请使用引号。

AutoMan CLI 命令使用 ​

调用方式 ​

环境要求 ​

快速开始 ​

全局参数 ​

环境与配置命令 ​

doctor ​

env setup ​

config show ​

config set ​

install ​

项目校验 ​

功能命令 ​

sdk-update ​

ad-config ​

cocos-license ​

cocos-decrypt ​

resource-import ​

android-pack ​

别名 ​

退出码 ​

注意事项 ​

AutoMan CLI 命令使用

调用方式

环境要求

快速开始

全局参数

环境与配置命令

`doctor`

`env setup`

`config show`

`config set`

`install`

项目校验

功能命令

`sdk-update`

`ad-config`

`cocos-license`

`cocos-decrypt`

`resource-import`

`android-pack`

别名

退出码

注意事项