ap

ap 是一个由项目配置驱动的 Android APK 打包与发布 CLI。它可以在配置指定的目录中调用项目自带的 Gradle Wrapper 打包 APK，也可以校验配置版本与 Android Gradle 版本，并在 Gitee 创建同名标签和 Release 后上传 APK。

只有显式执行 ap build 时 CLI 才会运行 Gradle；ap publish 不会隐式打包。项目基于 Node.js 18.11+ 内置能力实现，没有运行时 npm 依赖。

全局安装

以下命令均由使用者按需手动执行：

npm install --global D:\my_project\sdk-project\android-publish

安装后可先查看全部命令、功能介绍和示例：

ap --help
# 或
ap -h

# 查看某个命令的详细帮助
ap help publish
ap check -h

CLI 更新提示

执行任意有效的 ap 命令时，CLI 会并行查询 npm 上的 latest 版本。若线上版本高于当前版本，命令结束后会提示可下载的新版本以及更新命令：

npm install --global android-publish-cli@latest

版本查询设有超时并会在网络异常时静默跳过，不会改变原命令的执行结果或退出码。更新提示输出到标准错误流，因此不会污染 ap version 等命令的标准输出。

CLI 命令

| 命令 | 功能 | | --- | --- | | init | 初始化项目：检查当前项目，若 publish-config.json 或 changelog.md 不存在则自动生成模板；已存在默认跳过，--force 强制覆盖 | | bump | 升级发布配置的版本号：按 patch/minor/major 自增或直接指定版本号，versionCode 默认 +1，可用 --code 指定 | | build | 读取配置中的打包目录和 Gradle 任务，通过项目 Gradle Wrapper 打包并校验 APK | | publish | 校验本地发布资料，在 Gitee 创建标签与 Release，并上传已有 APK；省略命令时默认执行 | | check | 只校验本地配置、Gradle 版本、changelog 和 APK，不访问或修改 Gitee；若 Gradle 版本号为变量注入（单一数据源），会以配置为准并输出提示 | | help [命令] | 显示总帮助，或指定命令的详细用法、选项和示例 | | version | 显示当前 CLI 版本 |

常用执行方式：

# 初始化项目：生成缺失的 publish-config.json 与 changelog.md 模板
ap init

# 升级发布配置的版本号（versionName 自增，versionCode +1）
ap bump patch

# 使用 Gradle Wrapper 打包 APK
ap build

# 仅校验本地配置、Gradle 版本、changelog 和 APK
ap check

# 创建 Gitee Release 并上传 APK
ap publish

# 省略命令时也会执行发布，兼容原有使用方式
ap

# --dry-run 继续保留，等同于本地预检查
ap --dry-run

也可以从其他目录明确指定项目：

ap check --project D:\path\to\android-project
ap build --project D:\path\to\android-project
ap publish --project D:\path\to\android-project

项目初始化

ap init 会自动检查当前项目目录，若以下文件不存在则生成模板，已存在的文件默认跳过（不会覆盖真实数据）：

• publish-config.json：发布配置模板（内容与 publish-config.example.json 一致）。
• changelog.md：更新说明模板。

# 在当前目录初始化
ap init

# 强制用模板覆盖已存在的文件
ap init --force

版本号升级

ap bump 用于升级 publish-config.json 中的发布版本号：

ap bump patch        # 1.2.3 -> 1.2.4，versionCode +1
ap bump minor        # 1.2.3 -> 1.3.0，versionCode +1
ap bump major        # 1.2.3 -> 2.0.0，versionCode +1
ap bump 1.5.0        # 直接指定版本号，versionCode +1
ap bump 1.5.0 --code 42   # 同时显式指定 versionCode

说明：

• versionName 遵循语义化版本规则，--code 必须为正整数。
• 若不指定 --code，versionCode 在当前基础上 +1（保证单调递增）。
• 该命令只更新配置，不修改 Gradle 文件。若采用「单一数据源」方式（Gradle 读取配置注入版本号），两者会自动保持同步。

CLI 打包

