@flun/node-mobile-app 4.1.2 → 4.2.0

package/src/commands/test.js

@@ -1,148 +1,153 @@
-import path from 'path';
+import chalk from 'chalk';
+import { createHash } from 'crypto';
 import fs from 'fs';
+import http from 'http';
+import path from 'path';
 import { fileURLToPath } from 'url';
 import { loadConfig, validateConfig } from '../config.js';
-import { createHash } from 'crypto';
-import http from 'http';
 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 } from '../patcher.js';
-import { ensureMac, checkIosTools, podInstall } from '../platform-ios.js';
 import {
-  run, runSilent, runStream, findAdb, ensureDir, findHermesc, ensureInstallable, writeInstallState, spawnCmdAsync
+  patchAndroidConfig, patchAppConfig, patchIcon, patchIosConfig, patchIosIcon, patchMavenRepositories,
+  patchSigning
+} from '../patcher.js';
+import { checkIosTools, ensureMac, podInstall } from '../platform-ios.js';
+import {
+  ensureDir, ensureInstallable, findAdb, findHermesc, run, runSilent, runStream, spawnCmdAsync,
+  warnGradleDownloadHint, writeInstallState
 } from '../utils.js';
-import chalk from 'chalk';
 
-const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..'),
-  runTest = async flags => {
-    const userProjectDir = process.cwd(), isIos = !!flags.ios, total = isIos ? 9 : 11;
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+/**
+ * 编译并安装到设备;走 Metro 热更新,支持 --ios 与 --device
+ * >查看定义:@see {@link runTest}
+ * @param {object} flags 命令行参数,含 ios / device
+ * @returns {Promise<void>}
+ */
+const runTest = async flags => {
+  const userProjectDir = process.cwd(), isIos = !!flags.ios, total = isIos ? 9 : 11;
 
-    console.log(chalk.cyan(`\n=== node-mobile-app test (${isIos ? 'iOS' : 'Android'}) ===\n`));
-    console.log(chalk.gray('用户项目: ' + userProjectDir));
-    if (isIos) ensureMac(), checkIosTools();
-    console.log(chalk.cyan(`\n[1/${total}] 检查用户配置与入口文件`)), ensureUserConfig(userProjectDir, PKG_ROOT);
+  console.log(chalk.cyan(`\n=== node-mobile-app test (${isIos ? 'iOS' : 'Android'}) ===\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 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);
+  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[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[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);
+  console.log(chalk.cyan(`\n[6/${total}] 生成桥接文件`));
+  generateMainJs(targetDir, config, moduleType), generateRuntime(buildDir, config);
 
-    if (isIos) {
-      console.log(chalk.cyan(`\n[7/${total}] pod install`)), podInstall(path.join(buildDir, 'ios'));
-      console.log(chalk.cyan(`\n[8/${total}] 生成 JS bundle + Hermes 字节码(由 Xcode Run Script 自动)`));
-      const bundlePath = path.join(buildDir, 'ios', 'main.jsbundle');
-      runSilent('npx', [
-        'react-native', 'bundle',
-        '--platform', 'ios',
-        '--dev', 'false',
-        '--entry-file', 'index.js',
-        '--bundle-output', bundlePath,
-      ], { cwd: buildDir });
-      console.log(chalk.green('    ✓ bundle 已生成'));
+  if (isIos) {
+    console.log(chalk.cyan(`\n[7/${total}] pod install`)), podInstall(path.join(buildDir, 'ios'));
+    console.log(chalk.cyan(`\n[8/${total}] 生成 JS bundle + Hermes 字节码(由 Xcode Run Script 自动)`));
+    const bundlePath = path.join(buildDir, 'ios', 'main.jsbundle');
+    runSilent('npx', [
+      'react-native', 'bundle', '--platform', 'ios', '--dev', 'false',
+      '--entry-file', 'index.js', '--bundle-output', bundlePath,
+    ], { cwd: buildDir });
+    console.log(chalk.green('    ✓ bundle 已生成'));
 
-      console.log(chalk.cyan(`\n[9/${total}] 编译并安装到模拟器/设备`));
-      const args = ['react-native', 'run-ios'];
-      if (flags.device) args.push('--device', flags.device);
-      // FORCE_BUNDLING=1:即使 Debug+模拟器也把 main.jsbundle 打进 App
-      const env = { ...process.env, FORCE_BUNDLING: '1', NODE_MOBILE_MODE: 'test' };
-      run('npx', args, { cwd: buildDir, env, inherit: true });
-      await markVerified(buildDir);
-    } else {
-      console.log(chalk.cyan(`\n[7/${total}] 生成 JS bundle(离线可用)`));
-      const assetsDir = path.join(buildDir, 'android', 'app', 'src', 'main', 'assets'),
-        resDir = path.join(buildDir, 'android', 'app', 'src', 'main', 'res');
-      ensureDir(assetsDir);
+    console.log(chalk.cyan(`\n[9/${total}] 编译并安装到模拟器/设备`));
+    const args = ['react-native', 'run-ios'];
+    if (flags.device) args.push('--device', flags.device);
+    // FORCE_BUNDLING=1:即使 Debug+模拟器也把 main.jsbundle 打进 App
+    const env = { ...process.env, FORCE_BUNDLING: '1', NODE_MOBILE_MODE: 'test' };
+    run('npx', args, { cwd: buildDir, env, inherit: true });
+    await markVerified(buildDir);
+  } else {
+    console.log(chalk.cyan(`\n[7/${total}] 生成 JS bundle(离线可用)`));
+    const assetsDir = path.join(buildDir, 'android', 'app', 'src', 'main', 'assets'),
+      resDir = path.join(buildDir, 'android', 'app', 'src', 'main', 'res');
+    ensureDir(assetsDir);
 
-      const bundlePath = path.join(assetsDir, 'index.android.bundle');
-      runSilent('npx', [
-        'react-native', 'bundle',
-        '--platform', 'android',
-        '--dev', 'false',
-        '--entry-file', 'index.js',
-        '--bundle-output', bundlePath,
-        '--assets-dest', resDir,
-      ], { cwd: buildDir });
-      console.log(chalk.green('    ✓ bundle 已生成'));
+    const bundlePath = path.join(assetsDir, 'index.android.bundle');
+    runSilent('npx', [
+      'react-native', 'bundle', '--platform', 'android', '--dev', 'false', '--entry-file', 'index.js',
+      '--bundle-output', bundlePath, '--assets-dest', resDir,
+    ], { cwd: buildDir });
+    console.log(chalk.green('    ✓ bundle 已生成'));
 
-      console.log(chalk.cyan(`\n[8/${total}] 编译 Hermes 字节码(加速离线启动)`));
-      const hermesc = findHermesc(userProjectDir);
-      if (hermesc) {
-        const hbcPath = bundlePath + '.hbc';
-        runSilent(hermesc, ['-emit-binary', '-out', hbcPath, bundlePath]);
-        fs.copyFileSync(hbcPath, bundlePath), fs.unlinkSync(hbcPath);
-        console.log(chalk.green('    ✓ 已替换为 Hermes 字节码'));
-      }
-      else console.warn(chalk.yellow('  ⚠️  未找到 hermesc,跳过字节码编译(离线启动会较慢)'));
+    console.log(chalk.cyan(`\n[8/${total}] 编译 Hermes 字节码(加速离线启动)`));
+    const hermesc = findHermesc(userProjectDir);
+    if (hermesc) {
+      const hbcPath = bundlePath + '.hbc';
+      runSilent(hermesc, ['-emit-binary', '-out', hbcPath, bundlePath]);
+      fs.copyFileSync(hbcPath, bundlePath), fs.unlinkSync(hbcPath);
+      console.log(chalk.green('    ✓ 已替换为 Hermes 字节码'));
+    }
+    else console.warn(chalk.yellow('  ⚠️  未找到 hermesc,跳过字节码编译(离线启动会较慢)'));
 
-      const mergedAsset = path.join(buildDir, 'android', 'app', 'build', 'intermediates', 'assets', 'debug',
-        'mergeDebugAssets', 'index.android.bundle');
-      if (fs.existsSync(mergedAsset)) {
-        const h = f => createHash('sha256').update(fs.readFileSync(f)).digest('hex');
-        if (h(bundlePath) !== h(mergedAsset)) {
-          fs.rmSync(path.dirname(mergedAsset), { recursive: true, force: true });
-          console.log(chalk.gray('  bundle 已变化,清理 mergeDebugAssets 缓存'));
-        }
+    const mergedAsset = path.join(buildDir, 'android', 'app', 'build', 'intermediates', 'assets', 'debug',
+      'mergeDebugAssets', 'index.android.bundle');
+    if (fs.existsSync(mergedAsset)) {
+      const h = f => createHash('sha256').update(fs.readFileSync(f)).digest('hex');
+      if (h(bundlePath) !== h(mergedAsset)) {
+        fs.rmSync(path.dirname(mergedAsset), { recursive: true, force: true });
+        console.log(chalk.gray('  bundle 已变化,清理 mergeDebugAssets 缓存'));
       }
-      console.log(chalk.cyan(`\n[9/${total}] 配置 adb 端口转发`));
-      const adb = findAdb(config);
-      console.log(chalk.gray('  adb: ' + adb)), run(adb, ['reverse', 'tcp:8081', 'tcp:8081'], { quiet: true });
+    }
+    console.log(chalk.cyan(`\n[9/${total}] 配置 adb 端口转发`));
+    const adb = findAdb(config);
+    console.log(chalk.gray('  adb: ' + adb)), run(adb, ['reverse', 'tcp:8081', 'tcp:8081'], { quiet: true });
 
-      const metroReady = () => new Promise(resolve => {
-        const req = http.get('http://localhost:8081/status', r => {
-          let d = '';
-          r.on('data', c => d += c);
-          r.on('end', () => resolve(d.includes('packager-status:running')));
-        });
-        req.on('error', () => resolve(false));
-        req.setTimeout(1000, () => { req.destroy(); resolve(false); });
+    const metroReady = () => new Promise(resolve => {
+      const req = http.get('http://localhost:8081/status', r => {
+        let d = '';
+        r.on('data', c => d += c);
+        r.on('end', () => resolve(d.includes('packager-status:running')));
       });
-      if (!await metroReady()) {
-        console.log(chalk.gray('  启动 Metro...'));
-        const metroLog = fs.openSync(path.join(buildDir, '.metro.log'), 'a'),
-          metro = spawnCmdAsync('npx', ['react-native', 'start'], {
-            cwd: buildDir, detached: true, stdio: ['ignore', metroLog, metroLog]
-          });
-        metro.unref();
-        let ready = false;
-        for (let i = 0; i < 60; i++) {
-          await new Promise(r => setTimeout(r, 500));
-          if (await metroReady()) {
-              ready = true, console.log(chalk.green('    ✓ Metro 已就绪(后台常驻,支持热更新)')); break;
-          }
+      req.on('error', () => resolve(false));
+      req.setTimeout(1000, () => { req.destroy(); resolve(false); });
+    });
+    if (!await metroReady()) {
+      console.log(chalk.gray('  启动 Metro...'));
+      const metroLog = fs.openSync(path.join(buildDir, '.metro.log'), 'a'),
+        metro = spawnCmdAsync('npx', ['react-native', 'start'], {
+          cwd: buildDir, detached: true, stdio: ['ignore', metroLog, metroLog]
+        });
+      metro.unref();
+      let ready = false;
+      for (let i = 0; i < 60; i++) {
+        await new Promise(r => setTimeout(r, 500));
+        if (await metroReady()) {
+          ready = true, console.log(chalk.green('    ✓ Metro 已就绪(后台常驻,支持热更新)')); break;
         }
-        if (!ready) console.log(chalk.yellow('  ⚠️  Metro 30 秒内未就绪,详见 .metro.log;app 将回落到本地 bundle'));
       }
-      console.log(chalk.cyan(`\n[10/${total}] 编译 Debug 包`));
-      const gradlew = process.platform === 'win32' ? 'gradlew.bat' : './gradlew';
+      if (!ready) console.log(chalk.yellow('  ⚠️  Metro 30 秒内未就绪,详见 .metro.log;app 将回落到本地 bundle'));
+    }
+    console.log(chalk.cyan(`\n[10/${total}] 编译 Debug 包`));
+    const gradlew = process.platform === 'win32' ? 'gradlew.bat' : './gradlew';
+    try {
       if (process.env.OPTIMIZE_DEBUG) await runStream(gradlew, ['assembleDebug'], {
-        cwd: path.join(buildDir, 'android'), env: { ...process.env, NODE_MOBILE_MODE: 'test' },
-        stdio: 'inherit'
+        cwd: path.join(buildDir, 'android'), env: { ...process.env, NODE_MOBILE_MODE: 'test' }, stdio: 'inherit'
       });
       else {
         console.log(chalk.gray('  编译中...'));
@@ -151,21 +156,24 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
         });
         console.log(chalk.green('    ✓ 编译完成'));
       }
-
-      console.log(chalk.cyan(`\n[11/${total}] 安装到设备`));
-      ensureInstallable(adb, config.appId, 'debug', buildDir, flags.device);
-      const apkDir = path.join(buildDir, 'android', 'app', 'build', 'outputs', 'apk', 'debug');
-      if (!fs.existsSync(apkDir)) console.error(chalk.red('  [错误] 未找到 APK 输出目录: ' + apkDir)), process.exit(1);
-      const apkPath = path.join(apkDir, 'app-debug.apk');
-      if (!fs.existsSync(apkPath)) console.error(chalk.red('  [错误] 未找到 app-debug.apk: ' + apkPath)), process.exit(1);
-      const devPrefix = flags.device ? ['-s', flags.device] : [];
-      run(adb, [...devPrefix, 'install', '-r', apkPath], { quiet: true });
-      console.log(chalk.green('    ✓ 已安装到设备'));
-      run(adb, [...devPrefix, 'shell', 'monkey', '-p', config.appId, '-c', 'android.intent.category.LAUNCHER', '1'],
-        { quiet: true });
-      writeInstallState(buildDir, { appId: config.appId, variant: 'debug', installedAt: new Date().toISOString() });
-      await markVerified(buildDir);
+    } catch (err) {
+      warnGradleDownloadHint(config); throw err;
     }
-  };
+
+    console.log(chalk.cyan(`\n[11/${total}] 安装到设备`));
+    ensureInstallable(adb, config.appId, 'debug', flags.device);
+    const apkDir = path.join(buildDir, 'android', 'app', 'build', 'outputs', 'apk', 'debug');
+    if (!fs.existsSync(apkDir)) console.error(chalk.red('  [错误] 未找到 APK 输出目录: ' + apkDir)), process.exit(1);
+    const apkPath = path.join(apkDir, 'app-debug.apk');
+    if (!fs.existsSync(apkPath)) console.error(chalk.red('  [错误] 未找到 app-debug.apk: ' + apkPath)), process.exit(1);
+    const devPrefix = flags.device ? ['-s', flags.device] : [];
+    run(adb, [...devPrefix, 'install', '-r', apkPath], { quiet: true });
+    console.log(chalk.green('    ✓ 已安装到设备'));
+    run(adb, [...devPrefix, 'shell', 'monkey', '-p', config.appId, '-c', 'android.intent.category.LAUNCHER', '1'],
+      { quiet: true });
+    writeInstallState(buildDir, { appId: config.appId, variant: 'debug', installedAt: new Date().toISOString() });
+    await markVerified(buildDir);
+  }
+};
 
 export { runTest };

package/src/config.js

@@ -1,8 +1,20 @@
-import path from 'path';
+import chalk from 'chalk';
 import fs from 'fs';
+import path from 'path';
 import { pathToFileURL } from 'url';
-import chalk from 'chalk';
 
+const merge = (def, user) => {
+  const out = { ...def };
+  for (const k of Object.keys(user)) {
+    if (user[k] && typeof user[k] === 'object' && !Array.isArray(user[k])) out[k] = merge(def[k] || {}, user[k]);
+    else if (user[k] !== undefined && user[k] !== null) out[k] = user[k];
+  }
+  return out;
+};
+/**
+ * 默认配置对象,用户未提供的字段使用此处默认值
+ * >查看定义:@see {@link DEFAULT_CONFIG}
+ */
 const DEFAULT_CONFIG = {
   serverPath: './server.js',
   appName: null,
@@ -27,6 +39,8 @@ const DEFAULT_CONFIG = {
     targetSdkVersion: 36,
     compileSdkVersion: 37,
     buildToolsVersion: '37.0.0',
+    gradleDistributionUrl: null,
+    mavenRepositories: null,
     abiFilters: ['arm64-v8a'],
     icon: './build/icon.png',
     usesCleartextTraffic: true,
@@ -57,57 +71,79 @@ const DEFAULT_CONFIG = {
   allowScripts: {
     'node': true,
   }
-},
-  merge = (def, user) => {
-    const out = { ...def };
-    for (const k of Object.keys(user)) {
-      if (user[k] && typeof user[k] === 'object' && !Array.isArray(user[k])) out[k] = merge(def[k] || {}, user[k]);
-      else if (user[k] !== undefined && user[k] !== null) out[k] = user[k];
-    }
-    return out;
-  },
-  loadConfig = async userProjectDir => {
-    for (const name of ['mobileAppConfig.js', 'mobileAppConfig.mjs', 'mobileAppConfig.cjs']) {
-      const p = path.join(userProjectDir, name);
-      if (fs.existsSync(p)) {
-        console.log(chalk.gray('  读取配置: ' + name));
-        const mod = await import(pathToFileURL(p).href);
-        return merge(DEFAULT_CONFIG, mod.default || mod);
-      }
-    }
-    console.log(chalk.yellow('未找到 mobileAppConfig.js,使用默认配置'));
-    return DEFAULT_CONFIG;
-  },
-  validateConfig = (config, userProjectDir) => {
-    const errors = [], entry = path.join(userProjectDir, config.serverPath);
-    if (!fs.existsSync(entry)) errors.push('serverPath 不存在: ' + config.serverPath);
+};
 
-    const pkg = path.join(userProjectDir, 'package.json');
-    if (!fs.existsSync(pkg)) errors.push('用户项目缺少 package.json');
-    // 极简防呆:至少 2 段、每段非空、只含 [a-zA-Z0-9_-],不允许首尾点或连续点
-    // 具体平台是否合法交给 Gradle / Xcode 报错(Android 不允许 -,iOS 允许)
-    if (typeof config.appId !== 'string' || !/^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)+$/.test(config.appId))
-      errors.push('appId 格式不合法(需反向域名格式,如 com.example.app): ' + config.appId);
-    if (!Number.isInteger(config.versionCode) || config.versionCode < 1) errors.push('versionCode 必须是正整数');
-    if (!config.android.abiFilters?.length) errors.push('android.abiFilters 不能为空');
-    if (errors.length) {
-      errors.forEach(e => console.error(chalk.red('  - ' + e)));
-      throw new Error('配置校验失败');
+/**
+ * 读取用户项目根的 mobileAppConfig.js,与默认配置深度合并
+ * >查看定义:@see {@link loadConfig}
+ * @param {string} userProjectDir 用户项目目录
+ * @returns {Promise<object>} 合并后的配置对象
+ */
+const loadConfig = async userProjectDir => {
+  for (const name of ['mobileAppConfig.js', 'mobileAppConfig.mjs', 'mobileAppConfig.cjs']) {
+    const p = path.join(userProjectDir, name);
+    if (fs.existsSync(p)) {
+      console.log(chalk.gray('  读取配置: ' + name));
+      const mod = await import(pathToFileURL(p).href);
+      return merge(DEFAULT_CONFIG, mod.default || mod);
     }
-    console.log(chalk.green('    ✓ 配置校验通过'));
-  },
-  resolveSdkPath = config => {
-    if (config.android && config.android.sdkPath) return config.android.sdkPath;
-    for (const env of ['ANDROID_HOME', 'ANDROID_SDK_ROOT']) {
-      const base = process.env[env];
-      if (base && fs.existsSync(base)) return base;
-    }
-    const localAppData = process.env.LOCALAPPDATA || '', home = process.env.USERPROFILE || process.env.HOME || '',
-      candidates = [path.join(localAppData, 'Android', 'Sdk'), path.join(home, 'Library', 'Android', 'sdk'),
-      path.join(home, 'Android', 'Sdk')];
+  }
+  console.log(chalk.yellow('未找到 mobileAppConfig.js,使用默认配置'));
+  return DEFAULT_CONFIG;
+};
+
+/**
+ * 定位 Android SDK 路径:配置 > 环境变量 > 默认路径
+ * >查看定义:@see {@link resolveSdkPath}
+ * @param {object} config 用户配置
+ * @returns {string|null} SDK 绝对路径,未找到时返回 null
+ */
+const resolveSdkPath = config => {
+  if (config.android && config.android.sdkPath) return config.android.sdkPath;
+  for (const env of ['ANDROID_HOME', 'ANDROID_SDK_ROOT']) {
+    const base = process.env[env];
+    if (base && fs.existsSync(base)) return base;
+  }
+  const localAppData = process.env.LOCALAPPDATA || '', home = process.env.USERPROFILE || process.env.HOME || '',
+    candidates = [path.join(localAppData, 'Android', 'Sdk'), path.join(home, 'Library', 'Android', 'sdk'),
+    path.join(home, 'Android', 'Sdk')];
 
-    for (const c of candidates) if (c && fs.existsSync(path.join(c, 'platform-tools'))) return c;
-    return null;
-  };
+  for (const c of candidates) if (c && fs.existsSync(path.join(c, 'platform-tools'))) return c;
+  return null;
+};
+
+/**
+ * 校验配置必填项与格式,失败时打印错误并抛出异常
+ * >查看定义:@see {@link validateConfig}
+ * @param {object} config 用户配置
+ * @param {string} userProjectDir 用户项目目录
+ * @returns {void}
+ */
+const validateConfig = (config, userProjectDir) => {
+  const errors = [], entry = path.join(userProjectDir, config.serverPath);
+  if (!fs.existsSync(entry)) errors.push('serverPath 不存在: ' + config.serverPath);
+
+  const pkg = path.join(userProjectDir, 'package.json');
+  if (!fs.existsSync(pkg)) errors.push('用户项目缺少 package.json');
+  // 极简防呆:至少 2 段、每段非空、只含 [a-zA-Z0-9_-],不允许首尾点或连续点
+  // 具体平台是否合法交给 Gradle / Xcode 报错(Android 不允许 -,iOS 允许)
+  if (typeof config.appId !== 'string' || !/^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)+$/.test(config.appId))
+    errors.push('appId 格式不合法(需反向域名格式,如 com.example.app): ' + config.appId);
+  if (!Number.isInteger(config.versionCode) || config.versionCode < 1) errors.push('versionCode 必须是正整数');
+  if (!config.android.abiFilters?.length) errors.push('android.abiFilters 不能为空');
+  if (config.android.gradleDistributionUrl && !/^https?:\/\/.+\.zip$/.test(config.android.gradleDistributionUrl))
+    errors.push('android.gradleDistributionUrl 必须是 http(s) 且以 .zip 结尾: ' + config.android.gradleDistributionUrl);
+  if (config.android.mavenRepositories != null && !Array.isArray(config.android.mavenRepositories))
+    errors.push('android.mavenRepositories 必须是数组或 null');
+  else if (Array.isArray(config.android.mavenRepositories)) {
+    const bad = config.android.mavenRepositories.filter(u => typeof u !== 'string' || !/^https?:\/\//.test(u));
+    if (bad.length) errors.push('android.mavenRepositories 存在非 http(s) 地址: ' + bad.join(', '));
+  }
+  if (errors.length) {
+    errors.forEach(e => console.error(chalk.red('  - ' + e)));
+    throw new Error('配置校验失败');
+  }
+  console.log(chalk.green('    ✓ 配置校验通过'));
+};
 
-export { DEFAULT_CONFIG, loadConfig, validateConfig, resolveSdkPath };
+export { DEFAULT_CONFIG, loadConfig, resolveSdkPath, validateConfig };