@flun/node-mobile-app 3.1.4 → 4.0.0
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 +46 -15
- package/README.md +559 -545
- package/bin/cli.js +3 -2
- package/package.json +4 -3
- package/src/commands/build.js +115 -114
- package/src/commands/clean.js +4 -3
- package/src/commands/test.js +160 -109
- package/src/config.js +6 -5
- package/src/copy.js +320 -319
- package/src/fingerprint.js +123 -122
- package/src/generate.js +105 -104
- package/src/install.js +317 -215
- package/src/optimize-node-modules.js +57 -54
- package/src/patcher.js +389 -388
- package/src/platform-ios.js +6 -5
- package/src/utils.js +92 -5
package/README.md
CHANGED
|
@@ -1,545 +1,559 @@
|
|
|
1
|
-
# @flun/node-mobile-app
|
|
2
|
-
|
|
3
|
-
将 Node.js 项目一键打包为 Android / iOS 移动应用;运行时由 @flun/nodejs-mobile-react-native 提供,无需修改你的 Node 代码;
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
- GitHub
|
|
8
|
-
- Gitee
|
|
9
|
-
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
## 特性
|
|
13
|
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
- **node_modules
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
│
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
│
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
│
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
│
|
|
53
|
-
|
|
54
|
-
│ ├──
|
|
55
|
-
│ ├──
|
|
56
|
-
│ ├──
|
|
57
|
-
│ ├──
|
|
58
|
-
│ ├──
|
|
59
|
-
│ ├──
|
|
60
|
-
│ ├──
|
|
61
|
-
│
|
|
62
|
-
│
|
|
63
|
-
│
|
|
64
|
-
│
|
|
65
|
-
│
|
|
66
|
-
|
|
67
|
-
│
|
|
68
|
-
|
|
69
|
-
│ ├──
|
|
70
|
-
│ ├──
|
|
71
|
-
│ ├──
|
|
72
|
-
│ ├──
|
|
73
|
-
│ ├──
|
|
74
|
-
│ ├──
|
|
75
|
-
│ ├──
|
|
76
|
-
│ ├──
|
|
77
|
-
│ ├── .
|
|
78
|
-
│ ├──
|
|
79
|
-
│
|
|
80
|
-
│
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
├──
|
|
84
|
-
├──
|
|
85
|
-
├──
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
- `template
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
"
|
|
104
|
-
"
|
|
105
|
-
"
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
#
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
#
|
|
153
|
-
npx node-mobile-app
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
|
164
|
-
|
|
|
165
|
-
| `npx node-mobile-app
|
|
166
|
-
| `npx node-mobile-app
|
|
167
|
-
| `npx node-mobile-app
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
|
175
|
-
|
|
|
176
|
-
| `--
|
|
177
|
-
| `--
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
```
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
|
241
|
-
|
|
|
242
|
-
| `
|
|
243
|
-
| `
|
|
244
|
-
| `
|
|
245
|
-
| `
|
|
246
|
-
| `
|
|
247
|
-
|
|
248
|
-
###
|
|
249
|
-
|
|
250
|
-
| 字段
|
|
251
|
-
|
|
|
252
|
-
| `
|
|
253
|
-
| `
|
|
254
|
-
| `
|
|
255
|
-
| `
|
|
256
|
-
| `
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
259
|
-
| `
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
|
264
|
-
|
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
-
|
|
292
|
-
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
|
324
|
-
|
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
|
329
|
-
|
|
|
330
|
-
| `
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
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
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
- `
|
|
376
|
-
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
-
|
|
506
|
-
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
1
|
+
# @flun/node-mobile-app
|
|
2
|
+
|
|
3
|
+
将 Node.js 项目一键打包为 Android / iOS 移动应用;运行时由 @flun/nodejs-mobile-react-native 提供,无需修改你的 Node 代码;
|
|
4
|
+
|
|
5
|
+
**核心理念**:你的 Node 项目保持不变,CLI 负责搬运,编译,打包;所有定制集中在 `mobileAppConfig.js` 一个文件;
|
|
6
|
+
|
|
7
|
+
- GitHub:https://github.com/OpenFlun/node-mobile-app
|
|
8
|
+
- Gitee(中国):https://gitee.com/OpenFlun/node-mobile-app
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## 特性
|
|
13
|
+
|
|
14
|
+
- **零侵入**:Node 项目源码,依赖,配置都不动,CLI 在独立目录里完成构建
|
|
15
|
+
- **自动识别服务地址**:拦截 `server.js` 里的 `listen()` 调用,动态获取真实协议和端口
|
|
16
|
+
- **失败可见**:5 秒内未启动,加载异常,App 显示错误页并支持展开详情(开发者可查)
|
|
17
|
+
- **增量构建**:文件指纹判断缓存,无变化时 10 秒级重跑
|
|
18
|
+
- **跨平台**:Android(Windows / macOS / Linux)+ iOS(仅 macOS)
|
|
19
|
+
- **离线可用**:`build` 打出的 APK / IPA 内置 JS,无需连电脑也能跑
|
|
20
|
+
- **node_modules 优化(默认开启)**:构建时先交叉编译原生模块,再自动执行六阶段优化--先清空 postinstall 资源(保留 js 供合并),再合并 JS,清平台二进制,清开发文件,清中间产物,清冗余与空目录;编译源文件与 node-gyp 中间产物在编译完成后一并清理,仅保留 `.node`;大幅减少打包文件数与体积,加速启动,无需配置;
|
|
21
|
+
- **热更新开箱可用**:`test` 自动启动 Metro 并后台常驻,命令结束后仍可热更新;详见 [自动化机制](#自动化机制);
|
|
22
|
+
- **签名切换自动处理**:设备已装包与待装包签名不一致时,`test` 自动卸载重装,避免 `INSTALL_FAILED_UPDATE_INCOMPATIBLE`;
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 环境要求(最低)
|
|
27
|
+
|
|
28
|
+
| 项 | 要求 |
|
|
29
|
+
| ------------ | ------------------------------------------------------------------- |
|
|
30
|
+
| Node.js | 需满足 `package.json` 的 `engines.node` 字段 |
|
|
31
|
+
| Android 构建 | JDK **17**,Android SDK(minSdk 29 / targetSdk 36 / compileSdk 37) |
|
|
32
|
+
| iOS 构建 | macOS + 完整 Xcode + CocoaPods |
|
|
33
|
+
| 可选 | watchman(提升 Metro 文件监听性能) |
|
|
34
|
+
| Windows 额外 | Visual Studio + Git for Windows(仅编译原生模块时需要,见下方说明) |
|
|
35
|
+
|
|
36
|
+
**JDK 必须是 17**,Android Gradle Plugin 目前不支持更高版本;
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 本包目录结构:
|
|
41
|
+
```txt
|
|
42
|
+
@flun/node-mobile-app/
|
|
43
|
+
│
|
|
44
|
+
├── bin/
|
|
45
|
+
│ └── cli.js # CLI 入口(命令分发)
|
|
46
|
+
│
|
|
47
|
+
├── cli-assets/
|
|
48
|
+
│ └── server.js # 默认 server 模板(你的项目无 server.js 时复制过去)
|
|
49
|
+
│
|
|
50
|
+
├── scripts/
|
|
51
|
+
│ └── copy-files.js # postinstall 钩子:在你的项目根生成 mobileAppConfig.js
|
|
52
|
+
│
|
|
53
|
+
├── src/
|
|
54
|
+
│ ├── config.js # 配置加载 + 校验(DEFAULT_CONFIG / loadConfig / validateConfig)
|
|
55
|
+
│ ├── copy.js # 模板复制 / 你的项目复制 / ABI patch / extraRnDependencies 注入
|
|
56
|
+
│ ├── fingerprint.js # 缓存指纹(判断是否需要清理构建缓存)
|
|
57
|
+
│ ├── generate.js # 生成 main.js(桥接)+ mobileApp.runtime.ts(运行时配置)
|
|
58
|
+
│ ├── install.js # 依赖安装 + 原生模块交叉编译(前移至优化前) + 插件 abiFilters patch + WebView SSL patch
|
|
59
|
+
│ ├── optimize-node-modules.js # node_modules 优化(六阶段:清资源 / 合并 JS / 清平台二进制 / 清开发文件与编译源文件 / 清 node-gyp 中间产物 / 清冗余与空目录)
|
|
60
|
+
│ ├── patcher.js # 应用信息 / Android / iOS 配置 patch
|
|
61
|
+
│ ├── platform-ios.js # iOS 构建(pod install / xcodebuild archive / export)
|
|
62
|
+
│ ├── utils.js # 通用工具(文件操作 / 进程调用 / adb / hermesc 定位)
|
|
63
|
+
│ └── commands/
|
|
64
|
+
│ ├── test.js # `test` 命令
|
|
65
|
+
│ ├── build.js # `build` 命令
|
|
66
|
+
│ └── clean.js # `clean` 命令
|
|
67
|
+
│
|
|
68
|
+
├── template/ # RN 工程模板(运行时复制到你的项目的 node-mobile-app-build/)
|
|
69
|
+
│ ├── android/ # Android 原生工程
|
|
70
|
+
│ ├── ios/ # iOS 原生工程
|
|
71
|
+
│ ├── App.tsx # RN 主界面(WebView + Node 桥接 + 错误页)
|
|
72
|
+
│ ├── index.js # RN 入口(注册根组件)
|
|
73
|
+
│ ├── app.json # RN 应用名(CLI 会覆盖)
|
|
74
|
+
│ ├── babel.config.js
|
|
75
|
+
│ ├── eslint.config.js
|
|
76
|
+
│ ├── metro.config.js # Metro 配置(watchFolders / nodeModulesPaths)
|
|
77
|
+
│ ├── mobileApp.runtime.d.ts # App.tsx 里 import 的类型声明(运行时由 CLI 生成 .ts)
|
|
78
|
+
│ ├── package.json # RN 工程依赖清单
|
|
79
|
+
│ ├── .prettierrc.js
|
|
80
|
+
│ ├── Gemfile
|
|
81
|
+
│ └── .watchmanconfig # watchman 文件监控配置(详见下方说明)
|
|
82
|
+
│
|
|
83
|
+
├── mobileAppConfig.js # 你的配置模板(postinstall 时复制到你的项目根)
|
|
84
|
+
├── package.json
|
|
85
|
+
├── README.md # 本文件
|
|
86
|
+
├── Android构建指南.md # Android 环境配置与踩坑清单
|
|
87
|
+
├── 自定义libnode指南.md # 自编译 libnode.so 的完整流程
|
|
88
|
+
└── 其它略...
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
**关键约定**:
|
|
92
|
+
- `template/` 是**只读模板**;CLI 每次 `test`/`build` 会把它复制到你的项目的 `node-mobile-app-build/`,你如手改模板内容会被覆盖
|
|
93
|
+
- 你的持久化的自定义项应写进 `mobileAppConfig.js`,或通过 `keepFiles` 保留特定模板文件
|
|
94
|
+
- `template/.watchmanconfig` 会在 `copyTemplate` 时复制到 `node-mobile-app-build/.watchmanconfig`,供 Metro 的 watchman 使用
|
|
95
|
+
|
|
96
|
+
### .watchmanconfig 说明
|
|
97
|
+
|
|
98
|
+
位于包根目录,配置 watchman 的文件监控行为:
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"ignore_dirs": [
|
|
103
|
+
".git", ".vs", ".vscode", ".idea",
|
|
104
|
+
"android/build", "android/app/build", "android/.gradle", "android/.cxx", "android/.kotlin",
|
|
105
|
+
"ios/build", "ios/Pods",
|
|
106
|
+
"node-mobile-app-build", "nodejs-assets",
|
|
107
|
+
"out", "dist", "dist-apk", "coverage"
|
|
108
|
+
],
|
|
109
|
+
"settle": 20
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- **`ignore_dirs`**:排除的目录(构建产物,缓存,IDE 配置);**不要排除 `node_modules`**,Metro 需要监控它来解析依赖
|
|
114
|
+
- **`settle`**:防抖延迟(毫秒),短时间内多次文件变更只触发一次重编
|
|
115
|
+
- 改完后需 `watchman watch-del-all && watchman shutdown-server` 才生效
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
## 基本配置
|
|
119
|
+
|
|
120
|
+
### 允许安装脚本执行
|
|
121
|
+
|
|
122
|
+
本包在安装时可能触发某些依赖包的自动脚本(如 `postinstall` 等);如果你的 npm 全局配置或项目配置禁止了脚本执行(例如设置了 `ignore-scripts=true`),可能会导致安装不完整或运行时异常;
|
|
123
|
+
|
|
124
|
+
推荐在项目根目录的 `package.json` 中添加 `allowScripts` 字段,显式放行本包及其依赖的脚本:
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"allowScripts": {
|
|
129
|
+
"esbuild": true,
|
|
130
|
+
"@flun/node-mobile-app": true,
|
|
131
|
+
"@flun/nodejs-mobile-react-native":true
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
## 安装
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
npm i -D @flun/node-mobile-app
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
安装完成后,会在你的项目根目录自动生成 `mobileAppConfig.js`(配置文件模板);
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## 快速开始
|
|
147
|
+
|
|
148
|
+
```bash
|
|
149
|
+
# 1. 编辑配置
|
|
150
|
+
# 打开 mobileAppConfig.js,改 appId / appName / serverPath 等
|
|
151
|
+
|
|
152
|
+
# 2. 开发调试(需连 USB,走 Metro 热更新,如需用模拟器请在 mobileAppConfig.js文件中显式配置)
|
|
153
|
+
npx node-mobile-app test
|
|
154
|
+
|
|
155
|
+
# 3. 打包发布
|
|
156
|
+
npx node-mobile-app build --release
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## 命令说明
|
|
162
|
+
|
|
163
|
+
| 命令 | 用途 |
|
|
164
|
+
| ------------------------------------- | --------------------------------------------------------------------------------- |
|
|
165
|
+
| `npx node-mobile-app test` | 编译并安装到设备(**需连 USB**);自动启动 Metro 并后台常驻,支持热更新;设备已装包签名不一致时自动卸载 |
|
|
166
|
+
| `npx node-mobile-app test --ios` | iOS 版(仅 macOS) |
|
|
167
|
+
| `npx node-mobile-app build` | 打 debug APK(**离线可用**) |
|
|
168
|
+
| `npx node-mobile-app build --release` | 打 release APK(默认用 debug keystore 签名,可安装;上架需配置 `android.signing`) |
|
|
169
|
+
| `npx node-mobile-app build --ios` | 打 IPA(仅 macOS) |
|
|
170
|
+
| `npx node-mobile-app clean` | 清理构建缓存 |
|
|
171
|
+
|
|
172
|
+
### 常用选项
|
|
173
|
+
|
|
174
|
+
| 选项 | 用途 |
|
|
175
|
+
| --------------- | ---------------------------------------------- |
|
|
176
|
+
| `--ios` | 目标平台为 iOS(默认 Android) |
|
|
177
|
+
| `--release` | 打 release 包(仅 `build`) |
|
|
178
|
+
| `--device <id>` | 指定设备(`test`) |
|
|
179
|
+
| `--arch <abi>` | 指定 ABI,逗号分隔(`build`,仅 Android) |
|
|
180
|
+
| `--debug` | 显示详细日志(优化各阶段明细,各命令完整输出) |
|
|
181
|
+
|
|
182
|
+
### 安装 APK 到手机
|
|
183
|
+
|
|
184
|
+
`build` 打出的 APK 在 `outputDir`(默认 `./out/`)里;手动装到手机:
|
|
185
|
+
|
|
186
|
+
Windows(用环境变量定位 adb,任何用户通用):
|
|
187
|
+
|
|
188
|
+
```powershell
|
|
189
|
+
$adb = "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe"
|
|
190
|
+
& $adb install -r "<编译好的 APK 完整路径>"
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
macOS / Linux:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
adb install -r "<编译好的 APK 完整路径>"
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
例如(`build` 末尾会打印完整路径):
|
|
200
|
+
|
|
201
|
+
```powershell
|
|
202
|
+
# Windows
|
|
203
|
+
& $adb install -r "D:\你的项目\out\myapp-1.0.0-release.apk"
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
# macOS / Linux
|
|
208
|
+
adb install -r "./out/myapp-1.0.0-release.apk"
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
**说明**:
|
|
212
|
+
- `-r` = 覆盖安装(保留应用数据)
|
|
213
|
+
- **签名不同的包不能互相覆盖**:`build` 的 release 包用 `android.signing` 的 keystore 签名,`test` / `build` 的 debug 包用模板自带 debug keystore 签名;两者包名相同但签名不同,直接 `install -r` 会报 `INSTALL_FAILED_UPDATE_INCOMPATIBLE: signatures do not match`;需先执行 `adb uninstall <appId>` 再安装(会清除应用数据)
|
|
214
|
+
- `adb` 找不到?在 `mobileAppConfig.js` 里配 `android.adbPath`
|
|
215
|
+
- `test` 命令已自动处理签名冲突并安装,无需手动
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## 自动化机制
|
|
220
|
+
|
|
221
|
+
- **快照双哈希**:`.deps-snapshot.json` 记录 `optimizeHash`(`optimize-node-modules.js` 内容哈希)与 `installerHash`(`install.js` 内容哈希);任一变化即触发重装、重编、重优化,避免流程代码更新后仍复用旧缓存;
|
|
222
|
+
- **bundle 变化失效 Gradle 缓存**:`test` 生成 JS bundle 后,与 `android/app/build/intermediates/assets/debug/mergeDebugAssets/` 中的合并结果比对 SHA256;不一致时删除合并目录,强制 Gradle 重新合并;一致时保持 UP-TO-DATE;
|
|
223
|
+
- **编译前执行 `patch-package.js`**:把原生模块 `package.json` 中的 `node-gyp-build` 替换为 `node-gyp-build-mobile`,使编译走 `@flun/nodejs-mobile-gyp` 而非 npm 自带的 `node-gyp`;
|
|
224
|
+
- **Metro 生命周期**:`test` 执行前检测 `localhost:8081/status`;未运行则以 detached 方式启动 `react-native start`(日志写入 `node-mobile-app-build/.metro.log`),就绪后继续;`run-android` 加 `--no-packager`,命令结束后 Metro 保持运行;30 秒未就绪打印警告并回落到 APK 内置 bundle;
|
|
225
|
+
- **输出分级**:步骤标题 0 空格,动作与状态 2 空格,结果与完成 4 空格,子项详情 8 空格;优化阶段作为步骤子项,阶段标题 4 空格、阶段结果 6 空格;
|
|
226
|
+
- **精简与详细双模式**:默认只输出关键行与结果,`--debug` 或 `OPTIMIZE_DEBUG=1` 时全量输出(含 Gradle 与 Metro 完整日志);
|
|
227
|
+
|
|
228
|
+
## 配置文件 `mobileAppConfig.js`
|
|
229
|
+
|
|
230
|
+
所有定制集中在这一个文件;**不配置也能跑**(用默认值);
|
|
231
|
+
|
|
232
|
+
### 必填
|
|
233
|
+
|
|
234
|
+
| 字段 | 类型 | 说明 |
|
|
235
|
+
| ------------ | -------- | ----------------------------------------- |
|
|
236
|
+
| `serverPath` | `string` | Node 启动脚本路径(默认 `'./server.js'`) |
|
|
237
|
+
|
|
238
|
+
### 应用信息
|
|
239
|
+
|
|
240
|
+
| 字段 | 类型 | 说明 |
|
|
241
|
+
| ------------- | ---------------- | -------------------------------------------------------------------------- |
|
|
242
|
+
| `appName` | `string \| null` | 应用显示名称(默认从 `package.json` 的 `name` 读) |
|
|
243
|
+
| `outputDir` | `string \| null` | APK / IPA 输出目录(默认 `./out`) |
|
|
244
|
+
| `appId` | `string` | 应用唯一标识,反向域名格式(Android `applicationId` / iOS Bundle ID) |
|
|
245
|
+
| `versionCode` | `int` | 内部版本号(Android `versionCode` / iOS `CFBundleVersion`) |
|
|
246
|
+
| `versionName` | `string` | 你的可见版本名(Android `versionName` / iOS `CFBundleShortVersionString`) |
|
|
247
|
+
|
|
248
|
+
### WebView
|
|
249
|
+
|
|
250
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
251
|
+
| --------------------- | --------- | ------------------- | ------------------------------------------------------------------------------------------ |
|
|
252
|
+
| `showLoading` | `boolean` | `true` | 是否显示加载指示器 |
|
|
253
|
+
| `loadingText` | `string` | `'正在启动服务...'` | 加载提示文字 |
|
|
254
|
+
| `enableJavaScript` | `boolean` | `true` | 是否启用 JavaScript |
|
|
255
|
+
| `enableDomStorage` | `boolean` | `true` | 是否启用 DOM Storage |
|
|
256
|
+
| `allowFileAccess` | `boolean` | `true` | 是否允许访问本地文件 |
|
|
257
|
+
| `mixedContentMode` | `string` | `'always'` | 混合内容模式:`never` / `always` / `compatibility` |
|
|
258
|
+
| `backgroundColor` | 见下 | `'#ffffff'` | WebView 背景色;支持:固定色 `'#ffffff'` / 跟随系统 `'system'` / 深浅两值 `{ light, dark }` |
|
|
259
|
+
| `allowSelfSignedCert` | `boolean` | `false` | 见下文"HTTPS 自签证书" |
|
|
260
|
+
|
|
261
|
+
### Android
|
|
262
|
+
|
|
263
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
264
|
+
| ----------------------- | ---------------- | -------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
265
|
+
| `sdkPath` | `string \| null` | `null` | Android SDK 路径(默认自动查找) |
|
|
266
|
+
| `adbPath` | `string \| null` | `null` | adb 路径(默认自动查找) |
|
|
267
|
+
| `minSdkVersion` | `int` | `29` | 最低 SDK(29=Android 10.0) |
|
|
268
|
+
| `targetSdkVersion` | `int` | `36` | 目标 SDK |
|
|
269
|
+
| `compileSdkVersion` | `int` | `37` | 编译 SDK |
|
|
270
|
+
| `buildToolsVersion` | `string` | `'37.0.0'` | 构建工具版本 |
|
|
271
|
+
| `abiFilters` | `string[]` | `['arm64-v8a']` | 打包架构(真机 `arm64-v8a`,模拟器加 `x86_64`) |
|
|
272
|
+
| `icon` | `string` | `'./build/icon.png'` | 应用图标(建议 512×512 PNG) |
|
|
273
|
+
| `usesCleartextTraffic` | `boolean` | `true` | 是否允许明文 HTTP |
|
|
274
|
+
| `permissions` | `string[]` | `[]` | 额外权限(如 `'android.permission.CAMERA'`) |
|
|
275
|
+
| `signing` | `object` | - | 自定义签名配置.**不填则用模板自带的 debug keystore 签名**(可安装测试,不可上架);填则以下 4 项均为必填 |
|
|
276
|
+
| `signing.keystore` | `string` | - | keystore 路径(相对你的项目根) |
|
|
277
|
+
| `signing.storePassword` | `string` | - | keystore 密码 |
|
|
278
|
+
| `signing.keyAlias` | `string` | - | 密钥别名 |
|
|
279
|
+
| `signing.keyPassword` | `string` | - | 密钥密码(通常与 `storePassword` 相同) |
|
|
280
|
+
|
|
281
|
+
#### 生成自签名 keystore
|
|
282
|
+
|
|
283
|
+
如需自定义签名(上架或长期使用),先生成 keystore 文件.`keytool` 随 JDK 提供:
|
|
284
|
+
|
|
285
|
+
- 若已设 `JAVA_HOME`:`& "$env:JAVA_HOME\bin\keytool.exe"`
|
|
286
|
+
- 否则用 JDK 安装目录下的完整路径,例如 `C:\Program Files\Java\jdk-17.0.20\bin\keytool.exe`
|
|
287
|
+
|
|
288
|
+
```powershell
|
|
289
|
+
# Windows PowerShell
|
|
290
|
+
& "<JDK 安装目录>\bin\keytool.exe" -genkeypair -v `
|
|
291
|
+
-keystore "<你的项目根>\build\release.keystore" `
|
|
292
|
+
-alias testkey `
|
|
293
|
+
-keyalg RSA -keysize 2048 -validity 10000 `
|
|
294
|
+
-storepass <keystore 密码> -keypass <密钥密码> `
|
|
295
|
+
-dname "CN=Test, OU=Dev, O=Test, L=City, S=State, C=CN"
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
```bash
|
|
299
|
+
# macOS / Linux
|
|
300
|
+
keytool -genkeypair -v \
|
|
301
|
+
-keystore "<你的项目根>/build/release.keystore" \
|
|
302
|
+
-alias testkey \
|
|
303
|
+
-keyalg RSA -keysize 2048 -validity 10000 \
|
|
304
|
+
-storepass <keystore 密码> -keypass <密钥密码> \
|
|
305
|
+
-dname "CN=Test, OU=Dev, O=Test, L=City, S=State, C=CN"
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
生成后,把路径,密码,别名填入 `mobileAppConfig.js` 的 `android.signing`:
|
|
309
|
+
|
|
310
|
+
```js
|
|
311
|
+
signing: {
|
|
312
|
+
keystore: './build/release.keystore', // 相对你的项目根
|
|
313
|
+
storePassword: '<keystore 密码>',
|
|
314
|
+
keyAlias: 'testkey',
|
|
315
|
+
keyPassword: '<密钥密码>',
|
|
316
|
+
},
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
> **提示**:`storepass` / `keypass` 可填相同值,对应配置里 `storePassword` / `keyPassword` 也填相同值.四项缺一不可,缺项时构建前会报错.
|
|
320
|
+
|
|
321
|
+
### iOS
|
|
322
|
+
|
|
323
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
324
|
+
| ----------------------------- | -------- | -------------------- | ------------------------------------------------------ |
|
|
325
|
+
| `deploymentTarget` | `string` | `'15.1'` | 最低 iOS 版本 |
|
|
326
|
+
| `icon` | `string` | `'./build/icon.png'` | 应用图标(建议 1024×1024 PNG) |
|
|
327
|
+
| `signing.teamId` | `string` | - | Apple Developer Team ID |
|
|
328
|
+
| `signing.provisioningProfile` | `string` | - | 描述文件路径(写入 `exportOptions.plist`) |
|
|
329
|
+
| `signing.certificate` | `string` | - | P12 证书路径(导入临时 keychain 供 xcodebuild 签名用) |
|
|
330
|
+
| `signing.certificatePassword` | `string` | - | P12 密码 |
|
|
331
|
+
|
|
332
|
+
### 高级
|
|
333
|
+
|
|
334
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
335
|
+
| ---------------------------- | --------- | ------ | -------------------------- |
|
|
336
|
+
| `advanced.keepAlive` | `boolean` | `true` | 是否发送心跳保持 Node 进程 |
|
|
337
|
+
| `advanced.heartbeatInterval` | `int` | `5000` | 心跳间隔(毫秒) |
|
|
338
|
+
|
|
339
|
+
### 扩展点
|
|
340
|
+
|
|
341
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
342
|
+
| --------------------- | ---------- | ---- | ----------------------------------------------------- |
|
|
343
|
+
| `keepFiles` | `string[]` | `[]` | 不重置的模板文件(路径相对 `node-mobile-app-build/`) |
|
|
344
|
+
| `extraRnDependencies` | `string[]` | `[]` | 额外 RN 原生依赖包名(需先安装在你的开发字段中) |
|
|
345
|
+
|
|
346
|
+
### 排除 / 白名单
|
|
347
|
+
|
|
348
|
+
| 字段 | 说明 |
|
|
349
|
+
| -------------- | ---------------------------------------------------------------------------- |
|
|
350
|
+
| `excludeFiles` | 复制到 build 目录时跳过的文件/目录(支持 `*.log`,`build/` 等) |
|
|
351
|
+
| `allowScripts` | 移动端 Node 环境里允许跑安装脚本的包(会写入 `nodejs-project/package.json`) |
|
|
352
|
+
|
|
353
|
+
### node_modules 优化
|
|
354
|
+
|
|
355
|
+
构建时自动优化 `node_modules`(默认开启,无需配置),减少打包文件数与体积,加速启动.
|
|
356
|
+
|
|
357
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
358
|
+
| --------- | ---------- | ------ | ----------------------------------------------------------- |
|
|
359
|
+
| `enabled` | `boolean` | `true` | 是否启用优化 |
|
|
360
|
+
| `exclude` | `string[]` | `[]` | 排除优化时异常或不想优化的包(写 `package.json` 的 `name`) |
|
|
361
|
+
|
|
362
|
+
**编译与优化顺序**:先交叉编译原生模块(见 `install.js`),再执行以下六阶段优化:
|
|
363
|
+
|
|
364
|
+
1. **清空资源**:扫描各包 `postinstall` 引用的目录/文件,保留目录结构,清空内容;js 文件一律保留,留待合并阶段处理;
|
|
365
|
+
2. **合并 JS**:按包入口 bundle,多个 JS 文件合并为单文件(`bundled/` 目录);合并后同步删除 `package.json` 的 `scripts` 字段(运行时无安装期,且 Gradle `npm rebuild` 会触发脚本导致失败);
|
|
366
|
+
3. **清平台二进制**:按目标平台 + `abiFilters` 判定;`prebuilds/<platform>-<arch>` 按目录整体处理--Android 只保留 `android`,`linux` / `darwin` / `win32` 删除;iOS 只保留 `darwin`;其余二进制逐文件按文件头判定;
|
|
367
|
+
4. **清开发文件与编译源文件**:删除 `.md` / `.map` / `.d.ts` / `.h` / `.c` / `.cc` / `.cpp` / `.cxx` 等非运行文件;原生模块已在优化前完成编译,编译源文件无需保留;
|
|
368
|
+
5. **清 node-gyp 中间产物**:删除 `build/Release/obj.target/` 下的中间副本,以及 `.o` / `.d` / `.mk` / `.stamp` / `Makefile` 等编译中间文件;
|
|
369
|
+
6. **清不参与运行的文件和空目录**.
|
|
370
|
+
|
|
371
|
+
**缓存**:快照记录在 `node-mobile-app-build/.deps-snapshot.json`,构建时自动判断"重装并优化 / 仅优化 / 跳过";改动模板或依赖会自动触发重编.
|
|
372
|
+
|
|
373
|
+
**异常排查**:
|
|
374
|
+
|
|
375
|
+
- `optimize: { enabled: false }` 整体关闭优化;
|
|
376
|
+
- `optimize: { exclude: ['包名'] }` 排除优化时异常或不想优化的包;
|
|
377
|
+
- 加 `--debug` 查看优化各阶段明细与各命令完整输出.
|
|
378
|
+
|
|
379
|
+
## 服务地址说明
|
|
380
|
+
|
|
381
|
+
CLI **自动识别 `server.js` 实际监听的协议和端口**--拦截 `net.Server.prototype.listen`,从 `server.address()` 取真实端口,从 `Server` 类型判断 `http` / `https`;
|
|
382
|
+
|
|
383
|
+
因此 `mobileAppConfig.js` **不需要**配置端口/协议;动态端口(`listen(0)`)会拿到系统分配的真实端口;
|
|
384
|
+
|
|
385
|
+
**失败场景**:
|
|
386
|
+
- `server.js` 加载抛异常 → App 显示"应用启动失败"
|
|
387
|
+
- 5 秒内未调用 `listen()` → App 显示"应用启动失败"
|
|
388
|
+
|
|
389
|
+
你会看到简要提示,开发者点开"▶ 查看详细信息"能看到具体原因;
|
|
390
|
+
|
|
391
|
+
---
|
|
392
|
+
|
|
393
|
+
## HTTPS 自签证书
|
|
394
|
+
|
|
395
|
+
`webview.allowSelfSignedCert` 控制是否放行**不受信任的 HTTPS 证书**:
|
|
396
|
+
|
|
397
|
+
| 场景 | 是否受开关影响 |
|
|
398
|
+
| --------------------------------------------- | ------------------- |
|
|
399
|
+
| HTTP | 无关 |
|
|
400
|
+
| HTTPS + 真证书(Let's Encrypt 等) | 无关 |
|
|
401
|
+
| HTTPS + 自签证书 + 已装进设备信任库 | 无关 |
|
|
402
|
+
| HTTPS + 自签证书 + 未装设备(本地测试最常见) | **必须设为 `true`** |
|
|
403
|
+
|
|
404
|
+
**实现方式**:
|
|
405
|
+
- Android:patch `RNCWebViewClient.java`,仅对 `127.0.0.1` / `localhost` 放行
|
|
406
|
+
- iOS:patch `RNCWebViewImpl.m`,同上
|
|
407
|
+
|
|
408
|
+
其他域名仍严格校验;生产环境建议关闭;
|
|
409
|
+
|
|
410
|
+
---
|
|
411
|
+
|
|
412
|
+
## Android / iOS 差异
|
|
413
|
+
|
|
414
|
+
| 项 | Android | iOS |
|
|
415
|
+
| ------------ | --------------------------------------------------------- | ---------------------------------------- |
|
|
416
|
+
| 构建环境 | Windows / macOS / Linux | **仅 macOS** |
|
|
417
|
+
| 运行时版本 | 官方提供多个版本,可用 `NODE_MOBILE_PREBUILT_VERSION` 切换 | **当前为 v18.20.4**,更高版本后续逐步适配 |
|
|
418
|
+
| Express 版本 | 产物带 full-icu,4.x / 5.x 均可用 | 当前产物不带 full-icu,**必须用 4.x** |
|
|
419
|
+
| full-icu | 自 v22.23.2 产物起支持 | 暂无 |
|
|
420
|
+
| `test` 离线 | ✓(内置 bundle) | ✓(需 `FORCE_BUNDLING=1`) |
|
|
421
|
+
| 图标尺寸 | 5 个密度(48~192) | 9 个尺寸(40~1024) |
|
|
422
|
+
|
|
423
|
+
**iOS 运行时版本**:iOS 附件的实际运行时版本随适配进度变化,**当前对应 v18.20.4**;如需更高版本,可克隆 [nodejs-mobile 仓库](https://github.com/OpenFlun/nodejs-mobile) 自行编译 `NodeMobile.xcframework`,流程与 Android 自编译 `libnode.so` 类似(见 `自定义libnode指南.md`);
|
|
424
|
+
|
|
425
|
+
---
|
|
426
|
+
|
|
427
|
+
## 你的项目结构
|
|
428
|
+
|
|
429
|
+
运行 CLI 后,你的项目根目录的样子:
|
|
430
|
+
|
|
431
|
+
```
|
|
432
|
+
你的项目/
|
|
433
|
+
├── package.json # 你自己的
|
|
434
|
+
├── mobileAppConfig.js # CLI 生成的配置(可编辑)
|
|
435
|
+
├── server.js # Node 启动脚本(你写的,或 CLI 生成的示例)
|
|
436
|
+
├── node_modules/ # 你的依赖
|
|
437
|
+
├── build/ # 你的资源(图标,keystore 等)
|
|
438
|
+
│ ├── icon.png
|
|
439
|
+
│ └── release.keystore
|
|
440
|
+
│── 你的其它文件/目录...
|
|
441
|
+
└── node-mobile-app-build/ # CLI 生成的 RN 工程(可整体删除重建)
|
|
442
|
+
├── android/ ios/ App.tsx index.js ...
|
|
443
|
+
├── mobileApp.runtime.ts # CLI 生成,App.tsx 读
|
|
444
|
+
└── nodejs-assets/
|
|
445
|
+
└── nodejs-project/ # 你的 Node 项目副本
|
|
446
|
+
├── server.js # 你的源码
|
|
447
|
+
├── main.js # CLI 生成,桥接代码
|
|
448
|
+
│── 你允许的其它生产文件/目录...
|
|
449
|
+
├── package.json # 只保留 dependencies
|
|
450
|
+
└── node_modules/ # 你的生产依赖
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
---
|
|
454
|
+
|
|
455
|
+
## 常见问题
|
|
456
|
+
|
|
457
|
+
### Q:`test` 拔掉 USB 后 App 加载慢?
|
|
458
|
+
|
|
459
|
+
`test` 打的是 debug 版,启动时优先连 Metro;CLI 会在 `[9/11]` 自动启动 Metro 并保持后台常驻,但设备通过 `adb reverse` 访问 `localhost:8081`,**拔掉 USB 后端口转发失效**,设备连不上 Metro,debug 包等待超时后才回落到 APK 内置的 bundle;这个"等超时"是 RN debug 版的固有行为;
|
|
460
|
+
|
|
461
|
+
拔线后的启动速度(从快到慢):
|
|
462
|
+
|
|
463
|
+
1. **`npx node-mobile-app build --release`** 打包后安装到手机--最快(release 版不连 Metro)
|
|
464
|
+
2. **`npx node-mobile-app build`** 打包后安装到手机--次之(debug 版,会先尝试连 Metro 再回退)
|
|
465
|
+
3. **`npx node-mobile-app test`** 后手动打开应用--最慢(同上,且 `test` 面向"连 USB 热更新"场景)
|
|
466
|
+
|
|
467
|
+
若需要**热更新**,保持 USB 连接(维持 `adb reverse` 的端口转发);不需要热更新时,用 `build --release` 打包可避免等待 Metro 超时.
|
|
468
|
+
|
|
469
|
+
### Q:`test` 装到手机后拔 USB 就崩?
|
|
470
|
+
|
|
471
|
+
前提是 APK 里有内置 bundle;`test` 每次都会先 `react-native bundle` 打进 APK;**如果崩,检查 CLI 输出里 `[7/11] 生成 JS bundle（离线可用）` 是否成功**;
|
|
472
|
+
|
|
473
|
+
### Q:Node 进程启动失败怎么排查?
|
|
474
|
+
|
|
475
|
+
App 显示"应用启动失败"页 → 点"▶ 查看详细信息" → 看到具体原因(如 `加载 ./server.js 失败 -- ...`);
|
|
476
|
+
|
|
477
|
+
进一步用 `adb logcat` 看 Node 日志:
|
|
478
|
+
|
|
479
|
+
```bash
|
|
480
|
+
adb logcat -c
|
|
481
|
+
adb shell am force-stop <你的 appId>
|
|
482
|
+
adb shell am start -n <你的 appId>/.MainActivity
|
|
483
|
+
adb logcat | grep -E "NODEJS-MOBILE|ReactNativeJS"
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
### Q:`npm install` 时提示 `install-scripts not yet covered by allowScripts`?
|
|
487
|
+
这是 npm 的提醒,表示某些依赖带有 `postinstall` / `install` 脚本,尚未在 `allowScripts` 里显式放行;`@flun/node-mobile-app` 及其依赖(`@flun/nodejs-mobile-react-native`、`esbuild` 等)需要执行这些脚本才能完整安装;
|
|
488
|
+
|
|
489
|
+
放行方式见 [允许安装脚本执行](#允许安装脚本执行):在项目根 `package.json` 中添加 `allowScripts` 字段,逐项设为 `true`;
|
|
490
|
+
|
|
491
|
+
未放行的后果:依赖虽能装完,但脚本未执行,运行时可能报模块缺失或二进制找不到;
|
|
492
|
+
|
|
493
|
+
### Q:Android 构建卡在拉取依赖(`react-android` / `hermes-android` 等)?
|
|
494
|
+
|
|
495
|
+
Android 模板的 `settings.gradle` 与 `build.gradle` 已在 `google()` / `mavenCentral()` 之前插入阿里云镜像,国内网络优先走镜像;海外网络镜像不命中会自动回退官方源,不影响功能.
|
|
496
|
+
|
|
497
|
+
若仍卡住:
|
|
498
|
+
|
|
499
|
+
- 检查镜像可达:浏览器打开 `https://maven.aliyun.com/repository/public` 是否正常;
|
|
500
|
+
- 检查本机 `~/.gradle/init.gradle` 是否有与仓库顺序冲突的配置(如强制替换仓库),有则临时移除以排除干扰;
|
|
501
|
+
- 停掉残留 Daemon 后重试:在 `node-mobile-app-build/android/` 下执行 `gradlew --stop`,再重跑 `test` / `build`.
|
|
502
|
+
|
|
503
|
+
### Q:Express 版本怎么选?
|
|
504
|
+
|
|
505
|
+
- **Android**:内置完整 ICU(full-icu)→ 可以用 Express 5
|
|
506
|
+
- **iOS**:暂无 ICU → 必须用 Express 4
|
|
507
|
+
|
|
508
|
+
Express 5 的路由语法与 4 不同(如 `app.get('*')` 要改成 `app.get('/{*splat}')`),迁移时留意;
|
|
509
|
+
|
|
510
|
+
### Q:`libnode.so` 和 `NodeMobile.xcframework` 是怎么来的?
|
|
511
|
+
|
|
512
|
+
从 `@flun/nodejs-mobile-react-native` 1.0.1 起,两套预编译二进制**不在 npm 包里**,改为 postinstall 阶段自动从 Gitee / GitHub Release 下载:
|
|
513
|
+
|
|
514
|
+
| 资源 | 目标位置 |
|
|
515
|
+
| -------------------------------- | --------------------------------------------------------------------------- |
|
|
516
|
+
| `android-libnode.zip` | `node_modules/@flun/nodejs-mobile-react-native/android/libnode/` |
|
|
517
|
+
| `ios-nodemobile.zip`(仅 macOS) | `node_modules/@flun/nodejs-mobile-react-native/ios/NodeMobile.xcframework/` |
|
|
518
|
+
|
|
519
|
+
- 默认下载版本以 `@flun/nodejs-mobile-react-native` 的 `package.json` 中 `prebuiltAssets.version` 字段为准
|
|
520
|
+
- Gitee 优先,失败自动回退 GitHub
|
|
521
|
+
- 已装版本匹配则跳过,不重复下
|
|
522
|
+
- 全部源失败时打印下载链接,**不中断 npm 安装**
|
|
523
|
+
|
|
524
|
+
环境变量:
|
|
525
|
+
|
|
526
|
+
```bash
|
|
527
|
+
NODE_MOBILE_PREBUILT_VERSION=<版本号> # 覆盖默认版本(须为该包 Release 中实际存在的 tag)
|
|
528
|
+
NODE_MOBILE_PREBUILT_SKIP=1 # 跳过全部下载
|
|
529
|
+
NODE_MOBILE_PREBUILT_IOS_SKIP=1 # 只跳过 iOS
|
|
530
|
+
```
|
|
531
|
+
|
|
532
|
+
### Q:如何替换成自定义编译的 `libnode.so`?
|
|
533
|
+
|
|
534
|
+
如果你自编译了 `libnode.so`(如需要特定 Node 版本或自定义 ICU),可手动覆盖自动下载的产物:
|
|
535
|
+
|
|
536
|
+
1. 把编译好的 `libnode.so` 覆盖到 `android/libnode/bin/<架构>/`(**只放你实际编译的架构**)
|
|
537
|
+
2. 如果 `mobileAppConfig.js` 的 `android.abiFilters` 与 libnode 支持的架构不一致,同步调整
|
|
538
|
+
3. 跑 `npx node-mobile-app build` 或 `npx node-mobile-app test`
|
|
539
|
+
|
|
540
|
+
**CLI 会自动处理缓存**:指纹机制检测到 `libnode.so` 或 `abiFilters` 变化,自动清理 `.cxx` / `android/build` / `app/build`,全量重编;**你无需手动清任何缓存**;
|
|
541
|
+
|
|
542
|
+
详细流程见 `自定义libnode指南.md`;
|
|
543
|
+
|
|
544
|
+
### Q:iOS 提示 `fallbackSourceURL does not override`?
|
|
545
|
+
|
|
546
|
+
RN 0.87 的 API 若变动,`AppDelegate.swift` 里的 fallback 可能不生效--不影响"连 Mac + Metro"正常开发,只是拔 Mac 后无法 fallback 到内置 bundle;届时反馈,我们更新适配;
|
|
547
|
+
|
|
548
|
+
---
|
|
549
|
+
|
|
550
|
+
## 相关文档
|
|
551
|
+
|
|
552
|
+
- [Android 构建指南.md](./Android%20构建指南.md) -- Android 环境配置,踩坑清单
|
|
553
|
+
- [自定义libnode指南.md](./自定义libnode指南.md) -- 自编译 `libnode.so` 的完整流程
|
|
554
|
+
|
|
555
|
+
---
|
|
556
|
+
|
|
557
|
+
## 许可
|
|
558
|
+
|
|
559
|
+
ISC
|