@flun/node-mobile-app 4.1.2 → 4.2.0

package/Android/346/236/204/345/273/272/346/214/207/345/215/227.md

@@ -129,7 +129,7 @@ NODE_MOBILE_PREBUILT_ANDROID_SKIP=1     # 只跳过 Android
 **预编译产物仓库**:
 
 - GitHub:https://github.com/OpenFlun/nodejs-mobile
-- Gitee(国内):https://gitee.com/OpenFlun/nodejs-mobile
+- Gitee(中国):https://gitee.com/OpenFlun/nodejs-mobile
 
 **架构支持(按版本)**:
 

package/CHANGELOG.md

@@ -1,32 +1,25 @@
 # 变更日志
 
+## [4.2.0] - 2026-11-09 15:33
+### 新增
+- 新增 `android.gradleDistributionUrl` 配置项,可指定 Gradle 发行版的完整下载地址;未配置时按腾讯、阿里、
+  官方顺序探测,三者均不可达则回落官方并警告;已配置时直接使用,失败不回退,并提示可改回 null 或换可达地址;
+- 新增 `android.mavenRepositories` 配置项,可自定义 Maven 仓库数组,同时替换 `settings.gradle` 与根
+  `build.gradle` 的仓库列表;未配置时保持模板默认(阿里云 public/google/gradle-plugin + 官方 google/mavenCentral);
+### 优化
+- 导出函数统一改为独立 `const` 声明并按字母序集中导出,未导出内容仍用逗号链;导出项补全标准 JSDoc;
+- 各文件 import 统一为第三方包在前、相对路径在后、各自字母序,花括号内名字按大小写不敏感字母序;
+- 删除无调用方的 `readInstallState`,移除 `ensureInstallable` 未使用的 `buildDir` 参数;
+- 模板 `App.tsx`、`.prettierrc.js`、`babel.config.js`、`eslint.config.js`、`metro.config.js` 改为
+  `const` 声明加末尾导出;
+
 ## [4.1.2] - 2026-11-07 22:27
 ### 修复
 - 修复 Android 构建长时间卡在 Gradle 下载的问题;模板 `gradle-wrapper.properties` 的 `distributionUrl`
-  由 `services.gradle.org` 改为腾讯云镜像,国内直连官方源常超时且不报错;
+  由 `services.gradle.org` 改为腾讯云镜像,中国直连官方源常超时且不报错;
 - 修复 `--debug` 下 Gradle 进度条被拆成大量点与数字的问题;调试模式编译改为 `stdio: 'inherit'`,
   让进度条直连终端刷新,不再经管道逐块拆分;
 
 ## [4.1.1] - 2026-11-06 11:11
 ### 优化
-- 细节优化;
-
-## [4.1.0] - 2026-11-06 10:10
-### 新增
-- 新增 `example` 子命令,重新生成 `mobileAppConfig.js` 到项目根目录;此前该文件只由 `postinstall` 自动复制,
-  误删后无法手动恢复;文件已存在时跳过,不覆盖用户的修改;
-
-### 优化
-- 命令行帮助改用分组结构,按「命令」「选项」分节,子说明以 `- ` 前缀对齐,便于区分每个命令的注释边界;
-- 帮助与运行输出统一使用 chalk 按语义着色:`用法:` 用 `blueBright`,分组名用 `cyan`,
-  命令与选项名用 `cyanBright`,说明用 `gray`,成功用 `green` 与 `greenBright`,错误用 `red`;
-- `scripts/copy-files.js` 的输出改用同套着色,移除 emoji 前缀;
-- 未知命令分支由逗号链跨行改为分号结束的多行块,符合行宽与语句分隔规则;
-
-### 修复
-- 指南文件名由 `Android 构建指南.md` 改为 `Android构建指南.md`,去除空格;
-  README 中的链接同步去除 `%20` 编码,此前指向不存在的路径;
-
-### 文档
-- README 命令列表与 `mobileAppConfig.js` 的「常用命令」注释补 `example`;
-- README 包目录结构按 `files` 字段顺序重排;
+- 细节优化;

