@flun/nodejs-mobile-gyp 1.1.3 → 1.1.4

package/lib/build.js

@@ -9,14 +9,14 @@ import fsSync from 'fs';
 
 const fs = gracefulFs.promises,
   _hostIsWindows = process.platform === 'win32',
-  // Android 交叉编译即使宿主是 Windows，也必须走 make（make-android 生成器）
+  // Android 交叉编译即使宿主是 Windows,也必须走 make(make-android 生成器)
   _isAndroidCrossBuild = process.env.npm_config_platform === 'android' || process.env.npm_config_format === 'make-android',
-  // win 在此文件中语义为"使用 MSBuild"：仅 Windows 宿主且非 Android 交叉编译
+  // win 在此文件中语义为"使用 MSBuild":仅 Windows 宿主且非 Android 交叉编译
   win = _hostIsWindows && !_isAndroidCrossBuild,
   /**
    * Windows 上 GNU make 需要 sh.exe 来执行 Makefile 里的 Unix 命令
-   * （printf / xargs / rm 等）。优先复用 Git for Windows 自带的 usr/bin，
-   * 避免要求用户额外安装 MSYS2。通过 "where git" 反推，不硬编码路径。
+   * (printf / xargs / rm 等);优先复用 Git for Windows 自带的 usr/bin,
+   * 避免要求用户额外安装 MSYS2;通过 "where git" 反推,不硬编码路径;
    */
   findWindowsShellDir = () => {
     if (process.platform !== 'win32') return null;
@@ -24,7 +24,7 @@ const fs = gracefulFs.promises,
       try { return fsSync.existsSync(path.join(dir, 'sh.exe')) ? dir : null } catch { return null }
     };
     const toShDir = (gitRoot) => tryShDir(path.join(gitRoot, 'usr', 'bin'));
-    // 1) 注册表：Git for Windows 安装时必写，与 PATH 无关（最可靠）
+    // 1) 注册表:Git for Windows 安装时必写,与 PATH 无关(最可靠)
     const reg = process.env.SystemRoot ? path.join(process.env.SystemRoot, 'System32', 'reg.exe') : 'reg.exe';
     for (const hive of ['HKLM', 'HKCU']) {
       for (const key of ['SOFTWARE\\GitForWindows', 'SOFTWARE\\WOW6432Node\\GitForWindows']) {
@@ -40,7 +40,7 @@ const fs = gracefulFs.promises,
         } catch { }
       }
     }
-    // 2) which.sync（PATH 中能找到 git 时可用）
+    // 2) which.sync(PATH 中能找到 git 时可用)
     try {
       const gitPath = which.sync('git');
       if (gitPath) {
@@ -49,7 +49,7 @@ const fs = gracefulFs.promises,
         if (r) return r;
       }
     } catch { }
