@flun/nodejs-mobile-gyp 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [1.1.0] - 2026-09-27 16:01
+
+### 新增
+
+- **Windows 宿主平台支持**：此前 Windows 上无法完成 Android 原生模块的交叉编译全流程，本版起支持。
+
+### 修复
+
+- **GNU make 缺 POSIX shell**：Android 原生模块通过 GNU make 构建，Makefile 会调用 `printf` / `xargs` / `sed` 等 Unix 命令。Windows 上原本因找不到 `sh.exe` 而报 `CreateProcess(NULL, printf ...) failed`。现在自动定位 Git for Windows 的 `usr/bin` 并前置到 PATH。
+- **Python 探测漏检**：`find-python.js` 原本硬编码 `3.11 / 3.10 / 3.9 / 3.8` 等安装目录，装在非标准位置（如 `C:\Python314`）或更新版本时无法识别。现在改为动态探测，见下方「变更」。
+- **工具集写死**：`configure` 阶段原本硬编码 `-Gmsvs_toolset=v145`，仅 VS2026 可用，VS2022 等会失败。现在从 `find-visualstudio` 的探测结果动态取用。
+- **路径分隔符**：gyp 生成的 Makefile 中路径带 Windows 反斜杠（如 `src\bufferutil.o`），导致 `sh` / `sed` / `make` 解析失败。现在统一转正斜杠；该改动在非 Windows 平台为 no-op。
+- **超长路径依赖**：Windows 下 Makefile 会因 gypi 依赖路径超过 260 字符而报 `No rule to make target`。现在过滤掉 `node_modules` 中的此类依赖——仅影响 Makefile 自动重新生成，不影响编译。
+
+### 变更
+
+- **`lib/find-python.js`**：重写。移除硬编码版本列表，改为 `py.exe` 候选（PATH / `%SystemRoot%`）+ `py -0p` 枚举 + `%LOCALAPPDATA%\Programs\Python` 与 `%ProgramFiles%\Python` 目录扫描。`run()` 显式检查 `execFile` 的 err，避免失败被当成空输出。
+- **`lib/build.js`**：区分「宿主平台」与「交叉编译目标」。Windows 宿主编译 Android 目标时走 GNU make（而非 MSBuild）；自动探测 `sh.exe`；为 Python 创建 `python3.cmd` shim（Windows 上无需符号链接权限）。
+- **`lib/configure.js`**：`-Gmsvs_toolset` 从探测结果动态生成，不再写死。
+- **`gyp/pylib/gyp/common.py`、`gyp/pylib/gyp/generator/make.py`**：路径统一输出正斜杠；新增 `slashpath` 辅助供 `mkdir` 使用。
+
+### 验证
+
+- Windows + VS2026 BuildTools + Python + Node + NDK 27.x 环境下，`configure` + `build` 全流程通过，生成的 `.node` 可被 Node 正常加载。
+- WSL Ubuntu 24.04 环境下，改动不改变生成的 Makefile 路径，非 Windows 平台行为不变。
+
+### 说明
+
+- 本版无破坏性变更，向后兼容。
+
+
+## [1.0.2] - 2026-09-26 22:00
+
+### 修复
+
+- **lib/log.js**：新版 `proc-log` 的日志级别函数与 `pause` / `resume` 挂在默认导出的 `log` 对象下，而非包顶层。之前误用 `procLog.pause()` 等写法，导致 `configure` 阶段直接抛出 `TypeError`，全流程无法启动。
+- **lib/process-release.js**：弃用 `url.resolve()` / `url.parse()`，改用 WHATWG `URL`，消除新版 Node 的 `DEP0169` 弃用警告。
+- **Windows 外部头警告抑制**：Node 官方 V8 头文件会触发 `warning C4018` 等噪音。现在在 gyp 中注册 `ExternalWarningLevel` 属性，并在 `addon.gypi` 中使用 `/external:anglebrackets` + `ExternalWarningLevel: TurnOffAllWarnings`。只对 `#include <...>` 的外部头（Node / V8）静音，不影响下游自己代码的警告；且通过 MSBuild 属性而非命令行 `/external:W0`，避免与默认的 `/external:W3` 冲突产生 `D9025`。
+
+### 变更
+
+- **package.json**
+  - `bin` 改为对象形式 `{ "nodejs-mobile-gyp": "./bin/node-gyp.js" }`，与上游命令名保持一致，避免与 `node-gyp` 包混淆。
+  - `engines.node` 提升到匹配依赖链（`make-fetch-happen`、`nopt`、`proc-log`、`which` 等）的最低版本要求。
+- **README.md**：CLI 调用命令修正为 `npx @flun/nodejs-mobile-gyp`；补充 Node 版本要求；移除对内部 `Gyp` API 的示例承诺。
+
+### 验证
+
+- 在 Windows + VS2026 BuildTools + Python 3.14 + Node 26.8.1 环境下，`configure` + `build` 全流程通过，0 warning / 0 error。
+- 生成的 `.node` 可被 Node 正常 `require()` 加载并调用。
+
 ## [1.0.1] - 2026-09-21
 
 ### 首发
