@flun/node-mobile-app 4.0.5 → 4.0.7

package/mobileAppConfig.js

@@ -5,20 +5,20 @@
  * 所有路径相对于用户项目根目录
  *
  * ===== 常用命令 =====
- *   npx node-mobile-app test            编译并安装到设备（需连 USB,走 Metro 热更新）
- *   npx node-mobile-app test --ios      iOS 版（仅 macOS）
- *   npx node-mobile-app build           打 debug APK（离线可用）
- *   npx node-mobile-app build --release 打 release APK（默认 debug keystore 签名,可安装；上架需配 android.signing）
- *   npx node-mobile-app build --ios     打 IPA（仅 macOS）
+ *   npx node-mobile-app test            编译并安装到设备(需连 USB,走 Metro 热更新)
+ *   npx node-mobile-app test --ios      iOS 版(仅 macOS)
+ *   npx node-mobile-app build           打 debug APK(离线可用)
+ *   npx node-mobile-app build --release 打 release APK(默认 debug keystore 签名,可安装;上架需配 android.signing)
+ *   npx node-mobile-app build --ios     打 IPA(仅 macOS)
  *   npx node-mobile-app clean           清理构建缓存
  *
- *   任意命令加 --debug 可显示详细日志（优化各阶段明细、各命令完整输出）
+ *   任意命令加 --debug 可显示详细日志(优化各阶段明细、各命令完整输出)
  *
  * ===== 服务地址说明 =====
- *   CLI 会自动识别 server.js 实际监听的协议和端口（拦截 listen 调用）,
+ *   CLI 会自动识别 server.js 实际监听的协议和端口(拦截 listen 调用),
  *   App 使用该地址加载页面,无需在此配置;
  *   若 5 秒内未能识别,App 显示启动失败并可在页面展开详情查看原因;