package/README.md

@@ -14,6 +14,8 @@
 - **自动识别服务地址**:拦截 `server.js` 里的 `listen()` 调用,动态获取真实协议和端口
 - **失败可见**:5 秒内未启动,加载异常,App 显示错误页并支持展开详情(开发者可查)
 - **增量构建**:文件指纹判断缓存,无变化时 10 秒级重跑
+- **内置镜像探测 + 可自定义**:Gradle 发行版默认走腾讯云,未配置时按腾讯、阿里、官方顺序探测;Maven 仓库默认
+  阿里云 public/google/gradle-plugin 加官方源,两者均可在 `mobileAppConfig.js` 里自定义;
 - **跨平台**:Android(Windows / macOS / Linux)+ iOS(仅 macOS)
 - **离线可用**:`build` 打出的 APK / IPA 内置 JS,无需连电脑也能跑
 - **node_modules 优化(默认开启)**:构建时先交叉编译原生模块,再自动执行六阶段优化--先清空 postinstall 资源(保留 js 供合并),
@@ -154,7 +156,7 @@ npm i -D @flun/node-mobile-app
 ### 快速开始
 
 ```bash
-# 1. 编辑配置:打开 mobileAppConfig.js,改 appId / appName / serverPath 等
+# 1. 编辑配置:打开 mobileAppConfig.js,改必填项 serverPath 或完整自定义;
 
 # 2. 开发调试(需 adb 可连的设备,走 Metro 热更新)
 npx node-mobile-app test
@@ -231,9 +233,28 @@ adb install -r "./out/myapp-1.0.0-release.apk"
 
 ## 参考配置
 
-所有定制集中在这一个文件;**不配置也能跑**(用默认值);
+所有定制集中在这一个文件;`serverPath` 字段值是必填项;
 
-### 必填
+### 入口与标识
+
+- `serverPath`
+  - 类型:`string`
+  - 默认:`'./server.js'`
+  - 说明:Node.js 启动脚本路径,指向的文件必须存在
+- `appId`
+  - 类型:`string`
+  - 默认:`'com.example.app'`
+  - 说明:应用唯一标识(反向域名格式,Android/iOS 通用)
+- `versionCode`
+  - 类型:`int`
+  - 默认:`1`
+  - 说明:内部版本号,必须为正整数
+
+构建前会校验以下项,不满足即报错:用户项目根必须有 `package.json`;`appId` 需为反向域名格式;
+`versionCode` 需为正整数;`android.abiFilters` 不能为空;`android.gradleDistributionUrl` 与
+`android.mavenRepositories` 若配置,格式不合法也会报错(见 Android 章节).
+
+### 应用信息
 
 - `appName`
   - 类型:`string \| null`
@@ -243,35 +264,44 @@ adb install -r "./out/myapp-1.0.0-release.apk"
   - 类型:`string \| null`
   - 默认:`null`
   - 说明:APK / IPA 输出目录(默认 `./out`)
-- `showLoading`
+- `versionName`
+  - 类型:`string`
+  - 默认:`'1.0.0'`
+  - 说明:用户可见版本名(Android versionName / iOS CFBundleShortVersionString)
+
+### WebView
+
+以下字段均位于 `webview` 对象下:
+
+- `webview.showLoading`
   - 类型:`boolean`
   - 默认:`true`
   - 说明:是否显示加载指示器
-- `loadingText`
+- `webview.loadingText`
   - 类型:`string`
   - 默认:`'正在启动服务...'`
   - 说明:加载提示文字
-- `enableJavaScript`
+- `webview.enableJavaScript`
   - 类型:`boolean`
   - 默认:`true`
   - 说明:是否启用 JavaScript
-- `enableDomStorage`
+- `webview.enableDomStorage`
   - 类型:`boolean`
   - 默认:`true`
   - 说明:是否启用 DOM Storage
-- `allowFileAccess`
+- `webview.allowFileAccess`
   - 类型:`boolean`
   - 默认:`true`
   - 说明:是否允许访问本地文件
-- `mixedContentMode`
+- `webview.mixedContentMode`
   - 类型:`string`
   - 默认:`'always'`
   - 说明:混合内容模式:`never` / `always` / `compatibility`
-- `backgroundColor`
+- `webview.backgroundColor`
   - 类型:见下
   - 默认:`'#ffffff'`
   - 说明:WebView 背景色;支持:固定色 `'#ffffff'` / 跟随系统 `'system'` / 深浅两值 `{ light, dark }`
-- `allowSelfSignedCert`
+- `webview.allowSelfSignedCert`
   - 类型:`boolean`
   - 默认:`false`
   - 说明:见下文"HTTPS 自签证书"
@@ -302,6 +332,16 @@ adb install -r "./out/myapp-1.0.0-release.apk"
   - 类型:`string`
   - 默认:`'37.0.0'`
   - 说明:构建工具版本
+- `gradleDistributionUrl`
+  - 类型:`string \| null`
+  - 默认:`null`
+  - 说明:Gradle 发行版的完整下载地址.未配置时按腾讯、阿里、官方顺序探测,三者均不可达则回落官方并警告;
+    已配置时直接使用,失败不回退,并提示可改回 `null` 或换可达地址
+- `mavenRepositories`
+  - 类型:`string[] \| null`
+  - 默认:`null`
+  - 说明:自定义 Maven 仓库数组,同时替换 `settings.gradle` 与根 `build.gradle` 的仓库列表;未配置时保持模板默认
+    (阿里云 `public`/`google`/`gradle-plugin` + 官方 `google`/`mavenCentral`)
 - `abiFilters`
   - 类型:`string[]`
   - 默认:`['arm64-v8a']`
@@ -591,14 +631,28 @@ adb logcat | grep -E "NODEJS-MOBILE|ReactNativeJS"
 ### Q:Android 构建卡在拉取依赖(`react-android` / `hermes-android` 等)?
 
 Android 模板的 `settings.gradle` 与 `build.gradle` 已在 `google()` / `mavenCentral()` 之前插入阿里云镜像,
-国内网络优先走镜像;海外网络镜像不命中会自动回退官方源,不影响功能.
+中国网络优先走镜像;海外网络镜像不命中会自动回退官方源,不影响功能.
 
 若仍卡住:
 
 - 检查镜像可达:浏览器打开 `https://maven.aliyun.com/repository/public` 是否正常;
 - 检查本机 `~/.gradle/init.gradle` 是否有与仓库顺序冲突的配置(如强制替换仓库),有则临时移除以排除干扰;
