@flun/nodejs-mobile-gyp 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +53 -53
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,22 @@
1
1
  # Changelog
2
2
 
3
+ ## [1.1.1] - 2026-09-28 09:23
4
+
5
+ ### 文档
6
+
7
+ 全面核对并修正 README，消除前后矛盾、过时表述与硬编码：
8
+
9
+ - **系统要求**：
10
+ - iOS 构建前置工具从「Command Line Tools」修正为「**完整 Xcode**」——`xcodebuild` 必须完整 Xcode，CLT 单独不够；
11
+ - Visual Studio 从「仅 VS2026」放宽为「**VS2019 / VS2022 / VS2026**」——VS2017 及更早受 Node 版本上限限制，故不在支持范围；VS2026 为已验证版本；
12
+ - Android NDK 从「27.x」修正为「**23–27**」，与实测验证范围一致；
13
+ - Git for Windows 的说明从「提供 `sh.exe` / `printf` / `xargs`」扩写为「**自带整套 MSYS2 POSIX 工具集**」，避免读者低估其必要性。
14
+ - **自动探测**：
15
+ - 「无需手动配置」改为「**无需手动指定路径**（前提：工具已安装）」，区分「必须安装」与「位置自动定位」；
16
+ - 「POSIX shell（`sh.exe`）」项改为「**Git for Windows 的 `usr/bin` 目录**（以 `sh.exe` 是否存在作为判据）」，与实际探测逻辑一致。
17
+ - **顶部引言**：适用范围从仅官方 `nodejs-mobile` 改为「官方及兼容的社区发行版（如 OpenFlun/nodejs-mobile）」。
18
+ - 修正若干失效链接。
19
+
3
20
  ## [1.1.0] - 2026-09-27 16:01
4
21
 
5
22
  ### 新增
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  移动端 Node.js 原生模块（Native Addon）的交叉编译工具。
4
4
 