- *   动态端口（listen(0)）会自动获取系统分配的真实端口;
+ *   动态端口(listen(0))会自动获取系统分配的真实端口;
  */
 export default {
   // ===== 必填 =====
@@ -39,16 +39,16 @@ export default {
     enableDomStorage: true,           // 是否启用 DOM Storage(localStorage 等)
     allowFileAccess: true,            // 是否允许访问本地文件
     mixedContentMode: 'always',       // 混合内容模式:never / always / compatibility
-    // WebView 背景色,支持三种写法：
+    // WebView 背景色,支持三种写法:
     //   '#ffffff' / 'white'              固定色
-    //   'system'                         跟随系统（内部用默认浅/深色）
+    //   'system'                         跟随系统(内部用默认浅/深色)
     //   { light: '#fff', dark: '#1a1a1a' }  按系统主题切换
     backgroundColor: '#ffffff',
-    // 仅影响 HTTPS 场景下 App 是否加载自签证书的页面：
-    //   - 用 HTTP：与本开关无关
-    //   - 用 HTTPS + 真证书(如 Let's Encrypt)：与本开关无关
-    //   - 用 HTTPS + 自签证书 + 已装进设备信任库：与本开关无关
-    //   - 用 HTTPS + 自签证书 + 未装设备(本地测试最常见)：必须设为 true
+    // 仅影响 HTTPS 场景下 App 是否加载自签证书的页面:
+    //   - 用 HTTP:与本开关无关
+    //   - 用 HTTPS + 真证书(如 Let's Encrypt):与本开关无关
+    //   - 用 HTTPS + 自签证书 + 已装进设备信任库:与本开关无关
+    //   - 用 HTTPS + 自签证书 + 未装设备(本地测试最常见):必须设为 true
     // ⚠️ 开启后仅对 127.0.0.1 / localhost 放行不受信任的 HTTPS 证书,其他域名仍严格校验
     //    用于本地自签证书测试,生产环境建议关闭
     allowSelfSignedCert: false,
@@ -71,24 +71,24 @@ export default {
       // 'android.permission.CAMERA',
       // 'android.permission.READ_EXTERNAL_STORAGE',
     ],
-    // 签名配置（可选）
+    // 签名配置(可选)
     //
-    // 不配置也能打 release：模板默认用 debug keystore 签名（可安装、可本地测试,不可上架）;
-    // 需要上架时再配置下面任一种：
+    // 不配置也能打 release:模板默认用 debug keystore 签名(可安装、可本地测试,不可上架);
+    // 需要上架时再配置下面任一种:
     //
-    // 方式一：Android SDK 自带 debug keystore（本地测试常用）
+    // 方式一:Android SDK 自带 debug keystore(本地测试常用)
     //   keystore:       %USERPROFILE%\.android\debug.keystore   (Windows)
     //                   ~/.android/debug.keystore                 (macOS/Linux)
     //   storePassword:  'android'
     //   keyAlias:       'androiddebugkey'
     //   keyPassword:    'android'
     //
-    // 取消下方整块注释即视为「启用签名」,此时 4 项均为必填（缺项会在构建前报错）
+    // 取消下方整块注释即视为"启用签名",此时 4 项均为必填(缺项会在构建前报错)
     signing: {
-      // keystore:      './build/release.keystore', // 必填：keystore 路径（相对用户项目根）
-      // storePassword: '',                         // 必填：keystore 密码
-      // keyAlias:      '',                         // 必填：密钥别名
-      // keyPassword:   '',                         // 必填：密钥密码（与 storePassword 相同可填同值）
+      // keystore:      './build/release.keystore', // 必填:keystore 路径(相对用户项目根)
+      // storePassword: '',                         // 必填:keystore 密码
+      // keyAlias:      '',                         // 必填:密钥别名
+      // keyPassword:   '',                         // 必填:密钥密码(与 storePassword 相同可填同值)
     },
   },
 
@@ -97,10 +97,10 @@ export default {
   ios: {
     deploymentTarget: '15.1',         // 最低 iOS 版本(RN 0.87 要求 15.1+)
     icon: './build/icon.png',         // 应用图标(建议 1024x1024 PNG)
-    // 签名配置（仅 macOS,发布时必填）：
+    // 签名配置(仅 macOS,发布时必填):
     //   teamId              Apple Developer Team ID
-    //   provisioningProfile 描述文件路径（写入 exportOptions.plist）
-    //   certificate         P12 证书路径（导入临时 keychain 供 xcodebuild 签名用）
+    //   provisioningProfile 描述文件路径(写入 exportOptions.plist)
+    //   certificate         P12 证书路径(导入临时 keychain 供 xcodebuild 签名用)
     //   certificatePassword P12 密码
     signing: {
       // teamId: '',
@@ -120,14 +120,14 @@ export default {
   // 构建时合并 JS + 清空已复制到项目根的资源 + 清平台二进制 + 清开发文件,加速启动
   // 默认开启;若构建或运行异常,可按下述方式关闭或排除问题包
   optimize: {
-    enabled: true,                     // 是否启用（默认 true）
-    // exclude: ['包名'],              // 排除优化时异常或不想优化的包（默认空）
+    enabled: true,                     // 是否启用(默认 true)
+    // exclude: ['包名'],              // 排除优化时异常或不想优化的包(默认空)
   },
 
   // ===== 扩展点 =====
-  // 不重置的模板文件（路径相对于 node-mobile-app-build/,如 'android/app/src/main/AndroidManifest.xml'）
+  // 不重置的模板文件(路径相对于 node-mobile-app-build/,如 'android/app/src/main/AndroidManifest.xml')
   keepFiles: [],
-  // 额外 RN 原生依赖包名数组（用于 autolink 识别,含原生模块的包必须在此声明）
+  // 额外 RN 原生依赖包名数组(用于 autolink 识别,含原生模块的包必须在此声明)
   // 安装命令用 --save-dev,这些是开发依赖,不会进移动端 Node 环境
   // 示例: npm install --save-dev react-native-camera
   //       extraRnDependencies: ['react-native-camera']
@@ -163,4 +163,4 @@ export default {
     '@parcel/watcher': true,
     'bcrypt': true,
   },
-};
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flun/node-mobile-app",
-  "version": "4.0.5",
-  "description": "将 Node.js 项目一键打包为 Android / iOS 移动应用,运行时由 @flun/nodejs-mobile-react-native 提供,无需修改你的 Node 代码;",
+  "version": "4.0.7",
+  "description": "将 Node.js 项目一键打包为 Android / iOS 移动应用,运行时由 @flun/nodejs-mobile-react-native 提供;",
   "author": "flun <open@flun.top>",
   "keywords": [
     "node-mobile",
@@ -40,10 +40,10 @@
     "postinstall": "node scripts/copy-files.js"
   },
   "dependencies": {
-    "@babel/core": "^8.0.7",
-    "@eslint-react/eslint-plugin": "^5.28.2",
+    "@babel/core": "^8.0.9",
+    "@eslint-react/eslint-plugin": "^5.28.8",
     "@eslint/js": "^10.0.1",
-    "@flun/nodejs-mobile-react-native": "^2.1.0",
+    "@flun/nodejs-mobile-react-native": "^2.1.1",
     "@react-native/babel-preset": "^0.88.0",
     "@react-native/metro-config": "^0.88.0",
     "@react-native-community/cli": "^20.2.0",

package/scripts/copy-files.js

@@ -15,7 +15,7 @@ const __filename = fileURLToPath(import.meta.url), __dirname = path.dirname(__fi
 const copyFile = () => {
     console.log(`🔍 检查 ${fileName} 文件...`), console.log(`📁 项目根目录:${targetDir}`);
     try {
-        // 目标目录不是 Node 项目 || 包自身的 npm install（开发调试）→ 跳过
+        // 目标目录不是 Node 项目 || 包自身的 npm install(开发调试)→ 跳过
         if (!fs.existsSync(path.join(targetDir, 'package.json'))) return true;
         if (targetDir === path.resolve(__dirname, '..')) return true;
         if (fs.existsSync(targetFile)) return true; // 目标文件已存在 → 直接返回

package/src/commands/build.js

@@ -21,7 +21,9 @@ 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.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);
@@ -59,10 +61,12 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
 
     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);
+      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);
+        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);
@@ -100,7 +104,8 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
       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`,
+        const src = path.join(apkDir, f),
+          dstName = `${safeName}-${config.versionName}-${release ? 'release' : 'debug'}.apk`,
           dst = path.join(outDir, dstName);
 
         fs.copyFileSync(src, dst);

package/src/commands/clean.js

@@ -20,8 +20,9 @@ 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)));
-    else console.log(chalk.gray('跳过（不存在）: ' + t.label));
+      removeDir(t.path),
+        console.log(chalk.green('已清理: ' + t.label + ' -> ' + (path.relative(userProjectDir, t.path) || t.path)));
+    else console.log(chalk.gray('跳过(不存在): ' + t.label));
   }
 
   console.log(chalk.green('\n✅ 清理完成'));

package/src/commands/test.js

@@ -45,7 +45,8 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
     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');
+    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);
 
@@ -54,7 +55,7 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
 
     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 自动）`));
+      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',
@@ -68,12 +69,12 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
       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
+      // 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（离线可用）`));
+      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);
@@ -89,7 +90,7 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
       ], { cwd: buildDir });
       console.log(chalk.green('    ✓ bundle 已生成'));
 