+- 若所在网络对默认镜像均不友好,可在 `mobileAppConfig.js` 里配置 `android.mavenRepositories` 指定自己的仓库数组,
+  配置后会完全替换模板默认仓库,未配置则保持模板默认;
 - 停掉残留 Daemon 后重试:在 `node-mobile-app-build/android/` 下执行 `gradlew --stop`,再重跑 `test` / `build`.
 
+### Q:Android 构建卡在下载 Gradle 发行版(`gradle-*-bin.zip`)?
+
+Gradle Wrapper 下载发行版走单个 `distributionUrl`,没有多 URL 自动回退机制.默认模板指向腾讯云镜像,
+中国网络可直接使用.若卡住:
+
+- 直接配置完整地址:`android.gradleDistributionUrl` 填一个可达的 `gradle-*-bin.zip` 地址;
+  配置后不再探测,失败不回退,会提示改回 `null` 或换可达地址;
+- 交回自动探测:把 `android.gradleDistributionUrl` 设为 `null`,工具会按腾讯、阿里、官方顺序探测,
+  三者均不可达时回落官方并警告;
+- Wrapper 只对单个 URL 做重试,不会在多个地址间切换;若地址本身不可达,换地址或改回 `null` 走探测才是有效手段;
+- 已下载完成的部分会留在 `~/.gradle/wrapper/dists/` 下,下次构建复用,不会重复下载.
+
 ### Q:Express 版本怎么选?
 
 - **Android**:内置完整 ICU(full-icu)→ 可以用 Express 5
