docs: document combined Android release packaging

Author: sunnylqm

site/pages/docs/bestpractice.md

@@ -52,6 +52,22 @@ splits {
 
 将 react-native-update-cli 更新到 v2.6.0 以上版本，即可使用 pushy parseAab 和 pushy uploadAab 命令来支持 aab 格式的原生包。
 
+如果同一个 Android 版本既需要上架 Google Play 的 AAB，也需要给其他渠道分发 APK，建议不要分两次构建。请在项目根目录的`package.json`中配置一个 npm script，让 CI 和本地发布都通过同一个入口，在同一次 Gradle 调用中同时执行`assembleRelease`和`bundleRelease`。如果已有`scripts`字段，只需要追加其中一项：
+
+```json
+{
+  "scripts": {
+    "package:android:release": "cd android && ./gradlew clean assembleRelease bundleRelease"
+  }
+}
+```
+
+```bash
+$ npm run package:android:release
+```
+
+这样生成的`android/app/build/outputs/apk/release/app-release.apk`和`android/app/build/outputs/bundle/release/app-release.aab`来自同一次 release 构建，编译时间戳保持一致。之后按渠道分发对应格式即可：Google Play 使用 AAB，直装包或第三方渠道使用 APK。如果项目使用 flavor，请把 npm script 中的任务名改为实际 variant，例如`assembleProdRelease`和`bundleProdRelease`。
+
 #### 测试与回滚
 
 自 v10.11.2 版本开始，可以使用以下两种快捷扫码方案来测试热更，而无需提前进行绑定：

site/pages/docs/publish.mdx

@@ -14,9 +14,9 @@ flowchart TD
     subgraph 发布原生基准版本
     tagNativeVersion["🏷️  (在 git 上)标记原生版本号"]
     newNativeVersion["🗂️  新的原生基准版本"]
-    nativePackage["📦  原生完整包(apk或ipa文件)"]
+    nativePackage["📦  原生完整包(apk、aab或ipa文件)"]
     tagNativeVersion--"🔨  编译"-->nativePackage
-    nativePackage--"⬆️&nbsp;&nbsp;使用<br/>pushy uploadApk/uploadIpa<br/>命令上传"-->newNativeVersion
+    nativePackage--"⬆️&nbsp;&nbsp;使用<br/>pushy uploadApk/uploadAab/uploadIpa<br/>命令上传"-->newNativeVersion
     end
     subgraph 发布热更新版本
     tagBundleVersion["🏷️&nbsp;&nbsp;(在 git 上)标记热更新版本号"]
@@ -33,7 +33,7 @@ flowchart TD
 
 流程总结如下：
 
-1.  我们需要先打包一个原生 release 版本，在打包前请确保已集成了`react-native-update`并在调试过程中运行正常，安卓端[关闭了`crunchPngs`设置](/docs/getting-started#%E7%A6%81%E7%94%A8-android-%E7%9A%84-crunch-%E4%BC%98%E5%8C%96)，打包说明可参考[iOS 打包](https://reactnative.cn/docs/publishing-to-app-store)和[android 打包](https://reactnative.cn/docs/signed-apk-android)。打包完成后请使用`pushy uploadIpa`或者`pushy uploadApk`命令来把这个安装包上传到 pushy 服务器端，以作为之后热更差量对比的基准。同时请保留好这个安装包，上架和分发给用户所使用的安装包`需要和服务器端完全一致`。建议使用 git tag 功能来标记原生版本号（例如`v1.0.0`）。
+1.  我们需要先打包一个原生 release 版本，在打包前请确保已集成了`react-native-update`并在调试过程中运行正常，安卓端[关闭了`crunchPngs`设置](/docs/getting-started#%E7%A6%81%E7%94%A8-android-%E7%9A%84-crunch-%E4%BC%98%E5%8C%96)，打包说明可参考[iOS 打包](https://reactnative.cn/docs/publishing-to-app-store)和[android 打包](https://reactnative.cn/docs/signed-apk-android)。打包完成后请使用`pushy uploadIpa`、`pushy uploadApk`或`pushy uploadAab`命令来把这个安装包上传到 pushy 服务器端，以作为之后热更差量对比的基准。同时请保留好这个安装包，上架和分发给用户所使用的安装包`需要和服务器端完全一致`。建议使用 git tag 功能来标记原生版本号（例如`v1.0.0`）。
 2.  然后在基准版本之上迭代业务逻辑（增删 js 代码，增删图片等静态资源），使用`pushy bundle`命令来生成和发布热更新版本，而不需要重新打包。建议使用 git tag 功能来标记热更版本号（例如`v1.0.1`）。
 3.  如果迭代过程中有原生方面的修改，则需要发布并上传新的原生基准版本（重复步骤 1，但需要设置不同的原生版本号）。可以只保留一个原生基准版本，也可以多版本同时维护。
 
@@ -64,20 +64,42 @@ $ pushy uploadIpa <ipa后缀文件>
 
 首先参考[文档-打包 APK](https://reactnative.cn/docs/signed-apk-android)设置签名，然后在 android 文件夹下运行`./gradlew assembleRelease`或`./gradlew aR`，你就可以在`android/app/build/outputs/apk/release/app-release.apk`中找到你的应用包。
 
+如果你需要同时向 Google Play 等渠道分发 `.aab`，并向其他渠道分发 `.apk`，建议在项目根目录的`package.json`中配置一个 npm script，在同一次 Gradle 调用中同时执行`assembleRelease`和`bundleRelease`。这样 APK 与 AAB 会复用同一份 release 构建产物，内置 bundle 与编译时间戳保持一致，后续按渠道分发对应格式即可。如果已有`scripts`字段，只需要追加其中一项：
 
-然后运行如下命令
+```json
+{
+  "scripts": {
+    "package:android:release": "cd android && ./gradlew clean assembleRelease bundleRelease"
+  }
+}
+```
+
+```bash
+$ npm run package:android:release
+```
+
+产物路径如下：
+
+```text
+android/app/build/outputs/apk/release/app-release.apk
+android/app/build/outputs/bundle/release/app-release.aab
+```
+
+如果项目使用了 flavor，请按实际 variant 调整 npm script 中的任务名，例如`assembleProdRelease`和`bundleProdRelease`。不要先单独执行一次`assembleRelease`，再在另一次 Gradle 命令中执行`bundleRelease`，否则两个包可能带有不同的编译时间戳。
+
+然后根据实际分发格式运行对应命令
 
 ```bash
 $ pushy uploadApk android/app/build/outputs/apk/release/app-release.apk
-# 如果你打的是 aab 格式的包，则请使用以下命令
-# pushy uploadAab android/app/build/outputs/bundle/release/app-release.aab
+# 如果你实际分发的是 aab 格式的包，则使用：
+$ pushy uploadAab android/app/build/outputs/bundle/release/app-release.aab
 ```
 
-即可上传 apk 以供后续版本比对之用。此 apk 的`versionName`字段(位于`android/app/build.gradle`中)会被记录为原生版本号`packageVersion`。
+即可上传对应的 Android 原生包以供后续版本比对之用。此包的`versionName`字段(位于`android/app/build.gradle`中)会被记录为原生版本号`packageVersion`。
 
-随后你可以选择往应用市场发布这个版本，也可以先往设备上直接安装这个 apk 文件以进行测试。
+随后你可以选择往应用市场发布这个版本，也可以先往设备上直接安装 apk 文件以进行测试。若同一个版本同时产出了 APK 与 AAB，请根据渠道要求分发对应格式：Google Play 通常使用 AAB，其他直装或第三方渠道通常使用 APK。
 
-如果后续需要再次打包（例如修改原生代码或配置。如果只是修改 js 代码则不需要重新打包。），请先**更改版本号**，并再次`uploadApk`到服务器端记录，否则后续生成的相同版本的原生包会由于[编译时间戳不一致而`无法获取热更新`](faq#热更新报错：热更新已暂停，原因：buildtime-mismatch。)。
+如果后续需要再次打包（例如修改原生代码或配置。如果只是修改 js 代码则不需要重新打包。），请先**更改版本号**，并再次上传对应原生包到服务器端记录，否则后续生成的相同版本的原生包会由于[编译时间戳不一致而`无法获取热更新`](faq#热更新报错：热更新已暂停，原因：buildtime-mismatch。)。
 
 ### Harmony