-      console.log(chalk.cyan(`\n[8/${total}] 编译 Hermes 字节码（加速离线启动）`));
+      console.log(chalk.cyan(`\n[8/${total}] 编译 Hermes 字节码(加速离线启动)`));
       const hermesc = findHermesc(userProjectDir);
       if (hermesc) {
         const hbcPath = bundlePath + '.hbc';
@@ -97,7 +98,7 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
         fs.copyFileSync(hbcPath, bundlePath), fs.unlinkSync(hbcPath);
         console.log(chalk.green('    ✓ 已替换为 Hermes 字节码'));
       }
-      else console.warn(chalk.yellow('  ⚠️  未找到 hermesc,跳过字节码编译（离线启动会较慢）'));
+      else console.warn(chalk.yellow('  ⚠️  未找到 hermesc,跳过字节码编译(离线启动会较慢)'));
 
       const mergedAsset = path.join(buildDir, 'android', 'app', 'build', 'intermediates', 'assets', 'debug',
         'mergeDebugAssets', 'index.android.bundle');
@@ -131,9 +132,11 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
         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 (await metroReady()) {
+              ready = true, console.log(chalk.green('    ✓ Metro 已就绪(后台常驻,支持热更新)')); break;
+          }
         }
-        if (!ready) console.log(chalk.yellow('  ⚠️  Metro 30 秒内未就绪,详见 .metro.log；app 将回落到本地 bundle'));
+        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';
@@ -157,7 +160,8 @@ const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
       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 });