@@ -658,6 +712,6 @@ ISC
 ## 贡献
 
 - 源码:[GitHub](https://github.com/OpenFlun/node-mobile-app)
-- 中国:[gitee](https://gitee.com/OpenFlun/node-mobile-app)
+- 中国镜像:[gitee](https://gitee.com/OpenFlun/node-mobile-app)
 - 问题反馈:[Issues](https://github.com/OpenFlun/node-mobile-app/issues)
 - 主页:[npm 包页面](https://www.npmjs.com/package/@flun/node-mobile-app#readme)

package/bin/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import chalk from 'chalk';
-import { runTest } from '../src/commands/test.js';
+import { copyFile } from '../scripts/copy-files.js';
 import { runBuild } from '../src/commands/build.js';
 import { runClean } from '../src/commands/clean.js';
-import { copyFile } from '../scripts/copy-files.js';
+import { runTest } from '../src/commands/test.js';
 
 // 输出用法;
 const printHelp = () => {
@@ -34,7 +34,7 @@ const printHelp = () => {
   /**
    * 解析 --key value 参数,重复键覆盖为后者;
    * @param {string[]} args 子命令后的参数
-   * @returns {Object} 解析结果
+   * @returns {object} 解析结果
    */
   parseFlags = args => {
     const f = {};

package/mobileAppConfig.js

@@ -20,8 +20,10 @@
  *   App 使用该地址加载页面,无需在此配置;
  *   若 5 秒内未能识别,App 显示启动失败并可在页面展开详情查看原因;
  *   动态端口(listen(0))会自动获取系统分配的真实端口;
+ *
+ * >查看定义:@see {@link mobileAppConfig}
  */
-export default {
+const mobileAppConfig = {
   // ===== 必填 =====
   serverPath: './server.js',            // Node.js 启动脚本路径
 
@@ -63,6 +65,15 @@ export default {
     targetSdkVersion: 36,             // 目标 SDK
     compileSdkVersion: 37,            // 编译 SDK
     buildToolsVersion: '37.0.0',      // 构建工具版本
+    gradleDistributionUrl: null,      // 下载地址,示例:'https://mirrors.cloud.tencent.com/gradle/gradle-9.5.1-bin.zip'
+    // Maven 仓库,用于 buildscript 插件与 allprojects 依赖;按顺序尝试,失败回退下一个
+    // 未配置时使用内置默认:阿里云 public/google/gradle-plugin + 官方 google/mavenCentral
+    mavenRepositories: null,          // 示例见下,按需取消注释
+    // mavenRepositories: [
+    //   'https://maven.aliyun.com/repository/public',         // Maven Central:通用开源库
+    //   'https://maven.aliyun.com/repository/google',         // Google Maven:AGP、AndroidX
+    //   'https://maven.aliyun.com/repository/gradle-plugin',  // Gradle 插件门户:插件本体
+    // ],
     abiFilters: ['arm64-v8a'],        // 打包架构(真机用 arm64-v8a, 模拟器加 x86_64)
     icon: './build/icon.png',         // 应用图标(建议 512x512 PNG)
     usesCleartextTraffic: true,       // 是否允许明文流量(http)
@@ -141,7 +152,7 @@ export default {
     '.vscode/',
     '.idea/',
     '.vs/',
-    'node_modules/',                  // 如需保留请删除此行
+    'node_modules/',
     'sessions/',
     'users.json',
     '.env',
@@ -163,5 +174,7 @@ export default {
     'unrs-resolver': true,
     '@parcel/watcher': true,
     'bcrypt': true,
-  },
-};
+  }
+};
+
+export default mobileAppConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flun/node-mobile-app",
-  "version": "4.1.2",
+  "version": "4.2.0",
   "description": "将 Node.js 项目一键打包为 Android / iOS 移动应用,运行时由 @flun/nodejs-mobile-react-native 提供;",
   "author": "flun <open@flun.top>",
   "keywords": [

package/scripts/copy-files.js

@@ -1,6 +1,6 @@
+import chalk from 'chalk';
 import fs from 'fs';
 import path from 'path';
-import chalk from 'chalk';
 import { fileURLToPath } from 'url';
 
 // 要复制的文件位置、目标目录和目标文件路径
@@ -10,7 +10,8 @@ const __filename = fileURLToPath(import.meta.url), __dirname = path.dirname(__fi
 
 /**
  * 复制配置文件到项目根目录
- * @returns {boolean} - 复制是否成功
+ * >查看定义:@see {@link copyFile}
+ * @returns {boolean} 复制是否成功
  */
 const copyFile = () => {
     console.log(chalk.gray('项目根目录: ') + targetDir);

package/src/commands/build.js

@@ -1,120 +1,126 @@
-import path from 'path';
+import chalk from 'chalk';
 import fs from 'fs';
+import path from 'path';
 import { fileURLToPath } from 'url';
 import { loadConfig, validateConfig } from '../config.js';
 import {
-  getBuildDir, copyTemplate, copyUserProject, writeLocalProperties, ensureUserEntry, ensureUserConfig, patchAndroidAbi,
-  patchExtraRnDependencies
+  copyTemplate, copyUserProject, ensureUserConfig, ensureUserEntry, getBuildDir, patchAndroidAbi,
+  patchExtraRnDependencies, writeLocalProperties
 } from '../copy.js';
+import { checkAndResetCache } from '../fingerprint.js';
+import { generateMainJs, generateRuntime } from '../generate.js';
 import { installUserDeps, patchNodejsMobilePlugin, patchWebViewSsl } from '../install.js';
 import { markVerified } from '../optimize-node-modules.js';
-import { generateMainJs, generateRuntime } from '../generate.js';
-import { checkAndResetCache } from '../fingerprint.js';
 import {
-  patchAppConfig, patchAndroidConfig, patchSigning, patchIcon, patchIosConfig, patchIosIcon, resolveAppName
+  patchAndroidConfig, patchAppConfig, patchIcon, patchIosConfig, patchIosIcon, patchMavenRepositories,
+  patchSigning, resolveAppName
 } from '../patcher.js';
-import { ensureMac, checkIosTools, podInstall, xcodebuildArchive, xcodebuildExport } from '../platform-ios.js';
-import { run, ensureDir, sanitizeFileName } from '../utils.js';
-import chalk from 'chalk';
+import { checkIosTools, ensureMac, podInstall, xcodebuildArchive, xcodebuildExport } from '../platform-ios.js';
+import { ensureDir, run, sanitizeFileName, warnGradleDownloadHint } from '../utils.js';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+/**
+ * 构建桌面应用:读取配置、校验、生成工程、安装依赖、编译、打包
+ * >查看定义:@see {@link runBuild}
+ * @param {object} flags 命令行参数,含 ios / release
+ * @returns {Promise<void>}
+ */
+const runBuild = async (flags) => {
+  const userProjectDir = process.cwd(), release = !!flags.release, isIos = !!flags.ios, total = isIos ? 8 : 7;
+
+  console.log(chalk.cyan(
+    `\n=== node-mobile-app build (${isIos ? 'iOS' : 'Android'}, ${release ? 'release' : 'debug'}) ===\n`
+  ));
+  console.log(chalk.gray('用户项目: ' + userProjectDir));
+  if (isIos) ensureMac(), checkIosTools();
+  console.log(chalk.cyan(`\n[1/${total}] 检查用户配置与入口文件`)), ensureUserConfig(userProjectDir, PKG_ROOT);
+
+  const config = await loadConfig(userProjectDir);
+  ensureUserEntry(userProjectDir, config, PKG_ROOT), validateConfig(config, userProjectDir);
+
+  const buildDir = getBuildDir(userProjectDir);
+  console.log(chalk.cyan(`\n[2/${total}] 重置 RN 工程模板`));
+  await copyTemplate(PKG_ROOT, buildDir, config);
+  patchAndroidAbi(buildDir, config);
+  patchExtraRnDependencies(buildDir, userProjectDir, config);
+  patchAppConfig(buildDir, userProjectDir, config);
+  patchAndroidConfig(buildDir, config), patchMavenRepositories(buildDir, config);
+  patchSigning(buildDir, userProjectDir, config);
+  await patchIcon(buildDir, userProjectDir, config);
+  patchIosConfig(buildDir, userProjectDir, config);
+  await patchIosIcon(buildDir, userProjectDir, config);
+
+  console.log(chalk.cyan(`\n[3/${total}] 检查缓存指纹`)), checkAndResetCache(buildDir, userProjectDir, config, PKG_ROOT);
+  console.log(chalk.cyan(`\n[4/${total}] 复制用户项目`));
+  const { moduleType, targetDir } = copyUserProject(userProjectDir, buildDir, config);
+  console.log(chalk.cyan(`\n[5/${total}] 安装依赖与编译优化`));
+  await installUserDeps(targetDir, userProjectDir, config, buildDir, isIos ? 'ios' : 'android');
+  patchNodejsMobilePlugin(userProjectDir, config);
+  patchWebViewSsl(userProjectDir, config);
+  writeLocalProperties(buildDir, config);
+
+  console.log(chalk.cyan(`\n[6/${total}] 生成桥接文件`));
+  generateMainJs(targetDir, config, moduleType), generateRuntime(buildDir, config);
+
+  const appName = resolveAppName(userProjectDir, config), safeName = sanitizeFileName(appName),
+    outDir = path.resolve(userProjectDir, config.outputDir || './out');
+  ensureDir(outDir);
+
+  if (isIos) {
+    console.log(chalk.cyan(`\n[7/${total}] pod install`)), podInstall(path.join(buildDir, 'ios'));
+    console.log(chalk.cyan(`\n[8/${total}] xcodebuild archive + export`));
+    xcodebuildArchive(buildDir, config, release, userProjectDir);
+
+    const ipaPath = xcodebuildExport(buildDir, config, release, outDir, userProjectDir),
+      dstName = `${safeName}-${config.versionName}-${release ? 'release' : 'debug'}.ipa`,
+      dst = path.join(outDir, dstName);
+    fs.copyFileSync(ipaPath, dst), console.log(chalk.green('\n✅ 打包完成'));
+
+    const mb = (fs.statSync(dst).size / 1024 / 1024).toFixed(1);
+    console.log(chalk.gray(`  ${dst}  (${mb} MB)`)), await markVerified(buildDir);
+    return;
+  }
 
-const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..'),
-  runBuild = async (flags) => {
-    const userProjectDir = process.cwd(), release = !!flags.release, isIos = !!flags.ios, total = isIos ? 8 : 7;
-
-    console.log(chalk.cyan(
-      `\n=== node-mobile-app build (${isIos ? 'iOS' : 'Android'}, ${release ? 'release' : 'debug'}) ===\n`
-    ));
-    console.log(chalk.gray('用户项目: ' + userProjectDir));
-    if (isIos) ensureMac(), checkIosTools();
-    console.log(chalk.cyan(`\n[1/${total}] 检查用户配置与入口文件`)), ensureUserConfig(userProjectDir, PKG_ROOT);
-
-    const config = await loadConfig(userProjectDir);
-    ensureUserEntry(userProjectDir, config, PKG_ROOT), validateConfig(config, userProjectDir);
-
-    const buildDir = getBuildDir(userProjectDir);
-    console.log(chalk.cyan(`\n[2/${total}] 重置 RN 工程模板`));
-    copyTemplate(PKG_ROOT, buildDir, config);
-    patchAndroidAbi(buildDir, config);
-    patchExtraRnDependencies(buildDir, userProjectDir, config);
-    patchAppConfig(buildDir, userProjectDir, config);
-    patchAndroidConfig(buildDir, config);
-    patchSigning(buildDir, userProjectDir, config);
-    await patchIcon(buildDir, userProjectDir, config);
-    patchIosConfig(buildDir, userProjectDir, config);
-    await patchIosIcon(buildDir, userProjectDir, config);
-
-    console.log(chalk.cyan(`\n[3/${total}] 检查缓存指纹`)), checkAndResetCache(buildDir, userProjectDir, config, PKG_ROOT);
-    console.log(chalk.cyan(`\n[4/${total}] 复制用户项目`));
-    const { moduleType, targetDir } = copyUserProject(userProjectDir, buildDir, config);
-    console.log(chalk.cyan(`\n[5/${total}] 安装依赖与编译优化`));
-    await installUserDeps(targetDir, userProjectDir, config, buildDir, isIos ? 'ios' : 'android');
-    patchNodejsMobilePlugin(userProjectDir, config);
-    patchWebViewSsl(userProjectDir, config);
-    writeLocalProperties(buildDir, config);
-
-    console.log(chalk.cyan(`\n[6/${total}] 生成桥接文件`));
-    generateMainJs(targetDir, config, moduleType), generateRuntime(buildDir, config);
-
-    const appName = resolveAppName(userProjectDir, config), safeName = sanitizeFileName(appName),
-      outDir = path.resolve(userProjectDir, config.outputDir || './out');
-    ensureDir(outDir);
-
-    if (isIos) {
-      console.log(chalk.cyan(`\n[7/${total}] pod install`)), podInstall(path.join(buildDir, 'ios'));
-      console.log(chalk.cyan(`\n[8/${total}] xcodebuild archive + export`)),
-        xcodebuildArchive(buildDir, config, release, userProjectDir);
-
-      const ipaPath = xcodebuildExport(buildDir, config, release, outDir, userProjectDir),
-        dstName = `${safeName}-${config.versionName}-${release ? 'release' : 'debug'}.ipa`,
-        dst = path.join(outDir, dstName);
-      fs.copyFileSync(ipaPath, dst), console.log(chalk.green('\n✅ 打包完成'));
+  console.log(chalk.cyan(`\n[7/${total}] 打包 APK`));
+  if (!process.env.OPTIMIZE_DEBUG) console.log(chalk.gray('  打包进行中...'));
+  const assetsDir = path.join(buildDir, 'android', 'app', 'src', 'main', 'assets'),
+    resDir = path.join(buildDir, 'android', 'app', 'src', 'main', 'res');
 
-      const mb = (fs.statSync(dst).size / 1024 / 1024).toFixed(1);
-      console.log(chalk.gray(`  ${dst}  (${mb} MB)`));
-      await markVerified(buildDir);
-      return;
-    }
+  ensureDir(assetsDir);
+  run('npx', [
+    'react-native', 'bundle', '--platform', 'android', '--dev', release ? 'false' : 'true',
+    '--entry-file', 'index.js', '--bundle-output',
+    path.join(assetsDir, 'index.android.bundle'), '--assets-dest', resDir,
+  ], { cwd: buildDir, quiet: true });
 
-    console.log(chalk.cyan(`\n[7/${total}] 打包 APK`));
-    if (!process.env.OPTIMIZE_DEBUG) console.log(chalk.gray('  打包进行中...'));
-    const assetsDir = path.join(buildDir, 'android', 'app', 'src', 'main', 'assets'),
-      resDir = path.join(buildDir, 'android', 'app', 'src', 'main', 'res');
-
-    ensureDir(assetsDir);
-    run('npx', [
-      'react-native', 'bundle',
-      '--platform', 'android',
-      '--dev', release ? 'false' : 'true',
-      '--entry-file', 'index.js',
-      '--bundle-output', path.join(assetsDir, 'index.android.bundle'),
-      '--assets-dest', resDir,
-    ], { cwd: buildDir, quiet: true });
-
-    const task = release ? 'assembleRelease' : 'assembleDebug', gradleArgs = [task];
-    if (flags.arch) gradleArgs.push(`-PreactNativeArchitectures=${flags.arch}`);
-
-    const gradlew = process.platform === 'win32' ? 'gradlew.bat' : './gradlew';
+  const task = release ? 'assembleRelease' : 'assembleDebug', gradleArgs = [task];
+  if (flags.arch) gradleArgs.push(`-PreactNativeArchitectures=${flags.arch}`);
+
+  const gradlew = process.platform === 'win32' ? 'gradlew.bat' : './gradlew';
+  try {
     run(gradlew, gradleArgs, { cwd: path.join(buildDir, 'android'), quiet: true });
+  } catch (err) {
+    warnGradleDownloadHint(config); throw err;
+  }
 
-    const apkDir = path.join(buildDir, 'android', 'app', 'build', 'outputs', 'apk', release ? 'release' : 'debug');
-    console.log(chalk.green('\n✅ 打包完成'));
+  const apkDir = path.join(buildDir, 'android', 'app', 'build', 'outputs', 'apk', release ? 'release' : 'debug');
+  console.log(chalk.green('\n✅ 打包完成'));
 
-    if (fs.existsSync(apkDir)) {
-      const apks = fs.readdirSync(apkDir).filter((f) => f.endsWith('.apk'));
-      if (apks.length === 0) console.log(chalk.yellow('  ⚠️  未找到 APK'));
+  if (fs.existsSync(apkDir)) {
+    const apks = fs.readdirSync(apkDir).filter((f) => f.endsWith('.apk'));
+    if (apks.length === 0) console.log(chalk.yellow('  ⚠️  未找到 APK'));
 
-      for (const f of apks) {
-        const src = path.join(apkDir, f),
-          dstName = `${safeName}-${config.versionName}-${release ? 'release' : 'debug'}.apk`,
-          dst = path.join(outDir, dstName);
+    for (const f of apks) {
+      const dstName = `${safeName}-${config.versionName}-${release ? 'release' : 'debug'}.apk`,
+        dst = path.join(outDir, dstName), src = path.join(apkDir, f);
 
-        fs.copyFileSync(src, dst);
-        const mb = (fs.statSync(dst).size / 1024 / 1024).toFixed(1);
-        console.log(chalk.gray(`  ${dst}  (${mb} MB)`));
-      }
+      fs.copyFileSync(src, dst);
+      const mb = (fs.statSync(dst).size / 1024 / 1024).toFixed(1);
+      console.log(chalk.gray(`  ${dst}  (${mb} MB)`));
     }
-    else console.log(chalk.yellow('  ⚠️  未找到 APK 输出目录: ' + apkDir));
-    await markVerified(buildDir);
   }
+  else console.log(chalk.yellow('  ⚠️  未找到 APK 输出目录: ' + apkDir));
+  await markVerified(buildDir);
+};
 
 export { runBuild };

package/src/commands/clean.js

@@ -1,9 +1,14 @@
-import path from 'path';
+import chalk from 'chalk';
 import fs from 'fs';
-import { removeDir } from '../utils.js';
+import path from 'path';
 import { getBuildDir } from '../copy.js';
-import chalk from 'chalk';
+import { removeDir } from '../utils.js';
 
+/**
+ * 清理构建缓存:构建目录、插件构建缓存、插件 CMake 缓存
+ * >查看定义:@see {@link runClean}
+ * @returns {Promise<void>}
+ */
 const runClean = async () => {
   const userProjectDir = process.cwd(), buildDir = getBuildDir(userProjectDir),
     targets = [
@@ -19,9 +24,10 @@ const runClean = async () => {
     ];
 
   for (const t of targets) {
-    if (fs.existsSync(t.path))
-      removeDir(t.path),
-        console.log(chalk.green('已清理: ' + t.label + ' -> ' + (path.relative(userProjectDir, t.path) || t.path)));
+    if (fs.existsSync(t.path)) {
+      removeDir(t.path);
+      console.log(chalk.green('已清理: ' + t.label + ' -> ' + (path.relative(userProjectDir, t.path) || t.path)));
+    }
     else console.log(chalk.gray('跳过(不存在): ' + t.label));
   }