-    // 3) PATH 中找 git.exe，再反推 ../usr/bin
+    // 3) PATH 中找 git.exe,再反推 ../usr/bin
     for (const pd of (process.env.PATH || '').split(';')) {
       if (!pd) continue;
       try {
@@ -97,11 +97,11 @@ const fs = gracefulFs.promises,
       if (win && !verbose) argv.push('/clp:Verbosity=minimal');
       if (win) argv.push('/nologo'); // Windows 上关闭 Microsoft logo
 
-      // 指定构建类型，默认 Release
+      // 指定构建类型,默认 Release
       if (win) {
         // 把 .gypi 配置中的 target_arch 转换为 MSBuild 的 /Platform
-        // 因为表示"32 位 Intel"的方式很多，默认按此处理
-        // 注意：msbuild 的 Condition 字符串相等比较不区分大小写
+        // 因为表示"32 位 Intel"的方式很多,默认按此处理
+        // 注意:msbuild 的 Condition 字符串相等比较不区分大小写
         const archLower = arch.toLowerCase(), p = archLower === 'x64' ? 'x64' : (archLower === 'arm' ? 'ARM'
           : (archLower === 'arm64' ? 'ARM64' : 'Win32'));
         argv.push('/p:Configuration=' + buildType + ';Platform=' + p)
@@ -122,13 +122,13 @@ const fs = gracefulFs.promises,
       }
 
       if (win) {
-        // 用户是否指定了自己的 .sln 文件？
+        // 用户是否指定了自己的 .sln 文件?
         const hasSln = argv.some(arg => path.extname(arg) === '.sln');
         if (!hasSln) argv.unshift(gyp.opts.solution || guessedSolution);
       }
 
       if (!win) {
-        // 把构建期依赖的符号链接（如 Python）加入 PATH
+        // 把构建期依赖的符号链接(如 Python)加入 PATH
         buildBinsDir = path.resolve('build', 'node_gyp_bins');
         if (_hostIsWindows) {
           const shellDir = findWindowsShellDir();
@@ -136,7 +136,7 @@ const fs = gracefulFs.promises,
             process.env.PATH = `${shellDir};${process.env.PATH}`;
             log.verbose('bin shell', `prepended ${shellDir} to PATH for make`);
           } else {
-            log.warn('bin shell', 'no sh.exe found; GNU make 的 Unix 命令可能失败。建议安装 Git for Windows');
+            log.warn('bin shell', 'no sh.exe found; GNU make 的 Unix 命令可能失败;建议安装 Git for Windows');
           }
         }
         process.env.PATH = _hostIsWindows
@@ -145,7 +145,7 @@ const fs = gracefulFs.promises,
         await fs.mkdir(buildBinsDir, { recursive: true });
 
         if (_hostIsWindows) {
-          // Windows 无 python3 名称，且创建符号链接需要管理员权限；改用 .cmd 桥接
+          // Windows 无 python3 名称,且创建符号链接需要管理员权限;改用 .cmd 桥接
           const shimPath = path.join(buildBinsDir, 'python3.cmd');
           await fs.writeFile(shimPath, `@echo off\r\n"${python}" %*\r\n`);
           log.verbose('bin shims', `created python3.cmd shim to "${python}" and added to PATH`);
@@ -176,7 +176,7 @@ const fs = gracefulFs.promises,
       doWhich = async () => {
         // Windows 使用 node-gyp configure 提供的 msbuild
         if (win) {
-          if (!config.variables.msbuild_path) throw new Error('MSBuild 未设置，请先运行 `node-gyp configure`');
+          if (!config.variables.msbuild_path) throw new Error('MSBuild 未设置,请先运行 `node-gyp configure`');
           command = config.variables.msbuild_path, log.verbose('using MSBuild:', command), await doBuild();
           return;
         }
@@ -190,7 +190,7 @@ const fs = gracefulFs.promises,
        */
       findSolutionFile = async () => {
         const files = await glob('build/*.sln')
-        if (files.length === 0) throw new Error('未找到 *.sln 文件，是否运行过 configure？');
+        if (files.length === 0) throw new Error('未找到 *.sln 文件,是否运行过 configure?');
         guessedSolution = files[0], log.verbose('found first Solution file', guessedSolution), await doWhich();
       },
       /**

package/lib/clean.js

@@ -3,7 +3,7 @@ import * as log from './log.js';
 
 const fs = gracefulFs.promises,
   /**
-   * 清理：删除 build 目录
+   * 清理:删除 build 目录
    */
   clean = async (gyp, argv) => {
     const buildDir = 'build';
@@ -13,4 +13,4 @@ const fs = gracefulFs.promises,
   }
 
 clean.usage = 'Removes any generated build files and the "out" dir';
-export { clean };
+export { clean };

package/lib/configure.js

@@ -10,9 +10,10 @@ import { findAccessibleSync } from './util.js';
 import { PythonFinder } from './find-python.js';
 import { fileURLToPath } from 'url';
 
-const fs = gracefulFs.promises, win = process.platform === 'win32', __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fs = gracefulFs.promises, win = process.platform === 'win32',
+    __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-// 条件加载：仅在 Windows 上需要
+// 条件加载:仅在 Windows 上需要
 let findVisualStudio = null, nodeDir, vsInfo = null;
 if (win) {
   const { VisualStudioFinder } = await import('./find-visualstudio.js');
@@ -20,7 +21,7 @@ if (win) {
 }
 
 /**
- * 生成构建文件（Makefile / MSVC 工程）
+ * 生成构建文件(Makefile / MSVC 工程)
  */
 const configure = async (gyp, argv) => {
   const buildDir = path.resolve('build'), configNames = ['config.gypi', 'common.gypi'], configs = [],
@@ -40,7 +41,7 @@ const configure = async (gyp, argv) => {
       }
 
       configs.forEach(config => argv.push('-I', config)); // 引入所有找到的 .gypi 文件
-      // AIX 和 z/OS 需要设置导出文件路径，其中包含链接所需符号
+      // AIX 和 z/OS 需要设置导出文件路径,其中包含链接所需符号
       let nodeExpFile, nodeRootDir, candidates, logprefix = 'find exports file';
       if (process.platform === 'aix' || process.platform === 'os390' || process.platform === 'os400') {
         const ext = process.platform === 'os390' ? 'x' : 'exp';
@@ -62,7 +63,7 @@ const configure = async (gyp, argv) => {
         }
       }
 
-      // z/OS 需要设置 zoslib 头文件目录，其中包含 v8config.h 引用的头文件
+      // z/OS 需要设置 zoslib 头文件目录,其中包含 v8config.h 引用的头文件
       let zoslibIncDir;
       if (process.platform === 'os390') {
         logprefix = "find zoslib's zos-base.h:";
@@ -110,7 +111,8 @@ const configure = async (gyp, argv) => {
       if (win) outputDir = buildDir;  // Windows 需要绝对路径
       const nodeGypDir = path.resolve(__dirname, '..');
 
-      let nodeLibFile = path.join(nodeDir, !gyp.opts.nodedir ? '<(target_arch)' : '$(Configuration)', release.name + '.lib');
+      let nodeLibFile = path.join(nodeDir,
+          !gyp.opts.nodedir ? '<(target_arch)' : '$(Configuration)', release.name + '.lib');
 
       argv.push('-I', addonGypi), argv.push('-I', commonGypi), argv.push('-Dlibrary=shared_library');
       argv.push('-Dvisibility=default'), argv.push('-Dnode_root_dir=' + nodeDir);
@@ -120,18 +122,18 @@ const configure = async (gyp, argv) => {
       }
       argv.push('-Dnode_gyp_dir=' + nodeGypDir);
 
-      // 这样做是为了让 Cygwin 环境正常工作，否则未转义的 '\' 会被吃掉，
-      // 导致路径错误，如 c:parentFolderfolderanotherFolder 而非 c:\parentFolder\folder\anotherFolder
+      // 这样做是为了让 Cygwin 环境正常工作,否则未转义的 '\' 会被吃掉,
+      // 导致路径错误,如 c:parentFolderfolderanotherFolder 而非 c:\parentFolder\folder\anotherFolder
       if (win) nodeLibFile = nodeLibFile.replace(/\\/g, '\\\\');
       argv.push('-Dnode_lib_file=' + nodeLibFile), argv.push('-Dmodule_root_dir=' + process.cwd());
       argv.push('-Dnode_engine=' + (gyp.opts.node_engine || process.jsEngine || 'v8'));
       argv.push('--depth=.'), argv.push('--no-parallel');
       argv.push('--generator-output', outputDir); // 告诉 gyp 把 Makefile/Solution 文件写到 output_dir
-      // 使用 find-visualstudio 探测到的实际 toolset（v140/v141/v142/v143/v145...），
-      // 不再硬编码，以兼容 VS2013+ 各版本
+      // 使用 find-visualstudio 探测到的实际 toolset(v140/v141/v142/v143/v145...),
+      // 不再硬编码,以兼容 VS2013+ 各版本
       if (win) {
         if (vsInfo?.toolset) argv.push('-Gmsvs_toolset=' + vsInfo.toolset);
-        else log.warn('gyp', '未能探测到 VS toolset，将使用 gyp 默认值');
+        else log.warn('gyp', '未能探测到 VS toolset,将使用 gyp 默认值');
       }
 
       argv.push('-Goutput_dir=.'); // 告诉 make 把输出写到同一目录
@@ -187,21 +189,22 @@ const configure = async (gyp, argv) => {
       process.env.PYTHON = python;
 
       if (gyp.opts.nodedir) {
-        // 指定了 --nodedir，用它作为开发文件目录
+        // 指定了 --nodedir,用它作为开发文件目录
         nodeDir = gyp.opts.nodedir.replace(/^~/, os.homedir());
         log.verbose('get node dir', 'compiling against specified --nodedir dev files: %s', nodeDir);
       } else {
-        // 未指定 --nodedir，先确保 Node 依赖已安装
+        // 未指定 --nodedir,先确保 Node 依赖已安装
         if ('v' + release.version !== process.version) {
-          // 指定了 --target，确定目标版本
+          // 指定了 --target,确定目标版本
           log.verbose('get node dir', 'compiling against --target node version: %s', release.version);
         } else {
-          // 未指定 --target，使用当前主机 Node 版本
-          log.verbose('get node dir', 'no --target version specified, falling back to host node version: %s', release.version);
+          // 未指定 --target,使用当前主机 Node 版本
+          log.verbose('get node dir',
+              'no --target version specified, falling back to host node version: %s', release.version);
         }
 
         if (!release.semver) throw new Error('版本号无效: ' + release.version); // 无法用 semver 解析版本字符串
-        // 如果指定了 tarball 选项，总是删除并重装 headers 到 devdir，
+        // 如果指定了 tarball 选项,总是删除并重装 headers 到 devdir,
         // 否则只在不存在时安装
         gyp.opts.ensure = !gyp.opts.tarball, await gyp.commands.install([release.version]);
         log.verbose('get node dir', 'target node version installed:', release.versionDir);

package/lib/create-config-gypi.js

@@ -16,7 +16,7 @@ const fs = gracefulFs.promises,
    * 读取基础 config.gypi
    */
   getBaseConfigGypi = async ({ gyp, nodeDir }) => {
-    // 在以下情况优先读取 $nodeDir/include/node/config.gypi：
+    // 在以下情况优先读取 $nodeDir/include/node/config.gypi:
     // 1. 指定了 --dist-url 或 --nodedir
     // 2. 且没有指定 --force-process-config
     const useCustomHeaders = gyp.opts.nodedir || gyp.opts.disturl || gyp.opts['dist-url'],
@@ -40,8 +40,8 @@ const fs = gracefulFs.promises,
     if (!config.variables) config.variables = {};
 
     const defaults = config.target_defaults, variables = config.variables;
-    // 不要继承 base config.gypi 的 defaults，
-    // 否则当 node 可执行文件在另一台机器编译（lib/include 路径不同）时会出问题
+    // 不要继承 base config.gypi 的 defaults,
+    // 否则当 node 可执行文件在另一台机器编译(lib/include 路径不同)时会出问题
     defaults.cflags = [], defaults.defines = [], defaults.include_dirs = [], defaults.libraries = [];
 
     // 设置 default_configuration
@@ -66,14 +66,14 @@ const fs = gracefulFs.promises,
         else log.warn('仅 Visual Studio 2017 15.9 及以上版本支持编译 ARM64 汇编');
       }
       variables.msbuild_path = vsInfo.msBuild;
-      // Windows 原生构建走 MSVC 工具集：必须关闭 clang 与 LTO，
-      // 否则 common.gypi 会把 toolset 设为 ClangCL，并向 MSVC 链接器传入 Clang 专用参数
-      // （-flto=thin、/opt:lldltojobs），导致 MSB8020 或 LNK1117
+      // Windows 原生构建走 MSVC 工具集:必须关闭 clang 与 LTO,
+      // 否则 common.gypi 会把 toolset 设为 ClangCL,并向 MSVC 链接器传入 Clang 专用参数
+      // (-flto=thin、/opt:lldltojobs),导致 MSB8020 或 LNK1117
       if (!gyp.opts.format || gyp.opts.format === 'msvs')
         variables.clang = 0, variables.enable_lto = 'false', variables.enable_thin_lto = 'false', variables.lto_jobs = '';
     }
 
-    // 把其余未知选项当作变量写入，支持模块自定义 configure 参数，例如：
+    // 把其余未知选项当作变量写入,支持模块自定义 configure 参数,例如:
     //   $ node-gyp configure --shared-libxml2
     for (const [k, v] of Object.entries(gyp.opts)) {
       if (k === 'argv' || k in gyp.configDefs) continue;
@@ -106,4 +106,4 @@ const fs = gracefulFs.promises,
     return configPath;
   };
 
-export { createConfigGypi, parseConfigGypi, getCurrentConfigGypi }
+export { createConfigGypi, parseConfigGypi, getCurrentConfigGypi }

package/lib/download.js

@@ -4,10 +4,10 @@ import * as log from './log.js';
 
 const { promises: fs } = gracefulFs,
   /**
-   * 读取 CA 证书文件，按证书边界切分为多个证书
+   * 读取 CA 证书文件,按证书边界切分为多个证书
    */
   readCAFile = async filename => {
-    // CA 文件可能包含多份证书，按证书边界切分; [\S\s]*? 用于匹配包括换行在内的所有内容;
+    // CA 文件可能包含多份证书,按证书边界切分; [\S\s]*? 用于匹配包括换行在内的所有内容;
     const ca = await fs.readFile(filename, 'utf8'), re = /(-----BEGIN CERTIFICATE-----[\S\s]*?-----END CERTIFICATE-----)/g;
     return ca.match(re);
   },
@@ -28,4 +28,4 @@ const { promises: fs } = gracefulFs,
     return res;
   }
 
-export { readCAFile, download }
+export { readCAFile, download }

package/lib/find-node-directory.js

@@ -7,33 +7,33 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url)),
    * 从脚本位置或进程对象推断 Node 根目录
    */
   findNodeDirectory = (scriptLocation, processObj) => {
-    // 未传入时使用默认值，便于回归测试
+    // 未传入时使用默认值,便于回归测试
     if (scriptLocation === undefined) scriptLocation = __dirname;
     if (processObj === undefined) processObj = process;
 
-    // 看看上层目录结构，判断当前所处位置
+    // 看看上层目录结构,判断当前所处位置
     const npmParentDirectory = path.join(scriptLocation, '../../../..');
     log.verbose('node-gyp root', 'npm_parent_directory is ' + path.basename(npmParentDirectory));
     log.verbose('node-gyp root', 'Finding node root directory');
     let nodeRootDir = '';
     if (path.basename(npmParentDirectory) === 'deps') {
-      // 处于构建目录中，脚本位于 deps/npm/node_modules/node-gyp/lib
+      // 处于构建目录中,脚本位于 deps/npm/node_modules/node-gyp/lib
       nodeRootDir = path.join(npmParentDirectory, '..');
       log.verbose('node-gyp root', 'in build directory, root = ' + nodeRootDir);
     } else if (path.basename(npmParentDirectory) === 'node_modules') {
-      // 处于 Node 安装目录中，脚本位于
+      // 处于 Node 安装目录中,脚本位于
       // lib/node_modules/npm/node_modules/node-gyp/lib 或
-      // node_modules/npm/node_modules/node-gyp/lib（视平台而定）
+      // node_modules/npm/node_modules/node-gyp/lib(视平台而定)
       if (processObj.platform === 'win32') nodeRootDir = path.join(npmParentDirectory, '..');
       else nodeRootDir = path.join(npmParentDirectory, '../..');
       log.verbose('node-gyp root', 'in install directory, root = ' + nodeRootDir);
     } else {
-      // 无法判断，尝试从 node 可执行文件的位置推断
+      // 无法判断,尝试从 node 可执行文件的位置推断
       const nodeDir = path.dirname(processObj.execPath), directoryUp = path.basename(nodeDir);
       if (directoryUp === 'bin') nodeRootDir = path.join(nodeDir, '..');
       else if (directoryUp === 'Release' || directoryUp === 'Debug') {
-        // 如果是刚构建的 node，且目录结构为仓库结构：
-        // Windows 只需上一层，其余平台两层
+        // 如果是刚构建的 node,且目录结构为仓库结构:
+        // Windows 只需上一层,其余平台两层
         if (processObj.platform === 'win32') nodeRootDir = path.join(nodeDir, '..');
         else nodeRootDir = path.join(nodeDir, '../..');
       }
@@ -42,4 +42,4 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url)),
     return nodeRootDir;
   }
 
-export { findNodeDirectory }
+export { findNodeDirectory }

package/lib/find-python.js

@@ -6,7 +6,7 @@ import fs from 'fs';
 
 const win = process.platform === 'win32',
   /**
-   * 获取当前操作系统用户名（失败时返回 undefined）
+   * 获取当前操作系统用户名(失败时返回 undefined)
    */
   getOsUserInfo = () => {
     try { return os.userInfo().username } catch { }
@@ -19,8 +19,8 @@ const win = process.platform === 'win32',
   programFilesX86 = process.env['ProgramFiles(x86)'] || `${programFiles} (x86)`,
   systemRoot = process.env.SystemRoot || `${systemDrive}\\Windows`,
   /**
-   * 动态扫描 Windows 上所有已安装的 Python，不硬编码版本号。
-   * 官方安装器目录命名：3.14 -> Python314，3.9 -> Python39，32 位加 -32 后缀。
+   * 动态扫描 Windows 上所有已安装的 Python,不硬编码版本号;
+   * 官方安装器目录命名:3.14 -> Python314,3.9 -> Python39,32 位加 -32 后缀;
    */
   scanWindowsPythonLocations = () => {
     const results = [], bases = [foundLocalAppData ? `${localAppData}\\Programs\\Python` : null, `${programFiles}\\Python`,
@@ -40,13 +40,13 @@ const win = process.platform === 'win32',
     return results;
   },
   /**
-   * py.exe 启动器候选：先试 PATH 中的，再试常见绝对路径，
-   * 避免 Gradle / CI 环境下 PATH 不含 C:\Windows 的情况。
+   * py.exe 启动器候选:先试 PATH 中的,再试常见绝对路径,
+   * 避免 Gradle / CI 环境下 PATH 不含 C:\Windows 的情况;
    */
   pyLauncherCandidates = win ? ['py.exe', `${systemRoot}\\py.exe`, `${systemRoot}\\System32\\py.exe`] : [];
 
 /**
- * Python 查找器：按顺序尝试多种途径定位可用的 Python 3.6+
+ * Python 查找器:按顺序尝试多种途径定位可用的 Python 3.6+
  */
 class PythonFinder {
   static findPython = (...args) => new PythonFinder(...args).findPython();
@@ -66,12 +66,12 @@ class PythonFinder {
     this.configPython = configPython, this.errorLog = [];
   }
 
-  // 以 verbose 级别记录日志，同时保存下来，出错时以 error 级别展示，便于诊断
+  // 以 verbose 级别记录日志,同时保存下来,出错时以 error 级别展示,便于诊断
   addLog(message) {
     this.log.verbose(message), this.errorLog.push(message);
   }
 
-  // 依次尝试多种 Python 定位方式。忽略错误，直到找到可用版本
+  // 依次尝试多种 Python 定位方式;忽略错误,直到找到可用版本
   async findPython() {
     const SKIP = 0, FAIL = 1,
       toCheck = (() => {
@@ -158,7 +158,7 @@ class PythonFinder {
     return this.fail();
   }
 
-  // 检查命令是否为可用的 Python。
+  // 检查命令是否为可用的 Python;
   async checkCommand(command) {
     this.log.verbose(`- executing "${command}" to get executable path`);
     try {
@@ -171,7 +171,7 @@ class PythonFinder {
     }
   }
 
-  // 检查指定 py 启动器是否能找到 Python 3。
+  // 检查指定 py 启动器是否能找到 Python 3;
   async checkPyLauncher(launcher = this.pyLauncher) {
     this.log.verbose(`- executing "${launcher}" to get Python 3 executable path`);
     try {
@@ -184,7 +184,7 @@ class PythonFinder {
     }
   }
 
-  // 通过 "py -0p" 枚举所有已注册的 Python，覆盖非标准安装位置。
+  // 通过 "py -0p" 枚举所有已注册的 Python,覆盖非标准安装位置;
   async checkPyList() {
     this.log.verbose('- executing "py -0p" to list registered Pythons');
     let lastErr;
@@ -213,7 +213,7 @@ class PythonFinder {
     throw lastErr || new Error('py -0p returned no usable Python');
   }
 
-  // 检查某个 Python 可执行文件版本是否可用。
+  // 检查某个 Python 可执行文件版本是否可用;
   async checkExecPath(execPath) {
     this.log.verbose(`- executing "${execPath}" to get version`);
     try {
@@ -242,8 +242,8 @@ class PythonFinder {
     }
   }
 
-  // 执行外部命令。execFile 包装不 reject，通过 [err, stdout, stderr] 返回结果，
-  // 必须显式检查 err，否则失败会被当成"成功但空输出"，掩盖真实原因。
+  // 执行外部命令;execFile 包装不 reject,通过 [err, stdout, stderr] 返回结果,
+  // 必须显式检查 err,否则失败会被当成"成功但空输出",掩盖真实原因;
   async run(exec, args, shell) {
     const env = Object.assign({}, this.env), opts = { env, shell };
     env.TERM = 'dumb';

package/lib/find-visualstudio.js

@@ -6,7 +6,7 @@ import { regSearchKeys, execFile } from './util.js';
 
 const path = nodePath.win32, __dirname = nodePath.dirname(fileURLToPath(import.meta.url));
 /**
- * Visual Studio 查找器：定位可用的 VS 安装
+ * Visual Studio 查找器:定位可用的 VS 安装
  */
 class VisualStudioFinder {
   static findVisualStudio = (...args) => new VisualStudioFinder(...args).findVisualStudio();
@@ -17,7 +17,7 @@ class VisualStudioFinder {
     this.nodeSemver = nodeSemver, this.configMsvsVersion = configMsvsVersion, this.errorLog = [], this.validVersions = [];
   }
 
-  // 以 verbose 级别记录日志，同时保存下来，出错时以 error 级别展示，便于诊断
+  // 以 verbose 级别记录日志,同时保存下来,出错时以 error 级别展示,便于诊断
   addLog(message) {
     this.log.verbose(message), this.errorLog.push(message);
   }
@@ -66,7 +66,7 @@ class VisualStudioFinder {
       this.errorLog.push(
         'msvs_version does not match this VS Command Prompt or the', 'installation cannot be used.');
     else if (this.configMsvsVersion) {
-      // 指定了 msvs_version 但没找到 VS，输出可接受的版本
+      // 指定了 msvs_version 但没找到 VS,输出可接受的版本
       this.errorLog.push('');
       if (this.validVersions) {
         this.errorLog.push('valid versions for msvs_version:');
@@ -76,7 +76,7 @@ class VisualStudioFinder {
     }
 
     const errorLog = this.errorLog.join('\n'),
-      // Windows 80 列控制台，用到 X 标记列之前（含日志前缀共 79 字符，可用 62 字符）：
+      // Windows 80 列控制台,用到 X 标记列之前(含日志前缀共 79 字符,可用 62 字符):
       infoLog = [
         '**************************************************************',
         'You need to install the latest version of Visual Studio',
@@ -90,7 +90,7 @@ class VisualStudioFinder {
     throw new Error('未找到可用的 Visual Studio 安装');
   }
 
-  // 调用 PowerShell 脚本，获取 Visual Studio 2017 或更新版本的信息
+  // 调用 PowerShell 脚本,获取 Visual Studio 2017 或更新版本的信息
   async findVisualStudio2017OrNewer() {
     const ps = path.join(process.env.SystemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
       csFile = path.join(__dirname, 'Find-VisualStudio.cs'),
@@ -102,7 +102,7 @@ class VisualStudioFinder {
     return this.parseData(err, stdout, stderr);
   }
 
-  // 解析 PowerShell 脚本输出，寻找可用的 Visual Studio 2017 或更新版本
+  // 解析 PowerShell 脚本输出,寻找可用的 Visual Studio 2017 或更新版本
   parseData(err, stdout, stderr) {
     this.log.silly('PS stderr = %j', stderr)
 
@@ -149,7 +149,7 @@ class VisualStudioFinder {
       return false;
     })
 
-    // 排序：新版本在前
+    // 排序:新版本在前
     vsInfo.sort((a, b) => b.versionYear - a.versionYear)
 
     for (let i = 0; i < vsInfo.length; ++i) {
@@ -182,7 +182,7 @@ class VisualStudioFinder {
     return null;
   }
 
-  // 辅助：解析版本信息
+  // 辅助:解析版本信息
   getVersionInfo(info) {
     const match = /^(\d+)\.(\d+)\./.exec(info.version);
     if (!match) {
@@ -206,7 +206,7 @@ class VisualStudioFinder {
     return existsSync(path);
   }
 
-  // 辅助：解析 MSBuild 信息
+  // 辅助:解析 MSBuild 信息
   getMSBuild(info, versionYear) {
     const pkg = 'Microsoft.VisualStudio.VC.MSBuild.Base',
       msbuildPath = path.join(info.path, 'MSBuild', 'Current', 'Bin', 'MSBuild.exe'),
@@ -217,16 +217,16 @@ class VisualStudioFinder {
       if (versionYear === 2019) return msbuildPath;
     }
     /**
-     * Visual Studio 2022 没有 MSBuild 包。
-     * ARM64 上编译的支持从 MSVC 14.32.31326 起加入，
-     * 因此用户设备是 ARM64 时优先使用它。
+     * Visual Studio 2022 没有 MSBuild 包;
+     * ARM64 上编译的支持从 MSVC 14.32.31326 起加入,
+     * 因此用户设备是 ARM64 时优先使用它;
      */
     if (process.arch === 'arm64' && this.msBuildPathExists(msbuildPathArm64)) return msbuildPathArm64;
     else if (this.msBuildPathExists(msbuildPath)) return msbuildPath;
     return null;
   }
 
-  // 辅助：解析 toolset 信息
+  // 辅助:解析 toolset 信息
   getToolset(info, versionYear) {
     const pkg = 'Microsoft.VisualStudio.Component.VC.Tools.x86.x64', express = 'Microsoft.VisualStudio.WDExpress';
     if (info.packages.indexOf(pkg) !== -1) this.log.silly('- found VC.Tools.x86.x64');
@@ -241,7 +241,7 @@ class VisualStudioFinder {
     return null;
   }
 
-  // 辅助：解析 Windows SDK 信息
+  // 辅助:解析 Windows SDK 信息
   getSDK(info) {
     const win8SDK = 'Microsoft.VisualStudio.Component.Windows81SDK',
       win10SDKPrefix = 'Microsoft.VisualStudio.Component.Windows10SDK.',
@@ -291,7 +291,7 @@ class VisualStudioFinder {
     return this.findOldVS({ version: '12.0', versionMajor: 12, versionMinor: 0, versionYear: 2013, toolset: 'v120' });
   }
 
-  // 辅助：VS2013 和 VS2015 的公共代码
+  // 辅助:VS2013 和 VS2015 的公共代码
   async findOldVS(info) {
     const regVC7 = ['HKLM\\Software\\Microsoft\\VisualStudio\\SxS\\VC7',
       'HKLM\\Software\\Wow6432Node\\Microsoft\\VisualStudio\\SxS\\VC7'],
@@ -322,10 +322,10 @@ class VisualStudioFinder {
     }
   }
 
-  // 找到可用的 Visual Studio 后：
-  // - 把它加入 validVersions，用于在指定版本未找到时输出；
-  // - 检查是否是请求的版本；
-  // - 检查是否匹配 Visual Studio 命令提示符。
+  // 找到可用的 Visual Studio 后:
+  // - 把它加入 validVersions,用于在指定版本未找到时输出;
+  // - 检查是否是请求的版本;
+  // - 检查是否匹配 Visual Studio 命令提示符;
   checkConfigVersion(versionYear, vsPath) {
     this.validVersions.push(versionYear), this.validVersions.push(vsPath);