+      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);
     }

package/src/config.js

@@ -84,10 +84,10 @@ const DEFAULT_CONFIG = {
 
     const pkg = path.join(userProjectDir, 'package.json');
     if (!fs.existsSync(pkg)) errors.push('用户项目缺少 package.json');
-    // 极简防呆：至少 2 段、每段非空、只含 [a-zA-Z0-9_-],不允许首尾点或连续点
-    // 具体平台是否合法交给 Gradle / Xcode 报错（Android 不允许 -,iOS 允许）
+    // 极简防呆:至少 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);
+      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) {

package/src/copy.js

@@ -14,7 +14,7 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
     'Pods/', 'local.properties', '*.bak', 'gradle.properties.bak',
   ],
   /**
-   * 内部：递归覆盖式复制模板,跳过 keepSet 命中的文件
+   * 内部:递归覆盖式复制模板,跳过 keepSet 命中的文件
    */
   copyDirOverwrite = (src, dst, exclude, buildDir, keepSet) => {
     ensureDir(dst);
@@ -30,7 +30,7 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
     }
   },
   /**
-   * 内部：增量复制用户项目到 nodejs-project
+   * 内部:增量复制用户项目到 nodejs-project
    * 保留 node_modules 等由其他步骤生成的产物
    */
   copyDirIncremental = (src, dst, exclude) => {
@@ -53,15 +53,15 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
     }
   },
   /**
-   * 获取 build 目录路径：<userProject>/node-mobile-app-build
+   * 获取 build 目录路径:<userProject>/node-mobile-app-build
    */
   getBuildDir = userProjectDir => path.join(userProjectDir, BUILD_DIR_NAME),
 
   /**
    * 把 buildDir/package.json 的依赖版本同步为主包 dependencies 的版本
-   * - 依赖名单来自 buildDir/package.json（模板声明需要哪些依赖）
-   * - 版本号来自 pkgRoot/package.json 的 dependencies（单一数据源）
-   * - 若主包缺少某个依赖,抛错中断（避免模板占位值被真正使用）
+   * - 依赖名单来自 buildDir/package.json(模板声明需要哪些依赖)
+   * - 版本号来自 pkgRoot/package.json 的 dependencies(单一数据源)
+   * - 若主包缺少某个依赖,抛错中断(避免模板占位值被真正使用)
    */
   syncTemplateDependencies = (pkgRoot, buildDir) => {
     const buildPkgPath = path.join(buildDir, 'package.json');
@@ -84,25 +84,26 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
 
     if (needWrite) {
       writeIfChanged(buildPkgPath, JSON.stringify(buildPkg, null, 2) + '\n');
-      if (depsUpdated > 0) console.log(chalk.green('    ✓ 已同步 ' + depsUpdated + ' 个依赖版本到 ' + BUILD_DIR_NAME + '/package.json'));
+      if (depsUpdated > 0)
+        console.log(chalk.green('    ✓ 已同步 ' + depsUpdated + ' 个依赖版本到 ' + BUILD_DIR_NAME + '/package.json'));
     }
 
     if (missing.length > 0) {
       throw new Error(
-        'template/package.json 声明的以下依赖在主包 dependencies 中不存在：\n' +
+        'template/package.json 声明的以下依赖在主包 dependencies 中不存在:\n' +
         '       ' + missing.join(', ') + '\n' +
-        '     请在 @flun/node-mobile-app 的 package.json 中补上对应声明（版本号随意,\n' +
-        '     但必须存在,以便 syncTemplateDependencies 覆盖模板里的占位值）。'
+        '     请在 @flun/node-mobile-app 的 package.json 中补上对应声明(版本号随意,\n' +
+        '     但必须存在,以便 syncTemplateDependencies 覆盖模板里的占位值);'
       );
     }
   },
   /**
-   * 把主包 node_modules 里被 npm 嵌套（未提升到用户根）的依赖,按需链接到用户根 node_modules 下,
-   * 让 RN CLI / Metro 从用户根也能解析到它们。
-   * - 判据：从用户根视角解析不到,才建链接；能解析则跳过；
-   * - 范围：遍历主包 node_modules 顶层全部条目（含 @scope/ 下每个子项）,不列举任何包名；
-   * - 落点：只在用户根 node_modules 缺失条目时建 symlink,不覆盖已有内容、不碰 package.json / package-lock.json；
-   * - 建链接失败：中断报错,不静默。
+   * 把主包 node_modules 里被 npm 嵌套(未提升到用户根)的依赖,按需链接到用户根 node_modules 下,
+   * 让 RN CLI / Metro 从用户根也能解析到它们;
+   * - 判据:从用户根视角解析不到,才建链接;能解析则跳过;
+   * - 范围:遍历主包 node_modules 顶层全部条目(含 @scope/ 下每个子项),不列举任何包名;
+   * - 落点:只在用户根 node_modules 缺失条目时建 symlink,不覆盖已有内容、不碰 package.json / package-lock.json;
+   * - 建链接失败:中断报错,不静默;
    */
   linkNestedDeps = (pkgRoot, buildDir) => {
     const pkgNm = path.join(pkgRoot, 'node_modules');
@@ -133,8 +134,8 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
         fs.symlinkSync(realSrc, dst, 'junction'), linked++;
       } catch (err) {
         throw new Error(
-          '建立兜底链接失败：' + dst + ' -> ' + realSrc + '\n' +
-          '      原因：' + err.message + '\n' +
+          '建立兜底链接失败:' + dst + ' -> ' + realSrc + '\n' +
+          '      原因:' + err.message + '\n' +
           '      请检查 node_modules 是否被其它程序占用后重试'
         );
       }