ap build 会先校验发布配置与 Gradle 版本，然后进入 android.build.directory 指定的目录，自动选择当前平台的 gradlew.bat 或 gradlew，执行 android.build.task。任务成功后，CLI 会将 Gradle 生成的同名 APK 同步到 artifact.path（例如 app/release/app-release.apk），并检查 APK 是否存在及大小是否符合限制。

# 按 publish-config.json 打包
ap build

# 从其他目录指定 Android 项目与配置文件
ap build --project D:\path\to\android-project --config config\release.json

打包环境依赖

以下依赖由使用者按项目要求自行准备，CLI 不会安装或修改系统环境：

• 与项目 Gradle / Android Gradle Plugin 版本兼容的 JDK。
• Android SDK 及项目需要的对应平台、Build Tools。
• android.build.directory 中当前平台可用的 Gradle Wrapper（Windows 为 gradlew.bat，macOS / Linux 为 gradlew）。
• Release 构建需要的签名配置；CLI 不读取或托管签名凭据。

项目配置

复制 publish-config.example.json 为 Android 项目根目录下的 publish-config.json，并按项目填写：

{
  "provider": "gitee",
  "repository": "owner/repository",
  "authentication": {
    "token": "your-gitee-personal-access-token"
  },
  "release": {
    "versionName": "1.0.0",
    "versionCode": 1,
    "tagPrefix": "",
    "prerelease": false
  },
  "artifact": {
    "path": "app/release/app-release.apk",
    "maxSizeMb": 100
  },
  "android": {
    "gradleFile": "app/build.gradle.kts",
    "build": {
      "directory": ".",
      "task": "assembleRelease"
    }
  },
  "changelog": {
    "path": "changelog.md"
  }
}

所有文件路径都以 Android 项目根目录为基准，且必须位于该项目目录内。

• android.build.directory：Gradle Wrapper 所在目录。普通 Android 项目通常为 .；若 Android 工程位于仓库的 android 子目录，可设置为 android。
• android.build.task：要执行的单个 Gradle 任务，默认 assembleRelease；多模块项目也可填写 :app:assembleRelease。
• artifact.path：最终保存 APK 的项目相对路径，例如 app/release/app-release.apk。它既是 build 的结果路径，也是 check / publish 读取和上传的文件；Gradle 的内部输出目录无需写入配置。

为兼容旧配置，省略 android.build 时会默认使用项目根目录和 assembleRelease。

changelog.md

changelog.md 每次只保存即将发布版本的内容。文件的全部 Markdown 正文会原样作为 Gitee Release 描述，不需要添加版本分节：

# 更新内容

- 优化性能。
- 优化 UI 布局。

下一次发版时，直接用新版本的更新内容覆盖该文件。

发布校验与边界

每次发布前，CLI 会校验：

• release.versionName 是语义化版本，release.versionCode 是正整数。
• 配置版本与 android.gradleFile 中的版本完全一致。
• APK 文件存在、扩展名为 .apk，并且未超过配置的大小限制。
• changelog.md 不为空。
• 同名 Gitee Release 尚不存在；已有 Release 不会被覆盖。

版本号单一数据源（可选）

推荐让 publish-config.json 成为版本号的唯一来源，避免与 build.gradle.kts 手动同步不一致。做法是在 Gradle 中读取 publish-config.json 并注入版本号，例如：

// app/build.gradle.kts
import org.json.JSONObject

val publishConfigFile = rootProject.file("publish-config.json")
val release = JSONObject(publishConfigFile.readText()).getJSONObject("release")

android {
    defaultConfig {
        versionCode = release.getInt("versionCode")
        versionName = release.getString("versionName")
    }
}

此时 Gradle 中的版本号由配置文件注入，二者天然同源。CLI 的 build / check / publish 会识别这种「变量注入」写法，以配置版本为准，不再比对 Gradle 中的字面量；check / publish 还会在发布计划中输出提示。

publish --dry-run 只执行本地校验，不访问或修改 Gitee；build 不接受 --dry-run。实际发布要求目标仓库已经有默认分支和至少一个提交。

build、check 和 publish 相互独立：build 只负责本地打包，check 只负责本地发布预检查，publish 只发布已有 APK。需要完整流程时，由使用者依次执行 ap build、ap check、ap publish。