@@ -25,7 +76,7 @@
 
 ### 依赖升级
 
-- `tar`: `^6.1.2` → `^7.5.21`
+- `tar`: `^6.1.2` → `^7.5.22`
 - `glob`: `^10.3.10` → `^13.0.6`
 - `make-fetch-happen`: `^13.0.0` → `^16.0.1`
 - 连带消除 `inflight`、`rimraf@3`、旧版 `glob` 等停更依赖
@@ -33,4 +84,4 @@
 ### 验证
 
 - Windows + VS2026 BuildTools + Python 3.14 + Node 26.8.1 环境下，`configure` + `build` 全流程通过
-- 生成的 `.node` 能被 Node 正常加载
+- 生成的 `.node` 能被 Node 正常加载

package/README.md

@@ -4,6 +4,8 @@
 
 用于为 [nodejs-mobile](https://github.com/nodejs-mobile/nodejs-mobile) 环境编译 C/C++ 原生模块，支持 Android 与 iOS 的交叉编译。
 
+宿主平台支持 **Windows** / **macOS** / **Linux**，各平台所需的环境与工具见「[支持的系统与配置要求](#支持的系统与配置要求)」。
+
 [`@flun/nodejs-mobile-react-native`](https://www.npmjs.com/package/@flun/nodejs-mobile-react-native) 在构建时会自动调用本包，无需手动安装。
 
 本包是 [`nodejs-mobile-gyp`](https://github.com/nodejs-mobile/nodejs-mobile-gyp) 的 flun fork，后者又基于上游 [`node-gyp`](https://github.com/nodejs/node-gyp)。
@@ -33,8 +35,8 @@
 │   ├── process-release.js        # 解析下载 URL、本地目录名、headers 与 node.lib 地址
 │   ├── download.js               # 基于 make-fetch-happen 的 HTTP 下载与 CA 读取
 │   ├── find-node-directory.js    # 推断 Node 安装根目录（用于 AIX / zOS）
-│   ├── find-python.js            # PythonFinder 类：按顺序定位可用的 Python 3.6+
-│   ├── find-visualstudio.js      # VisualStudioFinder 类：定位可用的 VS 安装（含 VS2026）
+│   ├── find-python.js            # PythonFinder 类：动态定位 Python 3.6+（py 启动器 / 目录扫描）
+│   ├── find-visualstudio.js      # VisualStudioFinder 类：定位可用的 VS 安装（VS2013+，含 VS2026）
 │   ├── Find-VisualStudio.cs      # PowerShell 调用的 C# 脚本，枚举 VS 安装信息
 │   ├── log.js                    # Logger 类 + proc-log 包装，分级着色日志
 │   └── util.js                   # 通用工具：execFile 包装、注册表读取、候选文件查找
@@ -61,7 +63,7 @@
 │   └── win_delay_load_hook.cc    # Windows 加载延迟钩子（编译进每个原生模块）
 │
 ├── addon.gypi                    # 所有原生模块共用的 gyp 配置
-├── package.json                  # type: module，bin 指向 bin/node-gyp.js
+├── package.json                  # type: module，bin 命令名为 nodejs-mobile-gyp
 ├── LICENSE                       # 本包许可证（ISC）
 ├── README.md                     # 本文件
 ├── CHANGELOG.md                  # 版本变更记录
@@ -96,20 +98,57 @@
 
 ### Windows 构建适配
 
-原版在 Windows 上默认走 ClangCL 工具集，且继承 Node 官方二进制的 LTO 配置。Node.js 24+ 官方二进制由 ClangCL + ThinLTO 编译，其 `common.gypi` 会在 `clang==1` 时把 MSBuild 工具集设为 `ClangCL`，并在 `enable_lto==true` / `enable_thin_lto==true` 时向链接器传入 `-flto=thin`、`/opt:lldltojobs` 等 Clang 专用参数。若用户本机没装 ClangCL，或用的是传统 MSVC 工具链，会报以下错误：
+原版 `nodejs-mobile-gyp` 在 Windows 上有若干问题，本 fork 逐一解决，涉及三方面。
+
+#### 1. 工具集与 LTO
+
+原版默认走 ClangCL 工具集，且继承 Node 官方二进制的 LTO 配置。Node.js 24+ 官方二进制由 ClangCL + ThinLTO 编译，其 `common.gypi` 会在 `clang==1` 时把 MSBuild 工具集设为 `ClangCL`，并在 `enable_lto==true` / `enable_thin_lto==true` 时向链接器传入 `-flto=thin`、`/opt:lldltojobs` 等 Clang 专用参数。若用户本机没装 ClangCL，或用的是传统 MSVC 工具链，会报：
 
 - `MSB8020: 无法找到 ClangCL 的生成工具`
 - `LNK1117: 选项"opt:lldltojobs=2"中的语法错误`
 
-本 fork 强制走 MSVC 工具集并关闭 LTO，避免上述报错。
+本 fork 强制走 MSVC 工具集并关闭 LTO，避免上述报错。工具集版本从 `find-visualstudio` 的探测结果**动态获取**（`v140` / `v141` / `v142` / `v143` / `v145`...），不写死。
+
+#### 2. GNU make 的 POSIX 环境
+
+Android 原生模块通过 GNU make 构建，其 Makefile 会调用 `printf`、`xargs`、`sed` 等 Unix 命令。GNU make 需要一个 POSIX shell（`sh.exe`）来执行它们；Windows 上若无，会直接报 `CreateProcess(NULL, printf ...) failed`。本 fork 自动定位 Git for Windows 的 `usr/bin` 并前置到 PATH，详见「[支持的系统与配置要求](#支持的系统与配置要求) → 自动探测」。
+
+#### 3. 路径分隔符
+
+gyp 生成的 Makefile 中，路径原本会带上 Windows 的反斜杠（如 `src\bufferutil.o`），导致 `sh` / `sed` / `make` 解析失败。本 fork 在 gyp 的路径生成环节统一转成正斜杠；该改动在非 Windows 平台上是 no-op。
 
 ### 具体改动清单
 
-| 文件                        | 改动                                                                                                                                                                 |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lib/create-config-gypi.js` | 生成 `config.gypi` 时，把 `clang` 置 0，`enable_lto` / `enable_thin_lto` 置 `'false'`，`lto_jobs` 置空。避免 `common.gypi` 把工具集改成 ClangCL、向 MSVC 传 LTO 参数 |
-| `lib/configure.js`          | 调用 gyp 时追加 `-Gmsvs_toolset=v145`，显式指定 VS2026 工具集                                                                                                        |
-| `lib/find-visualstudio.js`  | 支持 VS2026（版本号 18，`versionYear=2026`，toolset `v145`）                                                                                                         |
+#### 构建工具链
+
+| 文件 | 改动 |
+| --- | --- |
+| `lib/create-config-gypi.js` | 生成 `config.gypi` 时把 `clang` 置 0、`enable_lto` / `enable_thin_lto` 置 `'false'`、`lto_jobs` 置空，避免 `common.gypi` 切到 ClangCL 并向 MSVC 传 LTO 参数 |
+| `lib/configure.js` | 调用 gyp 时追加 `-Gmsvs_toolset=<探测到的 toolset>`，不再写死 `v145` |
+| `lib/find-visualstudio.js` | 支持 VS2013+，含最新 VS2026（版本号 18，`versionYear=2026`，toolset `v145`） |
+| `gyp/pylib/gyp/MSVSSettings.py` | 注册 `ExternalWarningLevel`（MSBuild 属性），供 `addon.gypi` 使用 |
+| `addon.gypi` | Windows 下追加 `/external:anglebrackets` + `ExternalWarningLevel: TurnOffAllWarnings`，只静音外部头（Node / V8）的警告 |
+
+#### 跨平台路径
+
+| 文件 | 改动 |
+| --- | --- |
+| `gyp/pylib/gyp/common.py` | `RelativePath` 返回值统一转正斜杠 |
+| `gyp/pylib/gyp/generator/make.py` | `Absolutify` 返回正斜杠；新增 `slashpath` 供 `mkdir` 使用；Windows 下跳过 `node_modules` 中的超长 gypi 依赖 |
+
+#### Windows 运行时探测
+
+| 文件 | 改动 |
+| --- | --- |
+| `lib/find-python.js` | 重写：移除硬编码版本列表，改为 `py.exe` 候选 + `py -0p` 枚举 + 目录扫描；`run()` 显式检查 `execFile` 的 err |
+| `lib/build.js` | 区分「宿主 Windows」与「Android 交叉编译」；自动探测 `sh.exe` 并前置到 PATH；为 Python 创建 `python3.cmd` shim |
+
+#### 兼容性与健壮性
+
+- **`proc-log` 新版本兼容**：新版把日志级别函数与 `pause` / `resume` 挂在默认导出的 `log` 对象下。本 fork 已按此调整 `lib/log.js`，否则 `configure` 阶段会抛 `TypeError`。
+- **弃用 API 清理**：`lib/process-release.js` 不再用 `url.resolve()` / `url.parse()`，改用 WHATWG `URL`，消除 `DEP0169` 警告。
+- **依赖脚本放行**：`package.json` 显式声明 `allowScripts`，适配新版 npm 默认禁止依赖执行安装脚本的行为。
+
 
 ### 迁移踩过的坑
 
@@ -134,6 +173,80 @@
 7. **非 Windows 平台不引入 `find-visualstudio.js`**
    该模块依赖 Windows 专属的 `path.win32` 和注册表操作，保持原版的"仅在 Windows 上条件加载"逻辑。
 
+## 支持的系统与配置要求
+
+本包面向 **Android / iOS 交叉编译**，宿主平台支持情况：
+
+| 宿主平台 | 目标：Android | 目标：iOS  |
+| -------- | ------------- | ---------- |
+| Windows  | ✅ 完整支持    | ❌ 需 macOS |
+| macOS    | ✅ 完整支持    | ✅ 完整支持 |
+| Linux    | ✅ 完整支持    | ❌ 需 macOS |
+
+各平台所需的构建环境如下。
+
+### 通用要求
+
+- **Node.js**：最低版本见 `package.json` 的 `engines.node` 字段
+- **Python 3.6+**：gyp 本身是 Python 程序，构建时必需
+- **目标平台 SDK**：
+  - Android：Android NDK（已在 NDK **27.x** 上验证）
+  - iOS：Xcode Command Line Tools（仅 macOS）
+
+### Windows
+
+| 组件            | 要求                                    | 说明                                                        |
+| --------------- | --------------------------------------- | ----------------------------------------------------------- |
+| Node.js         | 见 `engines.node`                       |                                                             |
+| Python          | 3.6+                                    | 支持任意安装位置，见下方「自动探测」                        |
+| Visual Studio   | **VS2026**（版本号 18，toolset `v145`） | 需勾选「使用 C++ 的桌面开发」工作负载，含 Windows SDK       |
+| Android NDK     | 27.x（已验证）                          | 由 `@flun/nodejs-mobile-react-native` 自动定位              |
+| Git for Windows | 任意近期版本                            | 提供 make 所需的 `sh.exe` / `printf` / `xargs` 等 Unix 工具 |
+
+> **为什么需要 Git for Windows？** Android 原生模块通过 GNU make 构建，Makefile 中会调用 `printf`、`xargs`、`sed` 等 Unix 命令。GNU make 需要一个 POSIX shell（`sh.exe`）来执行它们，而 Git for Windows 自带完整的这套工具链，无需额外安装 MSYS2 或 Cygwin。
+
+### macOS
+
+| 组件        | 要求                             |
+| ----------- | -------------------------------- |
+| Node.js     | 见 `engines.node`                |
+| Python      | 3.6+                             |
+| Xcode       | 完整 Xcode 或 Command Line Tools |
+| Android NDK | 仅构建 Android 目标时需 27.x     |
+
+### Linux
+
+| 组件        | 要求                                                   |
+| ----------- | ------------------------------------------------------ |
+| Node.js     | 见 `engines.node`                                      |
+| Python      | 3.6+                                                   |
+| 构建工具    | `make`、`g++`（`apt install build-essential python3`） |
+| Android NDK | 仅构建 Android 目标时需 27.x                           |
+
+### 自动探测（Windows）
+
+Windows 上以下路径 / 版本由本包动态探测，**无需手动配置**：
+
+- **Python**，依次尝试：
+  1. `NODE_GYP_FORCE_PYTHON` 环境变量
+  2. 命令行 `--python=`
+  3. `PYTHON` 环境变量
+  4. `py.exe` 启动器（PATH 中、`%SystemRoot%\py.exe`、`%SystemRoot%\System32\py.exe`）
+  5. `py -0p` 枚举所有已注册 Python
+  6. `python3` / `python` 命令
+  7. 扫描 `%LOCALAPPDATA%\Programs\Python\Python*` 与 `%ProgramFiles%\Python*`
+
+- **POSIX shell（`sh.exe`）**，依次尝试：
+  1. 注册表 `HKLM\SOFTWARE\GitForWindows` 的 `InstallPath`
+  2. `which git` 反推 `../usr/bin`
+  3. `PATH` 中的 `git.exe` 反推 `../usr/bin`
+  4. 常见安装位置兜底
+
+- **Android NDK**：由 `@flun/nodejs-mobile-react-native` 通过 `android.ndkDirectory` 定位，并注入 `make.exe`、`clang` 等工具路径。
+
+> 本包不依赖任何随包分发的硬编码配置文件。上述探测均为运行时动态完成；仅 Visual Studio 的「版本号 → 版本年份 → toolset」对照表以常量形式内联在 `lib/find-visualstudio.js` 中——这类信息由微软固定发布，无枚举接口，且随 VS 版本发布而更新，不适合做成外部资源。
+
+
 ## 安装
 
 ```bash
@@ -142,12 +255,14 @@ npm install @flun/nodejs-mobile-gyp
 
 通常你不需要手动安装本包——它由 [`@flun/nodejs-mobile-react-native`](https://www.npmjs.com/package/@flun/nodejs-mobile-react-native) 在编译原生模块时自动调用。
 
+> **Node 版本要求**：本 fork 的依赖链（`make-fetch-happen`、`nopt`、`proc-log`、`which` 等）已升级到较新版本，要求比原版 `nodejs-mobile-gyp` 更高的 Node。具体最低版本见 `package.json` 的 `engines.node` 字段。若你的项目仍在使用较旧的 Node，请改用原版 `nodejs-mobile-gyp`。
+
 ## 使用
 
 ### 命令行
 
 ```bash
-npx node-gyp <command> [options]
+npx @flun/nodejs-mobile-gyp <command> [options]
 ```
 
 或在 `package.json` 的 `scripts` 中调用：
@@ -155,20 +270,14 @@ npx node-gyp <command> [options]
 ```json
 {
   "scripts": {
-    "build-addon": "node-gyp rebuild"
+    "build-addon": "nodejs-mobile-gyp rebuild"
   }
 }
 ```
 
 ### 从 Node.js 代码调用
 
-```js
-import createGyp from '@flun/nodejs-mobile-gyp'
-
-const gyp = createGyp()
-gyp.parseArgv(process.argv)
-// gyp.todo 是待执行的命令队列
-```
+本包主要作为 CLI 工具使用，推荐通过 spawn / execFile 调用其命令行入口。包本身也导出了 Gyp 类，但属于内部实现，接口可能随版本变化，不建议直接在代码中依赖。
 
 ## 命令
 
@@ -187,6 +296,7 @@ gyp.parseArgv(process.argv)
 
 | 选项                              | 说明                                               |
 | --------------------------------- | -------------------------------------------------- |
+| `-v`, `--version`                 | 打印本包版本号                                     |
 | `-j n`, `--jobs n`                | 并行运行 `make`；`max` 表示使用所有 CPU 核心       |
 | `--target=v6.2.1`                 | 目标 Node.js 版本（默认 `process.version`）        |
 | `--silly`, `--loglevel=silly`     | 输出全部进度日志                                   |
@@ -207,7 +317,7 @@ gyp.parseArgv(process.argv)
 | `--cafile=$cafile`                | 覆盖默认 CA 链（用于下载 tarball）                 |
 | `--nodedir=$path`                 | 指定 Node 源码路径                                 |
 | `--python=$path`                  | 指定 Python 二进制路径                             |
-| `--msvs_version=$version`         | 指定 Visual Studio 版本（仅 Windows）              |
+| `--msvs_version=$version`         | 指定 Visual Studio 版本或安装路径（仅 Windows；可填 `2022` / `2026` 或 `C:\...\BuildTools`） |
 | `--solution=$solution`            | 指定 Visual Studio Solution 版本（仅 Windows）     |
 | `--force-process-config`          | 强制用运行时的 `process.config` 生成 `config.gypi` |
 
@@ -237,7 +347,7 @@ set npm_config_devdir=c:\temp\.gyp
 npm config set [--global] devdir /tmp/.gyp
 ```
 
-**注意**：通过 `npm config` 设置的配置，只在 `node-gyp` **由 npm 调用时**生效，直接运行 `node-gyp` 不生效。
+**注意**：通过 `npm config` 设置的配置，只在本包 **由 npm 调用时**生效，直接运行 `nodejs-mobile-gyp` 不生效。
 
 ## 上游参考
 

package/addon.gypi

@@ -146,6 +146,18 @@
         ],
       }],
       [ 'OS=="win"', {
+        'msvs_settings': {
+          'VCCLCompilerTool': {
+            # /external:anglebrackets：把 <...> 引用的 Node / V8 头视为外部头，
+            # 只对它们抑制警告；下游自己代码（#include "..."）不受影响。
+            # 警告级别用 ExternalWarningLevel 属性设置，而不是命令行 /external:W0，
+            # 避免与 MSBuild 默认的 /external:W3 冲突而产生 D9025。
+            'AdditionalOptions': [
+              '/external:anglebrackets'
+            ],
+            'ExternalWarningLevel': 'TurnOffAllWarnings'
+          }
+        },
         'conditions': [
           ['node_engine=="chakracore"', {
             'library_dirs': [ '<(node_root_dir)/$(ConfigurationName)' ],
@@ -154,7 +166,7 @@
           ['node_with_ltcg=="true"', {
             'msvs_settings': {
               'VCCLCompilerTool': {
-                'WholeProgramOptimization': 'true' # /GL, whole program optimization, needed for LTCG
+                'WholeProgramOptimization': 'true', # /GL, whole program optimization, needed for LTCG
               },
               'VCLibrarianTool': {
                 'AdditionalOptions': [

package/bin/node-gyp.js

@@ -1,68 +1,51 @@
 #!/usr/bin/env node
 
-import envPaths from 'env-paths'
-import os from 'os'
-import fs from 'fs'
-import { Gyp } from '../lib/node-gyp.js'
-import * as log from '../lib/log.js'
+import envPaths from 'env-paths';
+import os from 'os';
+import fs from 'fs';
+import { Gyp } from '../lib/node-gyp.js';
+import * as log from '../lib/log.js';
 
-process.title = 'node-gyp'
+process.title = 'node-gyp';
 
 /**
  * 处理并执行选中的命令。
  */
 
-const prog = new Gyp()
-let completed = false
-prog.parseArgv(process.argv)
-prog.devDir = prog.opts.devdir
+const prog = new Gyp(), homeDir = os.homedir();
+let completed = false;
+prog.parseArgv(process.argv), prog.devDir = prog.opts.devdir;
 
-const homeDir = os.homedir()
-if (prog.devDir) {
-  prog.devDir = prog.devDir.replace(/^~/, homeDir)
-} else if (homeDir) {
-  prog.devDir = envPaths('node-gyp', { suffix: '' }).cache
-} else {
+if (prog.devDir) prog.devDir = prog.devDir.replace(/^~/, homeDir);
+else if (homeDir) prog.devDir = envPaths('node-gyp', { suffix: '' }).cache;
+else {
   throw new Error(
     "node-gyp requires that the user's home directory is specified " +
     'in either of the environmental variables HOME or USERPROFILE. ' +
-    'Overide with: --devdir /path/to/.node-gyp')
+    'Overide with: --devdir /path/to/.node-gyp');
 }
 
 if (prog.todo.length === 0) {
-  if (~process.argv.indexOf('-v') || ~process.argv.indexOf('--version')) {
-    log.stdout('v%s', prog.version)
-  } else {
-    log.stdout('%s', prog.usage())
-  }
-  process.exit(0)
+  if (~process.argv.indexOf('-v') || ~process.argv.indexOf('--version')) log.stdout('v%s', prog.version);
+  else log.stdout('%s', prog.usage());
+  process.exit(0);
 }
 
-log.info('it worked if it ends with', 'ok')
-log.verbose('cli', process.argv)
-log.info('using', 'node-gyp@%s', prog.version)
-log.info('using', 'node@%s | %s | %s', process.versions.node, process.platform, process.arch)
+log.info('it worked if it ends with', 'ok'), log.verbose('cli', process.argv), log.info('using', 'node-gyp@%s', prog.version);
+log.info('using', 'node@%s | %s | %s', process.versions.node, process.platform, process.arch);
 
 /**
- * 如果传了 -C/--directory，切换到该目录。
+ * 如果传了 -C/--directory,切换到该目录;
  */
-
-const dir = prog.opts.directory
+const dir = prog.opts.directory;
 if (dir) {
   try {
-    const stat = fs.statSync(dir)
-    if (stat.isDirectory()) {
-      log.info('chdir', dir)
-      process.chdir(dir)
-    } else {
-      log.warn('chdir', dir + ' is not a directory')
-    }
+    const stat = fs.statSync(dir);
+    if (stat.isDirectory()) log.info('chdir', dir), process.chdir(dir);
+    else log.warn('chdir', dir + ' 不是目录');
   } catch (e) {
-    if (e.code === 'ENOENT') {
-      log.warn('chdir', dir + ' is not a directory')
-    } else {
-      log.warn('chdir', 'error during chdir() "%s"', e.message)
-    }
+    if (e.code === 'ENOENT') log.warn('chdir', dir + ' 不是目录');
+    else log.warn('chdir', 'chdir() 出错 "%s"', e.message);
   }
 }
 
@@ -71,74 +54,48 @@ if (dir) {
  */
 const errorMessage = () => {
   // 复制自 npm 的 lib/utils/error-handler.js
-  log.error('System', os.type() + ' ' + os.release())
-  log.error('command', process.argv
-    .map(JSON.stringify).join(' '))
-  log.error('cwd', process.cwd())
-  log.error('node -v', process.version)
-  log.error('node-gyp -v', 'v' + prog.package.version)
-}
-
-/**
- * 打印最终诊断信息
- */
-const issueMessage = () => {
-  errorMessage()
-  log.error('', ['Node-gyp failed to build your package.',
-    'Try to update npm and/or node-gyp and if it does not help file an issue with the package author.'
-  ].join('\n'))
-}
-
-/**
- * 依次执行队列中的命令
- */
-const run = async () => {
-  const command = prog.todo.shift()
-  if (!command) {
-    // 完成！
-    completed = true
-    log.info('ok')
-    return
-  }
-
-  try {
-    const args = await prog.commands[command.name](command.args) ?? []
-
-    if (command.name === 'list') {
-      if (args.length) {
-        args.forEach((version) => log.stdout(version))
-      } else {
-        log.stdout('No node development files installed. Use `node-gyp install` to install a version.')
+  log.error('System', os.type() + ' ' + os.release());
+  log.error('command', process.argv.map(JSON.stringify).join(' ')), log.error('cwd', process.cwd());
+  log.error('node -v', process.version), log.error('node-gyp -v', 'v' + prog.package.version);
+},
+  /**
+   * 打印最终诊断信息
+   */
+  issueMessage = () => {
+    errorMessage();
+    log.error('', ['node-gyp 构建你的包失败!', '请尝试更新 npm 和/或 node-gyp;若仍无法解决,请向包作者反馈;'].join('\n'));
+  },
+  /**
+   * 依次执行队列中的命令
+   */
+  run = async () => {
+    const command = prog.todo.shift()
+    if (!command) {
+      // 完成！
+      completed = true, log.info('ok');
+      return;
+    };
+
+    try {
+      const args = await prog.commands[command.name](command.args) ?? [];
+
+      if (command.name === 'list') {
+        if (args.length) args.forEach((version) => log.stdout(version));
+        else log.stdout('尚未安装任何 Node 开发文件;可用 `node-gyp install` 安装指定版本;')
       }
-    } else if (args.length >= 1) {
-      log.stdout(...args.slice(1))
+      else if (args.length >= 1) log.stdout(...args.slice(1))
+      return run(); // 继续执行队列中的下一条命令
+    } catch (err) {
+      log.error(command.name + ' error'), log.error('stack', err.stack), errorMessage(), log.error('not ok');
+      return process.exit(1);
     }
+  };
 
-    // 继续执行队列中的下一条命令
-    return run()
-  } catch (err) {
-    log.error(command.name + ' error')
-    log.error('stack', err.stack)
-    errorMessage()
-    log.error('not ok')
-    return process.exit(1)
-  }
-}
-
-process.on('exit', function (code) {
-  if (!completed && !code) {
-    log.error('Completion callback never invoked!')
-    issueMessage()
-    process.exit(6)
-  }
-})
-
-process.on('uncaughtException', function (err) {
-  log.error('UNCAUGHT EXCEPTION')
-  log.error('stack', err.stack)
-  issueMessage()
-  process.exit(7)
-})
+process.on('exit', code => {
+  if (!completed && !code) log.error('完成回调未被调用！'), issueMessage(), process.exit(6);
+});
+process.on('uncaughtException', err => {
+  log.error('未捕获的异常'), log.error('stack', err.stack), issueMessage(), process.exit(7);
+});
 
-// 开始执行给定命令！
-run()
+run(); // 开始执行给定命令！

package/gyp/pylib/gyp/MSVSSettings.py

@@ -797,6 +797,19 @@ _MSBuildOnly(_compile, "MultiProcessorCompilation", _boolean)  # /MP
 _MSBuildOnly(_compile, "PreprocessOutputPath", _string)  # /Fi
 _MSBuildOnly(_compile, "ProcessorNumber", _integer)  # the number of processors
 _MSBuildOnly(_compile, "TrackerLogDirectory", _folder_name)
+_MSBuildOnly(
+    _compile,
+    "ExternalWarningLevel",
+    _Enumeration(
+        [
+            "TurnOffAllWarnings",  # /external:W0
+            "Level1",  # /external:W1
+            "Level2",  # /external:W2
+            "Level3",  # /external:W3
+            "Level4",  # /external:W4
+        ]
+    ),
+)  # /external:W
 _MSBuildOnly(_compile, "TreatSpecificWarningsAsErrors", _string_list)  # /we
 _MSBuildOnly(_compile, "UseUnicodeForAssemblerListing", _boolean)  # /FAu
 

package/gyp/pylib/gyp/common.py

@@ -153,7 +153,9 @@ def RelativePath(path, relative_to, follow_path_symlink=True):
         os.path.splitdrive(path)[0].lower()
         != os.path.splitdrive(relative_to)[0].lower()
     ):
-        return path
+        # Makefile / cmake / ninja 等生成器要求 POSIX 路径，统一用正斜杠。
+        # MSBuild 也接受正斜杠，故对 msvs 无影响。
+        return path.replace(os.sep, "/")
 
     # Split the paths into components.
     path_split = path.split(os.path.sep)
@@ -173,7 +175,8 @@ def RelativePath(path, relative_to, follow_path_symlink=True):
         return ""
 
     # Turn it back into a string and we're done.
-    return os.path.join(*relative_split)
+    # Makefile / cmake / ninja 等生成器要求 POSIX 路径，统一用正斜杠。
+    return os.path.join(*relative_split).replace(os.sep, "/")
 
 
 @memoize

package/gyp/pylib/gyp/generator/make.py

@@ -24,6 +24,7 @@
 
 import os
 import re
+import sys
 import subprocess
 import gyp
 import gyp.common
@@ -410,6 +411,7 @@ unreplace_spaces = $(subst """
     + SPACE_REPLACEMENT
     + """,$(space),$1)
 dirx = $(call unreplace_spaces,$(dir $(call replace_spaces,$1)))
+slashpath = $(subst \\,/,$(1))
 
 # Flags to make gcc output dependency info.  Note that you need to be
 # careful here to use the flags that ccache and distcc can understand.
@@ -547,7 +549,7 @@ endef
 define do_cmd
 $(if $(or $(command_changed),$(prereq_changed)),
   @$(call exact_echo,  $($(quiet)cmd_$(1)))
-  @mkdir -p "$(call dirx,$@)" "$(dir $(depfile))"
+  @mkdir -p "$(call slashpath,$(call dirx,$@))" "$(call slashpath,$(dir $(depfile)))"
   $(if $(findstring flock,$(word %(flock_index)d,$(cmd_$1))),
     @$(cmd_$(1))
     @echo "  $(quiet_cmd_$(1)): Finished",
@@ -2318,7 +2320,9 @@ $(obj).$(TOOLSET)/$(TARGET)/%%.o: $(obj)/%%%s FORCE_DO_CMD
             # path too aggressively if it features '..'. However it's still
             # important to strip trailing slashes.
             return path.rstrip("/")
-        return os.path.normpath(os.path.join(self.path, path))
+        # Makefile 要求 POSIX 路径；Windows 上 normpath 会把 "/" 变成 "\"，
+        # 导致编译产物路径（.o / .d.raw）带反斜杠，sh 与 sed 解析失败。
+        return os.path.normpath(os.path.join(self.path, path)).replace(os.sep, "/")
 
     def ExpandInputRoot(self, template, expansion, dirname):
         if "%(INPUT_ROOT)s" not in template and "%(INPUT_DIRNAME)s" not in template:
@@ -2361,6 +2365,17 @@ def WriteAutoRegenerationRule(params, root_makefile, makefile_name, build_files)
     if not gyp_binary.startswith(os.sep):
         gyp_binary = os.path.join(".", gyp_binary)
 
+    # Windows 下 GNU make（NDK 自带）对深层相对路径的解析有缺陷，会把
+    # 形如 $(srcdir)/../../.. 的外部 gypi 判为 "No rule to make target"。
+    # 这里跳过所有来自 node_modules 的依赖——它们是只读的外部 gypi，
+    # 内容不会在编译过程中变化；如确需重新生成 Makefile，重跑 configure 即可。
+    # 本地的 binding.gyp 与 build/config.gypi 仍会保留，足以触发自动重新生成。
+    deps_list = []
+    for bf in build_files:
+        if sys.platform == "win32" and "node_modules" in bf.replace("\\", "/"):
+            continue
+        deps_list.append(SourceifyAndQuoteSpaces(bf))
+
     root_makefile.write(
         "quiet_cmd_regen_makefile = ACTION Regenerating $@\n"
         "cmd_regen_makefile = cd $(srcdir); %(cmd)s\n"
@@ -2368,7 +2383,7 @@ def WriteAutoRegenerationRule(params, root_makefile, makefile_name, build_files)
         "\t$(call do_cmd,regen_makefile)\n\n"
         % {
             "makefile_name": makefile_name,
-            "deps": " ".join(SourceifyAndQuoteSpaces(bf) for bf in build_files),
+            "deps": " ".join(deps_list),
             "cmd": gyp.common.EncodePOSIXShellList(
                 [gyp_binary, "-fmake"] + gyp.RegenerateFlags(options) + build_files_args
             ),