@flun/nodejs-mobile-gyp 1.1.4 → 1.2.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.
- package/CHANGELOG.md +44 -8
- package/LICENSE +33 -33
- package/README.md +243 -248
- package/bin/node-gyp.js +27 -21
- package/lib/Find-VisualStudio.cs +2 -1
- package/lib/build.js +26 -36
- package/lib/clean.js +3 -3
- package/lib/configure.js +26 -26
- package/lib/create-config-gypi.js +4 -4
- package/lib/download.js +1 -1
- package/lib/find-node-directory.js +5 -5
- package/lib/find-python.js +44 -44
- package/lib/find-visualstudio.js +53 -53
- package/lib/install.js +42 -42
- package/lib/list.js +3 -3
- package/lib/node-gyp.js +31 -5
- package/lib/process-release.js +1 -1
- package/lib/rebuild.js +2 -2
- package/lib/remove.js +6 -6
- package/lib/util.js +72 -72
- package/package.json +9 -9
package/README.md
CHANGED
|
@@ -1,24 +1,58 @@
|
|
|
1
1
|
# @flun/nodejs-mobile-gyp
|
|
2
2
|
|
|
3
|
+
## 简介
|
|
4
|
+
|
|
3
5
|
移动端 Node.js 原生模块(Native Addon)的交叉编译工具;
|
|
4
6
|
|
|
5
7
|
用于为 nodejs-mobile 环境编译 C/C++ 原生模块,支持 Android 与 iOS 的交叉编译;
|
|
6
8
|
适用于官方 [nodejs-mobile](https://github.com/nodejs-mobile/nodejs-mobile) 及兼容的社区发行版
|
|
7
9
|
(如 [OpenFlun/nodejs-mobile](https://github.com/OpenFlun/nodejs-mobile));
|
|
8
10
|
|
|
9
|
-
宿主平台支持 **Windows** / **macOS** / **Linux**,各平台所需的环境与工具见
|
|
11
|
+
宿主平台支持 **Windows** / **macOS** / **Linux**,各平台所需的环境与工具见 [安装前准备](#安装前准备);
|
|
10
12
|
|
|
11
|
-
[`@flun/nodejs-mobile-react-native`](https://www.npmjs.com/package/@flun/nodejs-mobile-react-native)
|
|
13
|
+
[`@flun/nodejs-mobile-react-native`](https://www.npmjs.com/package/@flun/nodejs-mobile-react-native)
|
|
12
14
|
在构建时会自动调用本包,无需手动安装;
|
|
13
15
|
|
|
14
|
-
本包是 [`nodejs-mobile-gyp`](https://github.com/nodejs-mobile/nodejs-mobile-gyp) 的 flun fork,后者又基于上游
|
|
16
|
+
本包是 [`nodejs-mobile-gyp`](https://github.com/nodejs-mobile/nodejs-mobile-gyp) 的 flun fork,后者又基于上游
|
|
15
17
|
[`node-gyp`](https://github.com/nodejs/node-gyp);
|
|
16
18
|
|
|
17
19
|
- GitHub:https://github.com/OpenFlun/nodejs-mobile-gyp
|
|
18
20
|
- gitee: https://gitee.com/OpenFlun/nodejs-mobile-gyp
|
|
19
21
|
- npm:https://www.npmjs.com/package/@flun/nodejs-mobile-gyp
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
### 与原版的差异
|
|
24
|
+
|
|
25
|
+
#### 代码风格
|
|
26
|
+
|
|
27
|
+
| 项 | 原版 | 本 fork |
|
|
28
|
+
| -------- | ----------------------- | ------------------------------------------- |
|
|
29
|
+
| 模块系统 | CommonJS | **ESM**(`package.json` 的 `type: "module"`) |
|
|
30
|
+
| 导出方式 | 文件内 `module.exports` | **末尾统一 `export { ... }`** |
|
|
31
|
+
| 函数声明 | `async function xxx` | `const xxx = async () =>`(`class` 保留) |
|
|
32
|
+
| 注释 | 英文 | 中文 |
|
|
33
|
+
|
|
34
|
+
#### 依赖升级
|
|
35
|
+
|
|
36
|
+
| 包 | 原版 | 本 fork | 原因 |
|
|
37
|
+
| ------------------- | ---------- | --------- | ------------------------------------------- |
|
|
38
|
+
| `tar` | `^6.1.2` | `^7.5.22` | 上游 v6 停更,有安全公告 |
|
|
39
|
+
| `glob` | `^10.3.10` | `^13.0.6` | 上游 v10 停更 |
|
|
40
|
+
| `make-fetch-happen` | `^13.0.0` | `^16.0.1` | 连带升级 `cacache`,去掉 `tar@6` / `glob@10` |
|
|
41
|
+
|
|
42
|
+
升级后依赖树干净,`npm audit` 0 vulnerabilities;
|
|
43
|
+
|
|
44
|
+
## 特性
|
|
45
|
+
|
|
46
|
+
- 为 nodejs-mobile 环境交叉编译 C/C++ 原生模块
|
|
47
|
+
- 支持 Android 与 iOS 目标,宿主可为 Windows / macOS / Linux
|
|
48
|
+
- 自动探测 Windows 下的 Python、Visual Studio、Git for Windows(MSYS2 POSIX 工具集)
|
|
49
|
+
- 跨平台路径处理统一转正斜杠,兼容 Windows 下的 gyp 生成器
|
|
50
|
+
- 依赖链升级至较新版本(make-fetch-happen、nopt、proc-log、which 等)
|
|
51
|
+
- 由 `@flun/nodejs-mobile-react-native` 自动调用,通常无需手动安装
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 包目录结构
|
|
22
56
|
|
|
23
57
|
```txt
|
|
24
58
|
@flun/nodejs-mobile-gyp/
|
|
@@ -46,10 +80,6 @@
|
|
|
46
80
|
│ └── util.js # 通用工具:execFile 包装、注册表读取、候选文件查找
|
|
47
81
|
│
|
|
48
82
|
├── gyp/ # 内置的 gyp 工具(Python)
|
|
49
|
-
│ ├── gyp # Python 启动脚本(Unix)
|
|
50
|
-
│ ├── gyp.bat # Python 启动脚本(Windows)
|
|
51
|
-
│ ├── gyp_main.py # gyp 主入口
|
|
52
|
-
│ ├── LICENSE # gyp 自身的许可证
|
|
53
83
|
│ ├── pylib/gyp/ # gyp 核心 Python 模块
|
|
54
84
|
│ │ ├── input.py # 解析 .gyp / .gypi 文件
|
|
55
85
|
│ │ ├── common.py # 通用工具
|
|
@@ -60,155 +90,35 @@
|
|
|
60
90
|
│ │ ├── win_tool.py # Windows 工具链
|
|
61
91
|
│ │ └── generator/ # 各类生成器后端(make / msvs / ninja / xcode / cmake ...)
|
|
62
92
|
│ ├── pylib/packaging/ # gyp 依赖的 Python packaging 库(vendored)
|
|
63
|
-
│
|
|
64
|
-
│
|
|
93
|
+
│ ├── data/win/
|
|
94
|
+
│ │ └── large-pdb-shim.cc # Windows 大 PDB 兼容编译单元
|
|
95
|
+
│ ├── gyp # Python 启动脚本(Unix)
|
|
96
|
+
│ ├── gyp_main.py # gyp 主入口
|
|
97
|
+
│ ├── gyp.bat # Python 启动脚本(Windows)
|
|
98
|
+
│ ├── pyproject.toml # gyp 自身构建元数据(不随包发布)
|
|
99
|
+
│ ├── README.md # gyp 上游说明(不随包发布)
|
|
100
|
+
│ └── test_gyp.py # gyp 自测脚本(不随包发布)
|
|
65
101
|
│
|
|
66
102
|
├── src/
|
|
67
103
|
│ └── win_delay_load_hook.cc # Windows 加载延迟钩子(编译进每个原生模块)
|
|
68
104
|
│
|
|
69
105
|
├── addon.gypi # 所有原生模块共用的 gyp 配置
|
|
70
|
-
├── package.json # type: module,bin 命令名为 nodejs-mobile-gyp
|
|
71
|
-
├── LICENSE # 本包许可证(ISC)
|
|
72
|
-
├── README.md # 本文件
|
|
73
106
|
├── CHANGELOG.md # 版本变更记录
|
|
74
|
-
├── .
|
|
75
|
-
├──
|
|
76
|
-
├── .
|
|
77
|
-
└──
|
|
107
|
+
├── README.md # 本文件
|
|
108
|
+
├── LICENSE # 本包许可证(ISC)
|
|
109
|
+
├── macOS_Catalina_acid_test.sh # macOS Catalina 兼容性验证脚本(仅本地开发,不随包发布)
|
|
110
|
+
└── package.json # type: module,bin 命令名为 nodejs-mobile-gyp
|
|
78
111
|
```
|
|
79
112
|
|
|
80
|
-
##
|
|
81
|
-
|
|
82
|
-
本 fork 在功能上与原版 `nodejs-mobile-gyp` 一致,做了以下改造;
|
|
83
|
-
|
|
84
|
-
### 代码风格
|
|
85
|
-
|
|
86
|
-
| 项 | 原版 | 本 fork |
|
|
87
|
-
| -------- | ----------------------- | --------------------------------------------- |
|
|
88
|
-
| 模块系统 | CommonJS | **ESM**(`package.json` 的 `type: "module"`) |
|
|
89
|
-
| 导出方式 | 文件内 `module.exports` | **末尾统一 `export { ... }`** |
|
|
90
|
-
| 函数声明 | `async function xxx` | `const xxx = async () =>`(`class` 保留) |
|
|
91
|
-
| 注释 | 英文 | 中文 |
|
|
92
|
-
|
|
93
|
-
### 依赖升级
|
|
94
|
-
|
|
95
|
-
| 包 | 原版 | 本 fork | 原因 |
|
|
96
|
-
| ------------------- | ---------- | --------- | -------------------------------------------- |
|
|
97
|
-
| `tar` | `^6.1.2` | `^7.5.22` | 上游 v6 停更,有安全公告 |
|
|
98
|
-
| `glob` | `^10.3.10` | `^13.0.6` | 上游 v10 停更 |
|
|
99
|
-
| `make-fetch-happen` | `^13.0.0` | `^16.0.1` | 连带升级 `cacache`,去掉 `tar@6` / `glob@10` |
|
|
100
|
-
|
|
101
|
-
升级后依赖树干净,`npm audit` 0 vulnerabilities;
|
|
102
|
-
|
|
103
|
-
### Windows 构建适配
|
|
104
|
-
|
|
105
|
-
原版 `nodejs-mobile-gyp` 在 Windows 上有若干问题,本 fork 逐一解决,涉及三方面;
|
|
106
|
-
|
|
107
|
-
#### 1. 工具集与 LTO
|
|
108
|
-
|
|
109
|
-
原版默认走 ClangCL 工具集,且继承 Node 官方二进制的 LTO 配置;Node.js 24+ 官方二进制由 ClangCL + ThinLTO 编译,其
|
|
110
|
-
`common.gypi` 会在 `clang==1` 时把 MSBuild 工具集设为 `ClangCL`,并在 `enable_lto==true` / `enable_thin_lto==true`
|
|
111
|
-
时向链接器传入 `-flto=thin`、`/opt:lldltojobs` 等 Clang 专用参数;若用户本机没装 ClangCL,或用的是传统 MSVC 工具链,会报:
|
|
112
|
-
|
|
113
|
-
- `MSB8020: 无法找到 ClangCL 的生成工具`
|
|
114
|
-
- `LNK1117: 选项"opt:lldltojobs=2"中的语法错误`
|
|
115
|
-
|
|
116
|
-
本 fork 强制走 MSVC 工具集并关闭 LTO,避免上述报错;工具集版本从 `find-visualstudio` 的探测结果**动态获取**(`v140` / `v141`
|
|
117
|
-
/ `v142` / `v143` / `v145`...),不写死;
|
|
118
|
-
|
|
119
|
-
#### 2. GNU make 的 POSIX 环境
|
|
120
|
-
|
|
121
|
-
Android 原生模块通过 GNU make 构建,其 Makefile 会调用 `printf`、`xargs`、`sed` 等 Unix 命令;GNU make 需要一个 POSIX
|
|
122
|
-
shell(`sh.exe`)来执行它们;Windows 上若无,会直接报 `CreateProcess(NULL, printf ...) failed`;Git for Windows 自带整套 POSIX
|
|
123
|
-
工具集;本 fork 会自动定位其 `usr/bin` 并前置到 PATH,详见"[支持的系统与配置要求](#支持的系统与配置要求) → 自动探测";
|
|
124
|
-
|
|
125
|
-
#### 3. 路径分隔符
|
|
126
|
-
|
|
127
|
-
gyp 生成的 Makefile 中,路径原本会带上 Windows 的反斜杠(如 `src\bufferutil.o`),导致 `sh` / `sed` / `make` 解析失败;本 fork
|
|
128
|
-
在 gyp 的路径生成环节统一转成正斜杠;该改动在非 Windows 平台上是 no-op;
|
|
129
|
-
|
|
130
|
-
### 具体改动清单
|
|
131
|
-
|
|
132
|
-
#### 构建工具链
|
|
133
|
-
|
|
134
|
-
- `lib/create-config-gypi.js`
|
|
135
|
-
- 改动:生成 `config.gypi` 时把 `clang` 置 0、`enable_lto` / `enable_thin_lto` 置 `'false'`、
|
|
136
|
-
`lto_jobs` 置空,避免 `common.gypi` 切到 ClangCL 并向 MSVC 传 LTO 参数
|
|
137
|
-
- `lib/configure.js`
|
|
138
|
-
- 改动:调用 gyp 时追加 `-Gmsvs_toolset=<探测到的 toolset>`,不再写死 `v145`
|
|
139
|
-
- `lib/find-visualstudio.js`
|
|
140
|
-
- 改动:支持 VS2013+,含最新 VS2026(版本号 18,`versionYear=2026`,toolset `v145`)
|
|
141
|
-
- `gyp/pylib/gyp/MSVSSettings.py`
|
|
142
|
-
- 改动:注册 `ExternalWarningLevel`(MSBuild 属性),供 `addon.gypi` 使用
|
|
143
|
-
- `addon.gypi`
|
|
144
|
-
- 改动:Windows 下追加 `/external:anglebrackets` +
|
|
145
|
-
`ExternalWarningLevel: TurnOffAllWarnings`,只静音外部头(Node / V8)的警告
|
|
146
|
-
|
|
147
|
-
#### 跨平台路径
|
|
148
|
-
|
|
149
|
-
| 文件 | 改动
|
|
150
|
-
|
|
|
151
|
-
| --------------------------------- |
|
|
152
|
-
----------------------------------------------------------------------------------------------------------- |
|
|
153
|
-
| `gyp/pylib/gyp/common.py` | `RelativePath` 返回值统一转正斜杠
|
|
154
|
-
|
|
|
155
|
-
| `gyp/pylib/gyp/generator/make.py` | `Absolutify` 返回正斜杠;新增 `slashpath` 供 `mkdir` 使用;Windows 下跳过
|
|
156
|
-
`node_modules` 中的超长 gypi 依赖 |
|
|
157
|
-
|
|
158
|
-
#### Windows 运行时探测
|
|
159
|
-
|
|
160
|
-
| 文件 | 改动
|
|
161
|
-
|
|
|
162
|
-
| -------------------- |
|
|
163
|
-
-------------------------------------------------------------------------------------------------------------- |
|
|
164
|
-
| `lib/find-python.js` | 重写:移除硬编码版本列表,改为 `py.exe` 候选 + `py -0p` 枚举 + 目录扫描;`run()` 显式检查 `execFile`
|
|
165
|
-
的 err |
|
|
166
|
-
| `lib/build.js` | 区分"宿主 Windows"与"Android 交叉编译";自动探测 `sh.exe` 并前置到 PATH;为 Python 创建
|
|
167
|
-
`python3.cmd` shim |
|
|
168
|
-
|
|
169
|
-
#### 兼容性与健壮性
|
|
170
|
-
|
|
171
|
-
- **`proc-log` 新版本兼容**:新版把日志级别函数与 `pause` / `resume` 挂在默认导出的 `log` 对象下;本 fork 已按此调整
|
|
172
|
-
`lib/log.js`,否则 `configure` 阶段会抛 `TypeError`;
|
|
173
|
-
- **弃用 API 清理**:`lib/process-release.js` 不再用 `url.resolve()` / `url.parse()`,改用 WHATWG `URL`,消除 `DEP0169` 警告;
|
|
174
|
-
- **依赖脚本放行**:`package.json` 显式声明 `allowScripts`,适配新版 npm 默认禁止依赖执行安装脚本的行为;
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
### 迁移踩过的坑
|
|
178
|
-
|
|
179
|
-
1. **`graceful-fs` 是 CJS,命名导入会失败**
|
|
180
|
-
写成 `import gracefulFs from 'graceful-fs'`,再从 default 解构 `const { openSync, closeSync } = gracefulFs`;
|
|
181
|
-
|
|
182
|
-
2. **`tar@7` 没有 default export**
|
|
183
|
-
写成 `import * as tar from 'tar'`;
|
|
184
|
-
|
|
185
|
-
3. **`proc-log` 的解构**
|
|
186
|
-
`import procLog from 'proc-log'`,再把需要的函数从 default 里解构后统一导出;
|
|
187
|
-
|
|
188
|
-
4. **PowerShell 写文件会加 BOM**
|
|
189
|
-
`Set-Content -Encoding UTF8` 会写入 `\uFEFF`,导致 gyp 的 `eval()` 报
|
|
190
|
-
`SyntaxError: invalid non-printable character U+FEFF`;写 `binding.gyp` 等交给 Python eval 的文件时,用
|
|
191
|
-
`[System.IO.File]::WriteAllText` + `New-Object System.Text.UTF8Encoding $false`;
|
|
192
|
-
|
|
193
|
-
5. **ESM 不支持动态 `require('./' + command)`**
|
|
194
|
-
`lib/node-gyp.js` 原本用 `require('./' + command)` 动态加载命令模块,ESM 下改为在顶部静态 import 所有命令,
|
|
195
|
-
再用静态映射表组装 `this.commands`;
|
|
196
|
-
|
|
197
|
-
6. **`__dirname` / `__filename` 在 ESM 中不存在**
|
|
198
|
-
用 `fileURLToPath(import.meta.url)` 重建;
|
|
199
|
-
|
|
200
|
-
7. **非 Windows 平台不引入 `find-visualstudio.js`**
|
|
201
|
-
该模块依赖 Windows 专属的 `path.win32` 和注册表操作,保持原版的"仅在 Windows 上条件加载"逻辑;
|
|
202
|
-
|
|
203
|
-
## 支持的系统与配置要求
|
|
113
|
+
## 安装前准备
|
|
204
114
|
|
|
205
115
|
本包面向 **Android / iOS 交叉编译**,宿主平台支持情况:
|
|
206
116
|
|
|
207
|
-
| 宿主平台 | 目标:Android | 目标:iOS
|
|
208
|
-
| -------- |
|
|
209
|
-
| Windows |
|
|
210
|
-
| macOS |
|
|
211
|
-
| Linux |
|
|
117
|
+
| 宿主平台 | 目标:Android | 目标:iOS |
|
|
118
|
+
| -------- | ------------ | -------- |
|
|
119
|
+
| Windows | 完整支持 | 需 macOS |
|
|
120
|
+
| macOS | 完整支持 | 完整支持 |
|
|
121
|
+
| Linux | 完整支持 | 需 macOS |
|
|
212
122
|
|
|
213
123
|
各平台所需的构建环境如下;
|
|
214
124
|
|
|
@@ -222,39 +132,37 @@ gyp 生成的 Makefile 中,路径原本会带上 Windows 的反斜杠(如 `src\b
|
|
|
222
132
|
|
|
223
133
|
### Windows
|
|
224
134
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
命令;这些命令并非 Windows 自带,GNU make 需要一个 POSIX 环境来执行它们;Git for Windows
|
|
238
|
-
自带**整套 MSYS2 POSIX 工具集**(`sh.exe`、`printf`、`xargs`、`sed`、`rm`、`mkdir` 等数十个命令),无需额外安装 MSYS2 或
|
|
135
|
+
- `Node.js`:见 `engines.node`
|
|
136
|
+
- `Python`:3.6+,支持任意安装位置,见下方"自动探测"
|
|
137
|
+
- `Visual Studio`:**VS2019 / VS2022 / VS2026**(2026 已验证);需勾选"使用 C++ 的桌面开发"工作负载,
|
|
138
|
+
含 Windows SDK;VS2017 及更早受 Node 版本上限限制
|
|
139
|
+
- `Android NDK`:**23–27**(已验证);由 `@flun/nodejs-mobile-react-native` 自动定位
|
|
140
|
+
- `Git for Windows`:任意近期版本;自带**整套 MSYS2 POSIX 工具集**
|
|
141
|
+
(`sh.exe`、`printf`、`xargs`、`sed`、`rm`、`mkdir` 等数十个命令),
|
|
142
|
+
GNU make 执行 Makefile 所依赖的 Unix 命令均由它提供;位置自动探测(见下方)
|
|
143
|
+
|
|
144
|
+
> **为什么需要 Git for Windows?** Android 原生模块通过 GNU make 构建,Makefile 中会调用 `printf`、`xargs`、`sed` 等 Unix
|
|
145
|
+
命令;这些命令并非 Windows 自带,GNU make 需要一个 POSIX 环境来执行它们;Git for Windows
|
|
146
|
+
自带**整套 MSYS2 POSIX 工具集**(`sh.exe`、`printf`、`xargs`、`sed`、`rm`、`mkdir` 等数十个命令),无需额外安装 MSYS2 或
|
|
239
147
|
Cygwin;
|
|
240
148
|
|
|
241
149
|
### macOS
|
|
242
150
|
|
|
243
|
-
| 组件 | 要求
|
|
244
|
-
| ----------- |
|
|
245
|
-
| Node.js | 见 `engines.node`
|
|
246
|
-
| Python | 3.6+
|
|
151
|
+
| 组件 | 要求 |
|
|
152
|
+
| ----------- | ----------------------------- |
|
|
153
|
+
| Node.js | 见 `engines.node` |
|
|
154
|
+
| Python | 3.6+ |
|
|
247
155
|
| Xcode | 完整 Xcode(必须,CLT 单独不够) |
|
|
248
|
-
| Android NDK | 仅构建 Android 目标时需 23–27
|
|
156
|
+
| Android NDK | 仅构建 Android 目标时需 23–27 |
|
|
249
157
|
|
|
250
158
|
### Linux
|
|
251
159
|
|
|
252
|
-
| 组件 | 要求
|
|
253
|
-
| ----------- |
|
|
254
|
-
| Node.js | 见 `engines.node`
|
|
255
|
-
| Python | 3.6+
|
|
160
|
+
| 组件 | 要求 |
|
|
161
|
+
| ----------- | ---------------------------------------------------- |
|
|
162
|
+
| Node.js | 见 `engines.node` |
|
|
163
|
+
| Python | 3.6+ |
|
|
256
164
|
| 构建工具 | `make`、`g++`(`apt install build-essential python3`) |
|
|
257
|
-
| Android NDK | 仅构建 Android 目标时需 23–27
|
|
165
|
+
| Android NDK | 仅构建 Android 目标时需 23–27 |
|
|
258
166
|
|
|
259
167
|
### 自动探测(Windows)
|
|
260
168
|
|
|
@@ -275,10 +183,10 @@ gyp 生成的 Makefile 中,路径原本会带上 Windows 的反斜杠(如 `src\b
|
|
|
275
183
|
3. `PATH` 中的 `git.exe` 反推 `../usr/bin`
|
|
276
184
|
4. 常见安装位置兜底
|
|
277
185
|
|
|
278
|
-
- **Android NDK**:由 `@flun/nodejs-mobile-react-native` 通过 `android.ndkDirectory` 定位,并注入 `make.exe`、`clang`
|
|
186
|
+
- **Android NDK**:由 `@flun/nodejs-mobile-react-native` 通过 `android.ndkDirectory` 定位,并注入 `make.exe`、`clang`
|
|
279
187
|
等工具路径;
|
|
280
188
|
|
|
281
|
-
> 本包不依赖任何随包分发的硬编码配置文件;上述探测均为运行时动态完成;仅 Visual Studio 的"版本号 → 版本年份 →
|
|
189
|
+
> 本包不依赖任何随包分发的硬编码配置文件;上述探测均为运行时动态完成;仅 Visual Studio 的"版本号 → 版本年份 →
|
|
282
190
|
toolset"对照表以常量形式内联在 `lib/find-visualstudio.js` 中--这类信息由微软固定发布,无枚举接口,且随 VS 版本发布而更新,
|
|
283
191
|
不适合做成外部资源;
|
|
284
192
|
|
|
@@ -289,16 +197,28 @@ gyp 生成的 Makefile 中,路径原本会带上 Windows 的反斜杠(如 `src\b
|
|
|
289
197
|
npm i @flun/nodejs-mobile-gyp
|
|
290
198
|
```
|
|
291
199
|
|
|
292
|
-
通常你不需要手动安装本包--它由 [`@flun/nodejs-mobile-react-native`]
|
|
293
|
-
|
|
200
|
+
通常你不需要手动安装本包--它由 [`@flun/nodejs-mobile-react-native`][rn-pkg] 在编译原生模块时自动调用;
|
|
201
|
+
|
|
202
|
+
[rn-pkg]: https://www.npmjs.com/package/@flun/nodejs-mobile-react-native
|
|
294
203
|
|
|
295
|
-
> **Node 版本要求**:本 fork 的依赖链(`make-fetch-happen`、`nopt`、`proc-log`、`which` 等)已升级到较新版本,要求比原版
|
|
204
|
+
> **Node 版本要求**:本 fork 的依赖链(`make-fetch-happen`、`nopt`、`proc-log`、`which` 等)已升级到较新版本,要求比原版
|
|
296
205
|
`nodejs-mobile-gyp` 更高的 Node;具体最低版本见 `package.json` 的 `engines.node` 字段;若你的项目仍在使用较旧的 Node,
|
|
297
206
|
请改用原版 `nodejs-mobile-gyp`;
|
|
298
207
|
|
|
299
|
-
##
|
|
208
|
+
## 命令行
|
|
209
|
+
|
|
210
|
+
### 快速开始
|
|
300
211
|
|
|
301
|
-
|
|
212
|
+
在需要编译原生模块的项目目录下执行:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
npx @flun/nodejs-mobile-gyp rebuild --target=v18.20.4 --arch=arm64
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
`rebuild` 依次执行 `clean` → `configure` → `build`;`--target` 指定目标 Node.js 版本,
|
|
219
|
+
`--arch` 指定目标架构;Android 与 iOS 的构建环境要求见 [安装前准备](#安装前准备);
|
|
220
|
+
|
|
221
|
+
### 调用方式
|
|
302
222
|
|
|
303
223
|
```bash
|
|
304
224
|
npx @flun/nodejs-mobile-gyp <command> [options]
|
|
@@ -314,84 +234,60 @@ npx @flun/nodejs-mobile-gyp <command> [options]
|
|
|
314
234
|
}
|
|
315
235
|
```
|
|
316
236
|
|
|
317
|
-
###
|
|
318
|
-
|
|
319
|
-
本包主要作为 CLI 工具使用,推荐通过 spawn / execFile 调用其命令行入口;包本身也导出了 Gyp 类,但属于内部实现,
|
|
320
|
-
接口可能随版本变化,不建议直接在代码中依赖;
|
|
321
|
-
|
|
322
|
-
## 命令
|
|
237
|
+
### 命令
|
|
323
238
|
|
|
324
239
|
| 命令 | 说明 |
|
|
325
240
|
| ----------- | ---------------------------------------- |
|
|
326
241
|
| `help` | 显示帮助 |
|
|
327
242
|
| `build` | 调用 `make` / `msbuild.exe` 编译原生模块 |
|
|
328
|
-
| `clean` | 删除 `build` 目录(若存在)
|
|
243
|
+
| `clean` | 删除 `build` 目录(若存在) |
|
|
329
244
|
| `configure` | 为当前平台生成工程构建文件 |
|
|
330
245
|
| `rebuild` | 依次执行 `clean` → `configure` → `build` |
|
|
331
246
|
| `install` | 为指定版本安装 Node.js 头文件 |
|
|
332
247
|
| `list` | 列出已安装的 Node.js 头文件版本 |
|
|
333
248
|
| `remove` | 删除指定版本的 Node.js 头文件 |
|
|
334
249
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
| `--dist-url=$url` | 从自定义 URL 下载头文件 tarball
|
|
372
|
-
|
|
|
373
|
-
| `--proxy=$url` | 下载时使用 HTTP(S) 代理
|
|
374
|
-
|
|
|
375
|
-
| `--noproxy=$urls` | 下载时忽略代理的 URL 列表
|
|
376
|
-
|
|
|
377
|
-
| `--cafile=$cafile` | 覆盖默认 CA 链(用于下载 tarball)
|
|
378
|
-
|
|
|
379
|
-
| `--nodedir=$path` | 指定 Node 源码路径
|
|
380
|
-
|
|
|
381
|
-
| `--python=$path` | 指定 Python 二进制路径
|
|
382
|
-
|
|
|
383
|
-
| `--msvs_version=$version` | 指定 Visual Studio 版本或安装路径(仅 Windows;可填 `2022` / `2026` 或
|
|
384
|
-
`C:\...\BuildTools`) |
|
|
385
|
-
| `--solution=$solution` | 指定 Visual Studio Solution 版本(仅 Windows)
|
|
386
|
-
|
|
|
387
|
-
| `--force-process-config` | 强制用运行时的 `process.config` 生成 `config.gypi`
|
|
388
|
-
|
|
|
389
|
-
|
|
390
|
-
## 配置
|
|
250
|
+
### 参数
|
|
251
|
+
|
|
252
|
+
- `-v`, `--version`:打印本包版本号
|
|
253
|
+
- `-j n`, `--jobs n`:并行运行 `make`;`max` 表示使用所有 CPU 核心
|
|
254
|
+
- `--target=v6.2.1`:目标 Node.js 版本(默认 `process.version`)
|
|
255
|
+
- `--silly`, `--loglevel=silly`:输出全部进度日志
|
|
256
|
+
- `--verbose`, `--loglevel=verbose`:输出大部分进度日志
|
|
257
|
+
- `--silent`, `--loglevel=silent`:不输出任何日志
|
|
258
|
+
- `debug`, `--debug`:生成 Debug 构建(默认 Release)
|
|
259
|
+
- `--release`, `--no-debug`:生成 Release 构建
|
|
260
|
+
- `-C $dir`, `--directory=$dir`:在指定目录运行命令
|
|
261
|
+
- `--make=$make`:覆盖 `make` 命令(如 `gmake`)
|
|
262
|
+
- `--thin=yes`:启用 thin 静态库
|
|
263
|
+
- `--arch=$arch`:目标架构(如 `ia32`)
|
|
264
|
+
- `--tarball=$path`:从本地 tarball 获取头文件
|
|
265
|
+
- `--devdir=$path`:SDK 下载目录(默认为系统缓存目录)
|
|
266
|
+
- `--ensure`:已存在的头文件不重装
|
|
267
|
+
- `--dist-url=$url`:从自定义 URL 下载头文件 tarball
|
|
268
|
+
- `--proxy=$url`:下载时使用 HTTP(S) 代理
|
|
269
|
+
- `--noproxy=$urls`:下载时忽略代理的 URL 列表
|
|
270
|
+
- `--cafile=$cafile`:覆盖默认 CA 链(用于下载 tarball)
|
|
271
|
+
- `--nodedir=$path`:指定 Node 源码路径
|
|
272
|
+
- `--python=$path`:指定 Python 二进制路径
|
|
273
|
+
- `--msvs-version=$version`:指定 Visual Studio 版本或安装路径(仅 Windows;可填 `2022` / `2026` 或 `C:\...\BuildTools`)
|
|
274
|
+
- `--solution=$solution`:指定 Visual Studio Solution 版本(仅 Windows)
|
|
275
|
+
- `--force-process-config`:强制用运行时的 `process.config` 生成 `config.gypi`
|
|
276
|
+
|
|
277
|
+
## 函数方式
|
|
278
|
+
|
|
279
|
+
本包主要作为 CLI 工具使用,推荐通过 spawn / execFile 调用其命令行入口;
|
|
280
|
+
包本身也导出了 Gyp 类,但属于内部实现,接口可能随版本变化,不建议直接在代码中依赖;
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
|
|
285
|
+
## 参考配置
|
|
391
286
|
|
|
392
287
|
### 环境变量
|
|
393
288
|
|
|
394
|
-
|
|
289
|
+
上表中的命令选项(除 `-v`/`--version` 外),都可以用 `npm_config_OPTION_NAME` 形式的**环境变量**来设置;
|
|
290
|
+
选项名中的 `-` 替换为 `_`;
|
|
395
291
|
|
|
396
292
|
例如,把 `devdir` 设为 `/tmp/.gyp`:
|
|
397
293
|
|
|
@@ -415,14 +311,113 @@ npm config set [--global] devdir /tmp/.gyp
|
|
|
415
311
|
|
|
416
312
|
**注意**:通过 `npm config` 设置的配置,只在本包 **由 npm 调用时**生效,直接运行 `nodejs-mobile-gyp` 不生效;
|
|
417
313
|
|
|
418
|
-
##
|
|
314
|
+
## 开发者参考
|
|
419
315
|
|
|
420
|
-
|
|
316
|
+
### Windows 构建适配
|
|
421
317
|
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
318
|
+
原版 `nodejs-mobile-gyp` 在 Windows 上有若干问题,本 fork 逐一解决,涉及三方面;
|
|
319
|
+
|
|
320
|
+
#### 1. 工具集与 LTO
|
|
321
|
+
|
|
322
|
+
原版默认走 ClangCL 工具集,且继承 Node 官方二进制的 LTO 配置;Node.js 24+ 官方二进制由 ClangCL + ThinLTO 编译,其
|
|
323
|
+
`common.gypi` 会在 `clang==1` 时把 MSBuild 工具集设为 `ClangCL`,并在 `enable_lto==true` / `enable_thin_lto==true`
|
|
324
|
+
时向链接器传入 `-flto=thin`、`/opt:lldltojobs` 等 Clang 专用参数;若用户本机没装 ClangCL,或用的是传统 MSVC 工具链,会报:
|
|
425
325
|
|
|
426
|
-
|
|
326
|
+
- `MSB8020: 无法找到 ClangCL 的生成工具`
|
|
327
|
+
- `LNK1117: 选项"opt:lldltojobs=2"中的语法错误`
|
|
328
|
+
|
|
329
|
+
本 fork 强制走 MSVC 工具集并关闭 LTO,避免上述报错;工具集版本从 `find-visualstudio` 的探测结果**动态获取**(`v140` / `v141`
|
|
330
|
+
/ `v142` / `v143` / `v145`...),不写死;
|
|
427
331
|
|
|
428
|
-
|
|
332
|
+
#### 2. GNU make 的 POSIX 环境
|
|
333
|
+
|
|
334
|
+
Android 原生模块通过 GNU make 构建,其 Makefile 会调用 `printf`、`xargs`、`sed` 等 Unix 命令;GNU make 需要一个 POSIX
|
|
335
|
+
shell(`sh.exe`)来执行它们;Windows 上若无,会直接报 `CreateProcess(NULL, printf ...) failed`;Git for Windows 自带整套 POSIX
|
|
336
|
+
工具集;本 fork 会自动定位其 `usr/bin` 并前置到 PATH,详见 [安装前准备](#安装前准备) 的"自动探测(Windows)";
|
|
337
|
+
|
|
338
|
+
#### 3. 路径分隔符
|
|
339
|
+
|
|
340
|
+
gyp 生成的 Makefile 中,路径原本会带上 Windows 的反斜杠(如 `src\bufferutil.o`),导致 `sh` / `sed` / `make` 解析失败;本 fork
|
|
341
|
+
在 gyp 的路径生成环节统一转成正斜杠;该改动在非 Windows 平台上是 no-op;
|
|
342
|
+
|
|
343
|
+
### 具体改动清单
|
|
344
|
+
|
|
345
|
+
#### 构建工具链
|
|
346
|
+
|
|
347
|
+
- `lib/create-config-gypi.js`
|
|
348
|
+
- 改动:生成 `config.gypi` 时把 `clang` 置 0、`enable_lto` / `enable_thin_lto` 置 `'false'`、
|
|
349
|
+
`lto_jobs` 置空,避免 `common.gypi` 切到 ClangCL 并向 MSVC 传 LTO 参数
|
|
350
|
+
- `lib/configure.js`
|
|
351
|
+
- 改动:调用 gyp 时追加 `-Gmsvs_toolset=<探测到的 toolset>`,不再写死 `v145`
|
|
352
|
+
- `lib/find-visualstudio.js`
|
|
353
|
+
- 改动:支持 VS2013+,含最新 VS2026(版本号 18,`versionYear=2026`,toolset `v145`)
|
|
354
|
+
- `gyp/pylib/gyp/MSVSSettings.py`
|
|
355
|
+
- 改动:注册 `ExternalWarningLevel`(MSBuild 属性),供 `addon.gypi` 使用
|
|
356
|
+
- `addon.gypi`
|
|
357
|
+
- 改动:Windows 下追加 `/external:anglebrackets` +
|
|
358
|
+
`ExternalWarningLevel: TurnOffAllWarnings`,只静音外部头(Node / V8)的警告
|
|
359
|
+
|
|
360
|
+
#### 跨平台路径
|
|
361
|
+
|
|
362
|
+
- `gyp/pylib/gyp/common.py`:`RelativePath` 返回值统一转正斜杠
|
|
363
|
+
- `gyp/pylib/gyp/generator/make.py`:`Absolutify` 返回正斜杠;新增 `slashpath` 供 `mkdir` 使用;
|
|
364
|
+
Windows 下跳过 `node_modules` 中的超长 gypi 依赖
|
|
365
|
+
|
|
366
|
+
#### Windows 运行时探测
|
|
367
|
+
|
|
368
|
+
- `lib/find-python.js`:重写:移除硬编码版本列表,改为 `py.exe` 候选 + `py -0p` 枚举 + 目录扫描;
|
|
369
|
+
`run()` 显式检查 `execFile` 的 err
|
|
370
|
+
- `lib/build.js`:区分"宿主 Windows"与"Android 交叉编译";自动探测 `sh.exe` 并前置到 PATH;
|
|
371
|
+
为 Python 创建 `python3.cmd` shim
|
|
372
|
+
|
|
373
|
+
#### 兼容性与健壮性
|
|
374
|
+
|
|
375
|
+
- **`proc-log` 新版本兼容**:新版把日志级别函数与 `pause` / `resume` 挂在默认导出的 `log` 对象下;本 fork 已按此调整
|
|
376
|
+
`lib/log.js`,否则 `configure` 阶段会抛 `TypeError`;
|
|
377
|
+
- **弃用 API 清理**:`lib/process-release.js` 不再用 `url.resolve()` / `url.parse()`,改用 WHATWG `URL`,消除 `DEP0169` 警告;
|
|
378
|
+
- **依赖脚本放行**:`package.json` 显式声明 `allowScripts`,适配新版 npm 默认禁止依赖执行安装脚本的行为;
|
|
379
|
+
|
|
380
|
+
## 常见问题
|
|
381
|
+
|
|
382
|
+
1. **`graceful-fs` 是 CJS,命名导入会失败**
|
|
383
|
+
写成 `import gracefulFs from 'graceful-fs'`,再从 default 解构 `const { openSync, closeSync } = gracefulFs`;
|
|
384
|
+
|
|
385
|
+
2. **`tar@7` 没有 default export**
|
|
386
|
+
写成 `import * as tar from 'tar'`;
|
|
387
|
+
|
|
388
|
+
3. **`proc-log` 的解构**
|
|
389
|
+
`import procLog from 'proc-log'`,再把需要的函数从 default 里解构后统一导出;
|
|
390
|
+
|
|
391
|
+
4. **PowerShell 写文件会加 BOM**
|
|
392
|
+
`Set-Content -Encoding UTF8` 会写入 `\uFEFF`,导致 gyp 的 `eval()` 报
|
|
393
|
+
`SyntaxError: invalid non-printable character U+FEFF`;写 `binding.gyp` 等交给 Python eval 的文件时,用
|
|
394
|
+
`[System.IO.File]::WriteAllText` + `New-Object System.Text.UTF8Encoding $false`;
|
|
395
|
+
|
|
396
|
+
5. **ESM 不支持动态 `require('./' + command)`**
|
|
397
|
+
`lib/node-gyp.js` 原本用 `require('./' + command)` 动态加载命令模块,ESM 下改为在顶部静态 import 所有命令,
|
|
398
|
+
再用静态映射表组装 `this.commands`;
|
|
399
|
+
|
|
400
|
+
6. **`__dirname` / `__filename` 在 ESM 中不存在**
|
|
401
|
+
用 `fileURLToPath(import.meta.url)` 重建;
|
|
402
|
+
|
|
403
|
+
7. **非 Windows 平台不引入 `find-visualstudio.js`**
|
|
404
|
+
该模块依赖 Windows 专属的 `path.win32` 和注册表操作,保持原版的"仅在 Windows 上条件加载"逻辑;
|
|
405
|
+
|
|
406
|
+
## 许可证
|
|
407
|
+
|
|
408
|
+
ISC
|
|
409
|
+
|
|
410
|
+
---
|
|
411
|
+
|
|
412
|
+
## 贡献
|
|
413
|
+
|
|
414
|
+
- 源码:[GitHub](https://github.com/OpenFlun/nodejs-mobile-gyp)
|
|
415
|
+
- 中国镜像:[gitee](https://gitee.com/OpenFlun/nodejs-mobile-gyp)
|
|
416
|
+
- 问题反馈:[Issues](https://github.com/OpenFlun/nodejs-mobile-gyp/issues)
|
|
417
|
+
- 上游:`nodejs-mobile-gyp` 与 `node-gyp`
|
|
418
|
+
|
|
419
|
+
上游文档:
|
|
420
|
+
|
|
421
|
+
- [nodejs/node-gyp README](https://github.com/nodejs/node-gyp#readme)
|
|
422
|
+
- [gyp 用户文档](https://gyp.gsrc.io/docs/UserDocumentation.md)
|
|
423
|
+
- [gyp 输入格式参考](https://gyp.gsrc.io/docs/InputFormatReference.md)
|