@@ -143,8 +144,8 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
   },
   /**
    * 把 CLI 包里的 template/ 逐文件覆盖到 build 目录
-   * - 只覆盖模板里存在的文件,不删除 buildDir 里已有的其他内容（保留 Gradle 增量缓存）
-   * - 模板文件被改写时自动同步；新增文件自动添加
+   * - 只覆盖模板里存在的文件,不删除 buildDir 里已有的其他内容(保留 Gradle 增量缓存)
+   * - 模板文件被改写时自动同步;新增文件自动添加
    * - 若模板里删除了文件,旧副本残留由 CLI 版本指纹触发全量重建处理
    */
   copyTemplate = (pkgRoot, buildDir, config) => {
@@ -163,7 +164,7 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
   },
   /**
    * 复制用户 Node 项目到 <buildDir>/nodejs-assets/nodejs-project
-   * 复制后重写 package.json：只保留 dependencies,剔除 devDependencies；用 config 的 allowScripts
+   * 复制后重写 package.json:只保留 dependencies,剔除 devDependencies;用 config 的 allowScripts
    */
   copyUserProject = (userProjectDir, buildDir, config) => {
     const targetDir = path.join(buildDir, 'nodejs-assets', 'nodejs-project');
@@ -174,14 +175,15 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
       'mobileAppConfig.js', 'mobileAppConfig.mjs', 'mobileAppConfig.cjs'
     ];
 