5
- 用于为 [nodejs-mobile](https://github.com/nodejs-mobile/nodejs-mobile) 环境编译 C/C++ 原生模块，支持 Android 与 iOS 的交叉编译。
5
+ 用于为 nodejs-mobile 环境编译 C/C++ 原生模块，支持 Android 与 iOS 的交叉编译。适用于官方 [nodejs-mobile](https://github.com/nodejs-mobile/nodejs-mobile) 及兼容的社区发行版（如 [OpenFlun/nodejs-mobile](https://github.com/OpenFlun/nodejs-mobile)）。
6
6
 
7
7
  宿主平台支持 **Windows** / **macOS** / **Linux**，各平台所需的环境与工具见「[支持的系统与配置要求](#支持的系统与配置要求)」。
8
8
 
@@ -111,7 +111,7 @@
111
111
 
112
112
  #### 2. GNU make 的 POSIX 环境
113
113
 
114
- 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，详见「[支持的系统与配置要求](#支持的系统与配置要求) → 自动探测」。
114
+ Android 原生模块通过 GNU make 构建，其 Makefile 会调用 `printf`、`xargs`、`sed` 等 Unix 命令。GNU make 需要一个 POSIX shell（`sh.exe`）来执行它们；Windows 上若无，会直接报 `CreateProcess(NULL, printf ...) failed`。Git for Windows 自带整套 POSIX 工具集；本 fork 会自动定位其 `usr/bin` 并前置到 PATH，详见「[支持的系统与配置要求](#支持的系统与配置要求) → 自动探测」。
115
115
 
116
116
  #### 3. 路径分隔符
117
117
 
@@ -121,27 +121,27 @@ gyp 生成的 Makefile 中，路径原本会带上 Windows 的反斜杠（如 `s
121
121
 
122
122
  #### 构建工具链
123
123
 
124
- | 文件 | 改动 |
125
- | --- | --- |
126
- | `lib/create-config-gypi.js` | 生成 `config.gypi` 时把 `clang` 置 0、`enable_lto` / `enable_thin_lto` 置 `'false'`、`lto_jobs` 置空，避免 `common.gypi` 切到 ClangCL 并向 MSVC 传 LTO 参数 |
127
- | `lib/configure.js` | 调用 gyp 时追加 `-Gmsvs_toolset=<探测到的 toolset>`，不再写死 `v145` |
128
- | `lib/find-visualstudio.js` | 支持 VS2013+，含最新 VS2026（版本号 18，`versionYear=2026`，toolset `v145`） |
129
- | `gyp/pylib/gyp/MSVSSettings.py` | 注册 `ExternalWarningLevel`（MSBuild 属性），供 `addon.gypi` 使用 |
130
- | `addon.gypi` | Windows 下追加 `/external:anglebrackets` + `ExternalWarningLevel: TurnOffAllWarnings`，只静音外部头（Node / V8）的警告 |
124
+ | 文件 | 改动 |
125
+ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
126
+ | `lib/create-config-gypi.js` | 生成 `config.gypi` 时把 `clang` 置 0、`enable_lto` / `enable_thin_lto` 置 `'false'`、`lto_jobs` 置空，避免 `common.gypi` 切到 ClangCL 并向 MSVC 传 LTO 参数 |
127
+ | `lib/configure.js` | 调用 gyp 时追加 `-Gmsvs_toolset=<探测到的 toolset>`，不再写死 `v145` |
128
+ | `lib/find-visualstudio.js` | 支持 VS2013+，含最新 VS2026（版本号 18，`versionYear=2026`，toolset `v145`） |
129
+ | `gyp/pylib/gyp/MSVSSettings.py` | 注册 `ExternalWarningLevel`（MSBuild 属性），供 `addon.gypi` 使用 |
130
+ | `addon.gypi` | Windows 下追加 `/external:anglebrackets` + `ExternalWarningLevel: TurnOffAllWarnings`，只静音外部头（Node / V8）的警告 |
131
131
 
132
132
  #### 跨平台路径
133
133
 
134
- | 文件 | 改动 |
135
- | --- | --- |
136
- | `gyp/pylib/gyp/common.py` | `RelativePath` 返回值统一转正斜杠 |
134
+ | 文件 | 改动 |
135
+ | --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
136
+ | `gyp/pylib/gyp/common.py` | `RelativePath` 返回值统一转正斜杠 |
137
137
  | `gyp/pylib/gyp/generator/make.py` | `Absolutify` 返回正斜杠；新增 `slashpath` 供 `mkdir` 使用；Windows 下跳过 `node_modules` 中的超长 gypi 依赖 |
138
138
 
139
139
  #### Windows 运行时探测
140
140
 
141
- | 文件 | 改动 |
142
- | --- | --- |
143
- | `lib/find-python.js` | 重写：移除硬编码版本列表，改为 `py.exe` 候选 + `py -0p` 枚举 + 目录扫描；`run()` 显式检查 `execFile` 的 err |
144
- | `lib/build.js` | 区分「宿主 Windows」与「Android 交叉编译」；自动探测 `sh.exe` 并前置到 PATH；为 Python 创建 `python3.cmd` shim |
141
+ | 文件 | 改动 |
142
+ | -------------------- | -------------------------------------------------------------------------------------------------------------- |
143
+ | `lib/find-python.js` | 重写：移除硬编码版本列表，改为 `py.exe` 候选 + `py -0p` 枚举 + 目录扫描；`run()` 显式检查 `execFile` 的 err |
144
+ | `lib/build.js` | 区分「宿主 Windows」与「Android 交叉编译」；自动探测 `sh.exe` 并前置到 PATH；为 Python 创建 `python3.cmd` shim |
145
145
 
146
146
  #### 兼容性与健壮性
147
147
 
@@ -190,8 +190,8 @@ gyp 生成的 Makefile 中，路径原本会带上 Windows 的反斜杠（如 `s
190
190
  - **Node.js**：最低版本见 `package.json` 的 `engines.node` 字段
191
191
  - **Python 3.6+**：gyp 本身是 Python 程序，构建时必需
192
192
  - **目标平台 SDK**：
193
- - Android：Android NDK（已在 NDK **27.x** 上验证）
194
- - iOS：Xcode Command Line Tools（仅 macOS）
193
+ - Android：Android NDK（**23–27 已验证**）
194
+ - iOS：完整 Xcode（仅 macOS；Command Line Tools 单独不够）
195
195
 
196
196
  ### Windows
197
197
 
@@ -199,11 +199,11 @@ gyp 生成的 Makefile 中，路径原本会带上 Windows 的反斜杠（如 `s
199
199
  | --------------- | --------------------------------------- | ----------------------------------------------------------- |
200
200
  | Node.js | 见 `engines.node` | |
201
201
  | Python | 3.6+ | 支持任意安装位置，见下方「自动探测」 |
202
- | Visual Studio | **VS2026**（版本号 18，toolset `v145`） | 需勾选「使用 C++ 的桌面开发」工作负载，含 Windows SDK |
203
- | Android NDK | 27.x（已验证） | 由 `@flun/nodejs-mobile-react-native` 自动定位 |
204
- | Git for Windows | 任意近期版本 | 提供 make 所需的 `sh.exe` / `printf` / `xargs` 等 Unix 工具 |
202
+ | Visual Studio | **VS2019 / VS2022 / VS2026**（2026 已验证） | 需勾选「使用 C++ 的桌面开发」工作负载，含 Windows SDK；VS2017 及更早受 Node 版本上限限制 |
203
+ | Android NDK | **23–27**（已验证） | 由 `@flun/nodejs-mobile-react-native` 自动定位 |
204
+ | Git for Windows | 任意近期版本 | 自带**整套 MSYS2 POSIX 工具集**（`sh.exe`、`printf`、`xargs`、`sed`、`rm`、`mkdir` 等数十个命令），GNU make 执行 Makefile 所依赖的 Unix 命令均由它提供；位置自动探测（见下方） |
205
205
 
206
- > **为什么需要 Git for Windows？** Android 原生模块通过 GNU make 构建，Makefile 中会调用 `printf`、`xargs`、`sed` 等 Unix 命令。GNU make 需要一个 POSIX shell（`sh.exe`）来执行它们，而 Git for Windows 自带完整的这套工具链，无需额外安装 MSYS2 或 Cygwin。
206
+ > **为什么需要 Git for Windows？** Android 原生模块通过 GNU make 构建，Makefile 中会调用 `printf`、`xargs`、`sed` 等 Unix 命令。这些命令并非 Windows 自带，GNU make 需要一个 POSIX 环境来执行它们。Git for Windows 自带**整套 MSYS2 POSIX 工具集**（`sh.exe`、`printf`、`xargs`、`sed`、`rm`、`mkdir` 等数十个命令），无需额外安装 MSYS2 或 Cygwin。
207
207
 
208
208
  ### macOS
209
209
 
@@ -211,8 +211,8 @@ gyp 生成的 Makefile 中，路径原本会带上 Windows 的反斜杠（如 `s
211
211
  | ----------- | -------------------------------- |
212
212
  | Node.js | 见 `engines.node` |
213
213
  | Python | 3.6+ |
214
- | Xcode | 完整 Xcode 或 Command Line Tools |
215
- | Android NDK | 仅构建 Android 目标时需 27.x |
214
+ | Xcode | 完整 Xcode（必须，CLT 单独不够） |
215
+ | Android NDK | 仅构建 Android 目标时需 23–27 |
216
216
 
217
217
  ### Linux
218
218
 
@@ -221,11 +221,11 @@ gyp 生成的 Makefile 中，路径原本会带上 Windows 的反斜杠（如 `s
221
221
  | Node.js | 见 `engines.node` |
222
222
  | Python | 3.6+ |
223
223
  | 构建工具 | `make`、`g++`（`apt install build-essential python3`） |
224
- | Android NDK | 仅构建 Android 目标时需 27.x |
224
+ | Android NDK | 仅构建 Android 目标时需 23–27 |
225
225
 
226
226
  ### 自动探测（Windows）
227
227
 
228
- Windows 上以下路径 / 版本由本包动态探测，**无需手动配置**：
228
+ 以下工具的**安装位置**由本包动态探测，**无需手动指定路径**（前提：工具已安装）：
229
229
 
230
230
  - **Python**，依次尝试：
231
231
  1. `NODE_GYP_FORCE_PYTHON` 环境变量
@@ -236,7 +236,7 @@ Windows 上以下路径 / 版本由本包动态探测，**无需手动配置**
236
236
  6. `python3` / `python` 命令
237
237
  7. 扫描 `%LOCALAPPDATA%\Programs\Python\Python*` 与 `%ProgramFiles%\Python*`
238
238
 
239
- - **POSIX shell（`sh.exe`）**，依次尝试：
239
+ - **Git for Windows 的 `usr/bin` 目录**（POSIX 工具集所在处，以 `sh.exe` 是否存在作为判据），依次尝试：
240
240
  1. 注册表 `HKLM\SOFTWARE\GitForWindows` 的 `InstallPath`
241
241
  2. `which git` 反推 `../usr/bin`
242
242
  3. `PATH` 中的 `git.exe` 反推 `../usr/bin`
@@ -250,7 +250,7 @@ Windows 上以下路径 / 版本由本包动态探测，**无需手动配置**
250
250
  ## 安装
251
251
 
252
252
  ```bash
253
- npm install @flun/nodejs-mobile-gyp
253
+ npm i @flun/nodejs-mobile-gyp
254
254
  ```
255
255
 
256
256
  通常你不需要手动安装本包——它由 [`@flun/nodejs-mobile-react-native`](https://www.npmjs.com/package/@flun/nodejs-mobile-react-native) 在编译原生模块时自动调用。
@@ -294,32 +294,32 @@ npx @flun/nodejs-mobile-gyp <command> [options]
294
294
 
295
295
  ## 命令选项
296
296
 
297
- | 选项 | 说明 |
298
- | --------------------------------- | -------------------------------------------------- |
299
- | `-v`, `--version` | 打印本包版本号 |
300
- | `-j n`, `--jobs n` | 并行运行 `make`；`max` 表示使用所有 CPU 核心 |
301
- | `--target=v6.2.1` | 目标 Node.js 版本（默认 `process.version`） |
302
- | `--silly`, `--loglevel=silly` | 输出全部进度日志 |
303
- | `--verbose`, `--loglevel=verbose` | 输出大部分进度日志 |
304
- | `--silent`, `--loglevel=silent` | 不输出任何日志 |
305
- | `debug`, `--debug` | 生成 Debug 构建（默认 Release） |
306
- | `--release`, `--no-debug` | 生成 Release 构建 |
307
- | `-C $dir`, `--directory=$dir` | 在指定目录运行命令 |
308
- | `--make=$make` | 覆盖 `make` 命令（如 `gmake`） |
309
- | `--thin=yes` | 启用 thin 静态库 |
310
- | `--arch=$arch` | 目标架构（如 `ia32`） |
311
- | `--tarball=$path` | 从本地 tarball 获取头文件 |
312
- | `--devdir=$path` | SDK 下载目录（默认为系统缓存目录） |
313
- | `--ensure` | 已存在的头文件不重装 |
314
- | `--dist-url=$url` | 从自定义 URL 下载头文件 tarball |
315
- | `--proxy=$url` | 下载时使用 HTTP(S) 代理 |
316
- | `--noproxy=$urls` | 下载时忽略代理的 URL 列表 |
317
- | `--cafile=$cafile` | 覆盖默认 CA 链（用于下载 tarball） |
318
- | `--nodedir=$path` | 指定 Node 源码路径 |
319
- | `--python=$path` | 指定 Python 二进制路径 |
297
+ | 选项 | 说明 |
298
+ | --------------------------------- | -------------------------------------------------------------------------------------------- |
299
+ | `-v`, `--version` | 打印本包版本号 |
300
+ | `-j n`, `--jobs n` | 并行运行 `make`；`max` 表示使用所有 CPU 核心 |
301
+ | `--target=v6.2.1` | 目标 Node.js 版本（默认 `process.version`） |
302
+ | `--silly`, `--loglevel=silly` | 输出全部进度日志 |
303
+ | `--verbose`, `--loglevel=verbose` | 输出大部分进度日志 |
304
+ | `--silent`, `--loglevel=silent` | 不输出任何日志 |
305
+ | `debug`, `--debug` | 生成 Debug 构建（默认 Release） |
306
+ | `--release`, `--no-debug` | 生成 Release 构建 |
307
+ | `-C $dir`, `--directory=$dir` | 在指定目录运行命令 |
308
+ | `--make=$make` | 覆盖 `make` 命令（如 `gmake`） |
309
+ | `--thin=yes` | 启用 thin 静态库 |
310
+ | `--arch=$arch` | 目标架构（如 `ia32`） |
311
+ | `--tarball=$path` | 从本地 tarball 获取头文件 |
312
+ | `--devdir=$path` | SDK 下载目录（默认为系统缓存目录） |
313
+ | `--ensure` | 已存在的头文件不重装 |
314
+ | `--dist-url=$url` | 从自定义 URL 下载头文件 tarball |
315
+ | `--proxy=$url` | 下载时使用 HTTP(S) 代理 |
316
+ | `--noproxy=$urls` | 下载时忽略代理的 URL 列表 |
317
+ | `--cafile=$cafile` | 覆盖默认 CA 链（用于下载 tarball） |
318
+ | `--nodedir=$path` | 指定 Node 源码路径 |
319
+ | `--python=$path` | 指定 Python 二进制路径 |
320
320
  | `--msvs_version=$version` | 指定 Visual Studio 版本或安装路径（仅 Windows；可填 `2022` / `2026` 或 `C:\...\BuildTools`） |
321
- | `--solution=$solution` | 指定 Visual Studio Solution 版本（仅 Windows） |
322
- | `--force-process-config` | 强制用运行时的 `process.config` 生成 `config.gypi` |
321
+ | `--solution=$solution` | 指定 Visual Studio Solution 版本（仅 Windows） |
322
+ | `--force-process-config` | 强制用运行时的 `process.config` 生成 `config.gypi` |
323
323
 
324
324
  ## 配置
325
325
 
package/package.json CHANGED
@@ -11,7 +11,7 @@
11
11
  "bindings",
12
12
  "gyp"
13
13
  ],
14
- "version": "1.1.0",
14
+ "version": "1.1.1",
15
15
  "installVersion": 11,
16
16
  "author": "flun <open@flun.top>",
17
17
  "bin": {