-    // 增量复制：内容变化的文件才覆盖,保留 node_modules 和其他未变文件
+    // 增量复制:内容变化的文件才覆盖,保留 node_modules 和其他未变文件
     copyDirIncremental(userProjectDir, targetDir, exclude);
-    // 黑名单式过滤：只删 devDependencies 和 allowScripts,其余字段原样保留
+    // 黑名单式过滤:只删 devDependencies 和 allowScripts,其余字段原样保留
     const userPkgPath = path.join(userProjectDir, 'package.json');
     if (!fs.existsSync(userPkgPath)) throw new Error('用户项目缺少 package.json');
     const pkg = readJson(userPkgPath), out = { ...pkg };
     delete out.devDependencies;
-    out.allowScripts = (config.allowScripts && Object.keys(config.allowScripts).length) ? config.allowScripts : { node: true };
+    out.allowScripts 
+      (config.allowScripts && Object.keys(config.allowScripts).length) ? config.allowScripts : { node: true };
     writeIfChanged(path.join(targetDir, 'package.json'), JSON.stringify(out, null, 2) + '\n');
 
     console.log(chalk.green('    ✓ 已同步用户项目到 nodejs-assets/nodejs-project'));
@@ -191,11 +193,12 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
     return { pkg: out, moduleType: out.type === 'module' ? 'module' : 'commonjs', targetDir };
   },
   /**
-   * 生成 <buildDir>/android/local.properties（Gradle 需要 sdk.dir）
+   * 生成 <buildDir>/android/local.properties(Gradle 需要 sdk.dir)
    */
   writeLocalProperties = (buildDir, config) => {
     const sdkPath = resolveSdkPath(config);
-    if (!sdkPath) return console.warn(chalk.yellow('  ⚠️  未找到 Android SDK,请在 mobileAppConfig.js 里配置 android.sdkPath'));
+    if (!sdkPath)
+      return console.warn(chalk.yellow('  ⚠️  未找到 Android SDK,请在 mobileAppConfig.js 里配置 android.sdkPath'));
 
     const localProps = path.join(buildDir, 'android', 'local.properties'),
       escaped = sdkPath.replace(/\\/g, '\\\\').replace(/:/g, '\\:');
@@ -211,17 +214,17 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
     if (fs.existsSync(entryPath)) return { created: false, path: entryPath };
 
     const fallback = path.join(pkgRoot, 'cli-assets', 'server.js');
-    if (!fs.existsSync(fallback)) throw new Error('入口文件不存在: ' + config.serverPath + '（CLI 内置模板也缺失）');
+    if (!fs.existsSync(fallback)) throw new Error('入口文件不存在: ' + config.serverPath + '(CLI 内置模板也缺失)');
 
     ensureDir(path.dirname(entryPath)), fs.copyFileSync(fallback, entryPath);
     console.log(chalk.green('    ✓ 生成默认入口文件: ' + config.serverPath));
-    console.log(chalk.gray('    （因为用户项目里没有这个文件,从 CLI 内置模板复制）'));
+    console.log(chalk.gray('    (因为用户项目里没有这个文件,从 CLI 内置模板复制)'));
 
     return { created: true, path: entryPath };
   },
   /**
    * 确保用户项目根存在 mobileAppConfig.js
-   * 不存在时从 CLI 包根复制一份（带注释的模板）
+   * 不存在时从 CLI 包根复制一份(带注释的模板)
    */
   ensureUserConfig = (userProjectDir, pkgRoot) => {
     const configPath = path.join(userProjectDir, 'mobileAppConfig.js');
@@ -232,16 +235,16 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
 
     fs.copyFileSync(fallback, configPath);
     console.log(chalk.green('    ✓ 生成默认配置文件: mobileAppConfig.js'));
-    console.log(chalk.gray('    （因为用户项目里没有这个文件,从 CLI 内置模板复制）'));
+    console.log(chalk.gray('    (因为用户项目里没有这个文件,从 CLI 内置模板复制)'));
 
     return { created: true, path: configPath };
   },
   /**
-   * 按 config.android.abiFilters 修改 buildDir 里的 app/build.gradle：
+   * 按 config.android.abiFilters 修改 buildDir 里的 app/build.gradle:
    *   - defaultConfig.ndk.abiFilters
    *   - gradle.properties 的 reactNativeArchitectures
    * 插件 build.gradle 读的是 project(":app").android.defaultConfig.ndk.abiFilters,
-   * 所以必须改这里,改插件自身的 abiFilters 无效。
+   * 所以必须改这里,改插件自身的 abiFilters 无效;
    */
   patchAndroidAbi = (buildDir, config) => {
     const file = path.join(buildDir, 'android', 'app', 'build.gradle');
@@ -253,10 +256,10 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
 
     // defaultConfig 里的 ndk { abiFilters ... }
     c = c.replace(/(defaultConfig\s*\{[\s\S]*?ndk\s*\{\s*abiFilters\s+)("[^"]*"(?:\s*,\s*"[^"]*")*)/, `$1${abiList}`);
-    // 兜底：没有 ndk {} 块时,插到 defaultConfig 里
+    // 兜底:没有 ndk {} 块时,插到 defaultConfig 里
     if (!/ndk\s*\{\s*abiFilters/.test(c))
       c = c.replace(/(defaultConfig\s*\{)/, `$1\n        ndk {\n            abiFilters ${abiList}\n        }`);
-    // 不 patch splits.abi.include：AGP 禁止它和 ndk.abiFilters 同时存在
+    // 不 patch splits.abi.include:AGP 禁止它和 ndk.abiFilters 同时存在
     if (c !== before) writeIfChanged(file, c), console.log(chalk.green(`    ✓ 已设置 app ndk.abiFilters = [${abiList}]`));
 
     // 同步 gradle.properties 的 reactNativeArchitectures
@@ -265,7 +268,8 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
       let p = fs.readFileSync(propsFile, 'utf-8');
       const abiPlain = (config.android.abiFilters || []).join(','), before2 = p;
       p = p.replace(/^reactNativeArchitectures=.*/gm, `reactNativeArchitectures=${abiPlain}`);
-      if (p !== before2) writeIfChanged(propsFile, p), console.log(chalk.green(`    ✓ 已设置 reactNativeArchitectures = ${abiPlain}`));
+      if (p !== before2) writeIfChanged(propsFile, p),
+        console.log(chalk.green(`    ✓ 已设置 reactNativeArchitectures = ${abiPlain}`));
     }
   },
   /**
@@ -278,7 +282,8 @@ const BUILD_DIR_NAME = 'node-mobile-app-build',
     if (extras.length === 0) return;
 
     const buildPkgPath = path.join(buildDir, 'package.json');
-    if (!fs.existsSync(buildPkgPath)) return console.warn(chalk.yellow('  ⚠️  未找到 buildDir/package.json,跳过 extraRnDependencies'));
+    if (!fs.existsSync(buildPkgPath))
+      return console.warn(chalk.yellow('  ⚠️  未找到 buildDir/package.json,跳过 extraRnDependencies'));
 
     const buildPkg = readJson(buildPkgPath), missing = [];
     if (!buildPkg.dependencies) buildPkg.dependencies = {};

package/src/fingerprint.js

@@ -63,7 +63,8 @@ const FINGERPRINT_FILE = '.build-fingerprint.json',
 
     let pluginVersion = null, cliVersion = null;
     const pluginPkg = path.join(pluginDir, 'package.json'), cliPkg = path.join(pkgRoot, 'package.json');
-    if (fs.existsSync(pluginPkg)) try { pluginVersion = JSON.parse(fs.readFileSync(pluginPkg, 'utf-8')).version; } catch { };
+    if (fs.existsSync(pluginPkg))
+        try { pluginVersion = JSON.parse(fs.readFileSync(pluginPkg, 'utf-8')).version; } catch { };
     if (fs.existsSync(cliPkg)) try { cliVersion = JSON.parse(fs.readFileSync(cliPkg, 'utf-8')).version; } catch { };
 
     const depsHash = hashUserDeps(userProjectDir), a = config.android || {},
@@ -108,7 +109,7 @@ const FINGERPRINT_FILE = '.build-fingerprint.json',
       if (templateChanged) reasons.push('模板文件');
       if (depsChanged) reasons.push('用户依赖');
       if (appInfoChanged) reasons.push('应用信息');
-      console.log(chalk.yellow('  ⚠️  检测到变化（' + reasons.join('、') + '）,清理 Gradle 缓存、CMake 缓存与依赖缓存'));
+      console.log(chalk.yellow('  ⚠️  检测到变化(' + reasons.join('、') + '),清理 Gradle 缓存、CMake 缓存与依赖缓存'));
       clearGradleCaches(buildDir, userProjectDir);
       removeDir(path.join(userProjectDir, 'node_modules', '@flun', 'nodejs-mobile-react-native', 'android', '.cxx'));
       clearDepsCaches(buildDir);
@@ -117,7 +118,7 @@ const FINGERPRINT_FILE = '.build-fingerprint.json',
       const reasons = [], targets = [];
       if (depsChanged) reasons.push('用户依赖'), targets.push('依赖缓存', 'Gradle 缓存');
       if (appInfoChanged) reasons.push('应用信息'), targets.push('Gradle 缓存');
-      console.log(chalk.yellow('  ⚠️  检测到变化（' + reasons.join('、') + '）,清理 ' + [...new Set(targets)].join('、')));
+      console.log(chalk.yellow('  ⚠️  检测到变化(' + reasons.join('、') + '),清理 ' + [...new Set(targets)].join('、')));
       clearGradleCaches(buildDir, userProjectDir);
       if (depsChanged) clearDepsCaches(buildDir);
     }

package/src/generate.js

@@ -4,9 +4,9 @@ import { writeIfChanged } from './utils.js';
 import chalk from 'chalk';
 
 /**
- * 生成 main.js（桥接代码,用户不需要手写）
+ * 生成 main.js(桥接代码,用户不需要手写)
  *
- * 上报机制（通过 rn-bridge channel 发消息给 App.tsx）：
+ * 上报机制(通过 rn-bridge channel 发消息给 App.tsx):
  *   - 'Node started on <URL>'  server.js 成功调用 listen
  *   - 'Node failed: <原因>'    加载异常或 5 秒内未捕获 listen
  */
@@ -74,7 +74,9 @@ const generateMainJs = (targetDir, config, moduleType) => {
       }
     })();
 
-    ${config.advanced.keepAlive === false ? '// keepAlive: false — 不发送心跳' : "setInterval(() => rn_bridge.channel.send('heartbeat'), " + hb + ");"}
+    ${config.advanced.keepAlive === false
+      ? '// keepAlive: false - 不发送心跳'
+      : "setInterval(() => rn_bridge.channel.send('heartbeat'), " + hb + ");"}
 
     rn_bridge.channel.on('message', msg => rn_bridge.channel.send('Echo: ' + msg));
     })();`,