@flun/node-mobile-app 4.0.5 → 4.0.7
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/Android /346/236/204/345/273/272/346/214/207/345/215/227.md" +84 -76
- package/CHANGELOG.md +9 -9
- package/LICENSE +9 -4
- package/README.md +206 -113
- package/bin/cli.js +9 -9
- package/cli-assets/server.js +7 -4
- package/mobileAppConfig.js +32 -32
- package/package.json +5 -5
- package/scripts/copy-files.js +1 -1
- package/src/commands/build.js +9 -4
- package/src/commands/clean.js +3 -2
- package/src/commands/test.js +13 -9
- package/src/config.js +3 -3
- package/src/copy.js +41 -36
- package/src/fingerprint.js +4 -3
- package/src/generate.js +5 -3
- package/src/install.js +38 -27
- package/src/optimize-node-modules.js +10 -5
- package/src/patcher.js +37 -32
- package/src/platform-ios.js +6 -6
- package/src/utils.js +26 -22
- package/template/App.tsx +4 -4
- package/template/Gemfile +1 -1
- package/template/android/app/build.gradle +1 -1
- package/template/android/app/proguard-rules.pro +1 -1
- package/template/android/app/src/main/java/com/myapp/MainActivity.kt +1 -1
- package/template/android/app/src/main/java/com/myapp/MainApplication.kt +1 -1
- package/template/android/app/src/main/res/drawable/rn_edit_text_material.xml +6 -3
- package/template/android/app/src/main/res/raw/keep.xml +1 -1
- package/template/android/app/src/main/res/values/strings.xml +1 -1
- package/template/android/app/src/main/res/values/styles.xml +1 -1
- package/template/android/build.gradle +1 -1
- package/template/android/gradle.properties +1 -1
- package/template/android/gradlew +3 -2
- package/template/android/gradlew.bat +3 -2
- package/template/android/settings.gradle +1 -1
- package/template/app.json +1 -1
- package/template/index.js +2 -2
- package/template/ios/.xcode.env +1 -1
- package/template/ios/MyApp/Images.xcassets/AppIcon.appiconset/Contents.json +1 -1
- package/template/ios/MyApp/Images.xcassets/Contents.json +1 -1
- package/template/ios/MyApp/Info.plist +1 -1
- package/template/ios/MyApp/LaunchScreen.storyboard +30 -12
- package/template/ios/MyApp/PrivacyInfo.xcprivacy +1 -1
- package/template/ios/MyApp.xcodeproj/project.pbxproj +34 -15
- package/template/ios/MyApp.xcodeproj/xcshareddata/xcschemes/MyApp.xcscheme +1 -1
- package/template/ios/Podfile +1 -1
- package/template/package.json +1 -1
- package//350/207/252/345/256/232/344/271/211libnode/346/214/207/345/215/227.md +131 -98
package/README.md
CHANGED
|
@@ -17,7 +17,9 @@
|
|
|
17
17
|
- **增量构建**:文件指纹判断缓存,无变化时 10 秒级重跑
|
|
18
18
|
- **跨平台**:Android(Windows / macOS / Linux)+ iOS(仅 macOS)
|
|
19
19
|
- **离线可用**:`build` 打出的 APK / IPA 内置 JS,无需连电脑也能跑
|
|
20
|
-
- **node_modules 优化(默认开启)**:构建时先交叉编译原生模块,再自动执行六阶段优化--先清空 postinstall 资源(保留 js 供合并)
|
|
20
|
+
- **node_modules 优化(默认开启)**:构建时先交叉编译原生模块,再自动执行六阶段优化--先清空 postinstall 资源(保留 js 供合并),
|
|
21
|
+
再合并 JS,清平台二进制,清开发文件,清中间产物,清冗余与空目录;编译源文件与 node-gyp 中间产物在编译完成后一并清理,仅保留
|
|
22
|
+
`.node`;大幅减少打包文件数与体积,加速启动,无需配置;
|
|
21
23
|
- **热更新开箱可用**:`test` 自动启动 Metro 并后台常驻,命令结束后仍可热更新;详见 [自动化机制](#自动化机制);
|
|
22
24
|
- **签名切换自动处理**:设备已装包与待装包签名不一致时,`test` 自动卸载重装,避免 `INSTALL_FAILED_UPDATE_INCOMPATIBLE`;
|
|
23
25
|
|
|
@@ -25,13 +27,13 @@
|
|
|
25
27
|
|
|
26
28
|
## 环境要求(最低)
|
|
27
29
|
|
|
28
|
-
| 项 | 要求
|
|
29
|
-
| ------------ |
|
|
30
|
-
| Node.js | 需满足 `package.json` 的 `engines.node` 字段
|
|
30
|
+
| 项 | 要求 |
|
|
31
|
+
| ------------ | ---------------------------------------------------------------- |
|
|
32
|
+
| Node.js | 需满足 `package.json` 的 `engines.node` 字段 |
|
|
31
33
|
| 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(仅编译原生模块时需要,见下方说明)
|
|
34
|
+
| iOS 构建 | macOS + 完整 Xcode + CocoaPods |
|
|
35
|
+
| 可选 | watchman(提升 Metro 文件监听性能) |
|
|
36
|
+
| Windows 额外 | Visual Studio + Git for Windows(仅编译原生模块时需要,见下方说明) |
|
|
35
37
|
|
|
36
38
|
**JDK 必须是 17**,Android Gradle Plugin 目前不支持更高版本;
|
|
37
39
|
|
|
@@ -56,7 +58,8 @@
|
|
|
56
58
|
│ ├── fingerprint.js # 缓存指纹(判断是否需要清理构建缓存)
|
|
57
59
|
│ ├── generate.js # 生成 main.js(桥接)+ mobileApp.runtime.ts(运行时配置)
|
|
58
60
|
│ ├── install.js # 依赖安装 + 原生模块交叉编译(前移至优化前) + 插件 abiFilters patch + WebView SSL patch
|
|
59
|
-
│ ├── optimize-node-modules.js # node_modules 优化(六阶段:清资源 / 合并 JS / 清平台二进制 / 清开发文件与编译源文件 / 清
|
|
61
|
+
│ ├── optimize-node-modules.js # node_modules 优化(六阶段:清资源 / 合并 JS / 清平台二进制 / 清开发文件与编译源文件 / 清
|
|
62
|
+
node-gyp 中间产物 / 清冗余与空目录)
|
|
60
63
|
│ ├── patcher.js # 应用信息 / Android / iOS 配置 patch
|
|
61
64
|
│ ├── platform-ios.js # iOS 构建(pod install / xcodebuild archive / export)
|
|
62
65
|
│ ├── utils.js # 通用工具(文件操作 / 进程调用 / adb / hermesc 定位)
|
|
@@ -89,7 +92,8 @@
|
|
|
89
92
|
```
|
|
90
93
|
|
|
91
94
|
**关键约定**:
|
|
92
|
-
- `template/` 是**只读模板**;CLI 每次 `test`/`build` 会把它复制到你的项目的 `node-mobile-app-build
|
|
95
|
+
- `template/` 是**只读模板**;CLI 每次 `test`/`build` 会把它复制到你的项目的 `node-mobile-app-build/`,
|
|
96
|
+
你如手改模板内容会被覆盖
|
|
93
97
|
- 你的持久化的自定义项应写进 `mobileAppConfig.js`,或通过 `keepFiles` 保留特定模板文件
|
|
94
98
|
- `template/.watchmanconfig` 会在 `copyTemplate` 时复制到 `node-mobile-app-build/.watchmanconfig`,供 Metro 的 watchman 使用
|
|
95
99
|
|
|
@@ -119,7 +123,8 @@
|
|
|
119
123
|
|
|
120
124
|
### 允许安装脚本执行
|
|
121
125
|
|
|
122
|
-
本包在安装时可能触发某些依赖包的自动脚本(如 `postinstall` 等);如果你的 npm 全局配置或项目配置禁止了脚本执行(例如设置了
|
|
126
|
+
本包在安装时可能触发某些依赖包的自动脚本(如 `postinstall` 等);如果你的 npm 全局配置或项目配置禁止了脚本执行(例如设置了
|
|
127
|
+
`ignore-scripts=true`),可能会导致安装不完整或运行时异常;
|
|
123
128
|
|
|
124
129
|
推荐在项目根目录的 `package.json` 中添加 `allowScripts` 字段,显式放行本包及其依赖的脚本:
|
|
125
130
|
|
|
@@ -160,23 +165,27 @@ npx node-mobile-app build --release
|
|
|
160
165
|
|
|
161
166
|
## 命令说明
|
|
162
167
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
168
|
+
- `npx node-mobile-app test`
|
|
169
|
+
- 编译并安装到设备(**需连 USB**);自动启动 Metro 并后台常驻,支持热更新;设备已装包签名不一致时自动卸载
|
|
170
|
+
- `npx node-mobile-app test --ios`
|
|
171
|
+
- iOS 版(仅 macOS)
|
|
172
|
+
- `npx node-mobile-app build`
|
|
173
|
+
- 打 debug APK(**离线可用**)
|
|
174
|
+
- `npx node-mobile-app build --release`
|
|
175
|
+
- 打 release APK(默认用 debug keystore 签名,可安装;上架需配置 `android.signing`)
|
|
176
|
+
- `npx node-mobile-app build --ios`
|
|
177
|
+
- 打 IPA(仅 macOS)
|
|
178
|
+
- `npx node-mobile-app clean`
|
|
179
|
+
- 清理构建缓存
|
|
171
180
|
|
|
172
181
|
### 常用选项
|
|
173
182
|
|
|
174
|
-
| 选项 | 用途
|
|
175
|
-
| --------------- |
|
|
176
|
-
| `--ios` | 目标平台为 iOS(默认 Android)
|
|
177
|
-
| `--release` | 打 release 包(仅 `build`)
|
|
178
|
-
| `--device <id>` | 指定设备(`test`)
|
|
179
|
-
| `--arch <abi>` | 指定 ABI,逗号分隔(`build`,仅 Android)
|
|
183
|
+
| 选项 | 用途 |
|
|
184
|
+
| --------------- | ------------------------------------------- |
|
|
185
|
+
| `--ios` | 目标平台为 iOS(默认 Android) |
|
|
186
|
+
| `--release` | 打 release 包(仅 `build`) |
|
|
187
|
+
| `--device <id>` | 指定设备(`test`) |
|
|
188
|
+
| `--arch <abi>` | 指定 ABI,逗号分隔(`build`,仅 Android) |
|
|
180
189
|
| `--debug` | 显示详细日志(优化各阶段明细,各命令完整输出) |
|
|
181
190
|
|
|
182
191
|
### 安装 APK 到手机
|
|
@@ -210,7 +219,9 @@ adb install -r "./out/myapp-1.0.0-release.apk"
|
|
|
210
219
|
|
|
211
220
|
**说明**:
|
|
212
221
|
- `-r` = 覆盖安装(保留应用数据)
|
|
213
|
-
- **签名不同的包不能互相覆盖**:`build` 的 release 包用 `android.signing` 的 keystore 签名,`test` / `build` 的 debug
|
|
222
|
+
- **签名不同的包不能互相覆盖**:`build` 的 release 包用 `android.signing` 的 keystore 签名,`test` / `build` 的 debug
|
|
223
|
+
包用模板自带 debug keystore 签名;两者包名相同但签名不同,直接 `install -r` 会报
|
|
224
|
+
`INSTALL_FAILED_UPDATE_INCOMPATIBLE: signatures do not match`;需先执行 `adb uninstall <appId>` 再安装(会清除应用数据)
|
|
214
225
|
- `adb` 找不到?在 `mobileAppConfig.js` 里配 `android.adbPath`
|
|
215
226
|
- `test` 命令已自动处理签名冲突并安装,无需手动
|
|
216
227
|
|
|
@@ -218,11 +229,18 @@ adb install -r "./out/myapp-1.0.0-release.apk"
|
|
|
218
229
|
|
|
219
230
|
## 自动化机制
|
|
220
231
|
|
|
221
|
-
- **快照双哈希**:`.deps-snapshot.json` 记录 `optimizeHash`(`optimize-node-modules.js` 内容哈希)与
|
|
222
|
-
|
|
223
|
-
-
|
|
224
|
-
|
|
225
|
-
|
|
232
|
+
- **快照双哈希**:`.deps-snapshot.json` 记录 `optimizeHash`(`optimize-node-modules.js` 内容哈希)与
|
|
233
|
+
`installerHash`(`install.js` 内容哈希);任一变化即触发重装、重编、重优化,避免流程代码更新后仍复用旧缓存;
|
|
234
|
+
- **bundle 变化失效 Gradle 缓存**:`test` 生成 JS bundle 后,与
|
|
235
|
+
`android/app/build/intermediates/assets/debug/mergeDebugAssets/` 中的合并结果比对 SHA256;不一致时删除合并目录,强制
|
|
236
|
+
Gradle 重新合并;一致时保持 UP-TO-DATE;
|
|
237
|
+
- **编译前执行 `patch-package.js`**:把原生模块 `package.json` 中的 `node-gyp-build` 替换为 `node-gyp-build-mobile`,
|
|
238
|
+
使编译走 `@flun/nodejs-mobile-gyp` 而非 npm 自带的 `node-gyp`;
|
|
239
|
+
- **Metro 生命周期**:`test` 执行前检测 `localhost:8081/status`;未运行则以 detached 方式启动 `react-native start`(日志写入
|
|
240
|
+
`node-mobile-app-build/.metro.log`),就绪后继续;`run-android` 加 `--no-packager`,命令结束后 Metro 保持运行;30
|
|
241
|
+
秒未就绪打印警告并回落到 APK 内置 bundle;
|
|
242
|
+
- **输出分级**:步骤标题 0 空格,动作与状态 2 空格,结果与完成 4 空格,子项详情 8 空格;优化阶段作为步骤子项,阶段标题 4 空格、
|
|
243
|
+
阶段结果 6 空格;
|
|
226
244
|
- **精简与详细双模式**:默认只输出关键行与结果,`--debug` 或 `OPTIMIZE_DEBUG=1` 时全量输出(含 Gradle 与 Metro 完整日志);
|
|
227
245
|
|
|
228
246
|
## 配置文件 `mobileAppConfig.js`
|
|
@@ -231,52 +249,109 @@ adb install -r "./out/myapp-1.0.0-release.apk"
|
|
|
231
249
|
|
|
232
250
|
### 必填
|
|
233
251
|
|
|
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
|
-
|
|
252
|
+
- `appName`
|
|
253
|
+
- 类型:`string \| null`
|
|
254
|
+
- 默认:`null`
|
|
255
|
+
- 说明:应用显示名称(默认从 `package.json` 的 `name` 读)
|
|
256
|
+
- `outputDir`
|
|
257
|
+
- 类型:`string \| null`
|
|
258
|
+
- 默认:`null`
|
|
259
|
+
- 说明:APK / IPA 输出目录(默认 `./out`)
|
|
260
|
+
- `showLoading`
|
|
261
|
+
- 类型:`boolean`
|
|
262
|
+
- 默认:`true`
|
|
263
|
+
- 说明:是否显示加载指示器
|
|
264
|
+
- `loadingText`
|
|
265
|
+
- 类型:`string`
|
|
266
|
+
- 默认:`'正在启动服务...'`
|
|
267
|
+
- 说明:加载提示文字
|
|
268
|
+
- `enableJavaScript`
|
|
269
|
+
- 类型:`boolean`
|
|
270
|
+
- 默认:`true`
|
|
271
|
+
- 说明:是否启用 JavaScript
|
|
272
|
+
- `enableDomStorage`
|
|
273
|
+
- 类型:`boolean`
|
|
274
|
+
- 默认:`true`
|
|
275
|
+
- 说明:是否启用 DOM Storage
|
|
276
|
+
- `allowFileAccess`
|
|
277
|
+
- 类型:`boolean`
|
|
278
|
+
- 默认:`true`
|
|
279
|
+
- 说明:是否允许访问本地文件
|
|
280
|
+
- `mixedContentMode`
|
|
281
|
+
- 类型:`string`
|
|
282
|
+
- 默认:`'always'`
|
|
283
|
+
- 说明:混合内容模式:`never` / `always` / `compatibility`
|
|
284
|
+
- `backgroundColor`
|
|
285
|
+
- 类型:见下
|
|
286
|
+
- 默认:`'#ffffff'`
|
|
287
|
+
- 说明:WebView 背景色;支持:固定色 `'#ffffff'` / 跟随系统 `'system'` / 深浅两值 `{ light, dark }`
|
|
288
|
+
- `allowSelfSignedCert`
|
|
289
|
+
- 类型:`boolean`
|
|
290
|
+
- 默认:`false`
|
|
291
|
+
- 说明:见下文"HTTPS 自签证书"
|
|
260
292
|
|
|
261
293
|
### Android
|
|
262
294
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
295
|
+
- `sdkPath`
|
|
296
|
+
- 类型:`string \| null`
|
|
297
|
+
- 默认:`null`
|
|
298
|
+
- 说明:Android SDK 路径(默认自动查找)
|
|
299
|
+
- `adbPath`
|
|
300
|
+
- 类型:`string \| null`
|
|
301
|
+
- 默认:`null`
|
|
302
|
+
- 说明:adb 路径(默认自动查找)
|
|
303
|
+
- `minSdkVersion`
|
|
304
|
+
- 类型:`int`
|
|
305
|
+
- 默认:`29`
|
|
306
|
+
- 说明:最低 SDK(29=Android 10.0)
|
|
307
|
+
- `targetSdkVersion`
|
|
308
|
+
- 类型:`int`
|
|
309
|
+
- 默认:`36`
|
|
310
|
+
- 说明:目标 SDK
|
|
311
|
+
- `compileSdkVersion`
|
|
312
|
+
- 类型:`int`
|
|
313
|
+
- 默认:`37`
|
|
314
|
+
- 说明:编译 SDK
|
|
315
|
+
- `buildToolsVersion`
|
|
316
|
+
- 类型:`string`
|
|
317
|
+
- 默认:`'37.0.0'`
|
|
318
|
+
- 说明:构建工具版本
|
|
319
|
+
- `abiFilters`
|
|
320
|
+
- 类型:`string[]`
|
|
321
|
+
- 默认:`['arm64-v8a']`
|
|
322
|
+
- 说明:打包架构(真机 `arm64-v8a`,模拟器加 `x86_64`)
|
|
323
|
+
- `icon`
|
|
324
|
+
- 类型:`string`
|
|
325
|
+
- 默认:`'./build/icon.png'`
|
|
326
|
+
- 说明:应用图标(建议 512×512 PNG)
|
|
327
|
+
- `usesCleartextTraffic`
|
|
328
|
+
- 类型:`boolean`
|
|
329
|
+
- 默认:`true`
|
|
330
|
+
- 说明:是否允许明文 HTTP
|
|
331
|
+
- `permissions`
|
|
332
|
+
- 类型:`string[]`
|
|
333
|
+
- 默认:`[]`
|
|
334
|
+
- 说明:额外权限(如 `'android.permission.CAMERA'`)
|
|
335
|
+
- `signing`
|
|
336
|
+
- 类型:`object`
|
|
337
|
+
- 默认:-
|
|
338
|
+
- 说明:自定义签名配置.**不填则用模板自带的 debug keystore 签名**(可安装测试,不可上架);填则以下 4 项均为必填
|
|
339
|
+
- `signing.keystore`
|
|
340
|
+
- 类型:`string`
|
|
341
|
+
- 默认:-
|
|
342
|
+
- 说明:keystore 路径(相对你的项目根)
|
|
343
|
+
- `signing.storePassword`
|
|
344
|
+
- 类型:`string`
|
|
345
|
+
- 默认:-
|
|
346
|
+
- 说明:keystore 密码
|
|
347
|
+
- `signing.keyAlias`
|
|
348
|
+
- 类型:`string`
|
|
349
|
+
- 默认:-
|
|
350
|
+
- 说明:密钥别名
|
|
351
|
+
- `signing.keyPassword`
|
|
352
|
+
- 类型:`string`
|
|
353
|
+
- 默认:-
|
|
354
|
+
- 说明:密钥密码(通常与 `storePassword` 相同)
|
|
280
355
|
|
|
281
356
|
#### 生成自签名 keystore
|
|
282
357
|
|
|
@@ -316,59 +391,65 @@ signing: {
|
|
|
316
391
|
},
|
|
317
392
|
```
|
|
318
393
|
|
|
319
|
-
> **提示**:`storepass` / `keypass` 可填相同值,对应配置里 `storePassword` / `keyPassword`
|
|
394
|
+
> **提示**:`storepass` / `keypass` 可填相同值,对应配置里 `storePassword` / `keyPassword` 也填相同值.四项缺一不可,
|
|
395
|
+
缺项时构建前会报错.
|
|
320
396
|
|
|
321
397
|
### iOS
|
|
322
398
|
|
|
323
|
-
| 字段 | 类型 | 默认 | 说明
|
|
324
|
-
| ----------------------------- | -------- | -------------------- |
|
|
325
|
-
| `deploymentTarget` | `string` | `'15.1'` | 最低 iOS 版本
|
|
399
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
400
|
+
| ----------------------------- | -------- | -------------------- | ---------------------------------------------------- |
|
|
401
|
+
| `deploymentTarget` | `string` | `'15.1'` | 最低 iOS 版本 |
|
|
326
402
|
| `icon` | `string` | `'./build/icon.png'` | 应用图标(建议 1024×1024 PNG) |
|
|
327
|
-
| `signing.teamId` | `string` | - | Apple Developer Team ID
|
|
403
|
+
| `signing.teamId` | `string` | - | Apple Developer Team ID |
|
|
328
404
|
| `signing.provisioningProfile` | `string` | - | 描述文件路径(写入 `exportOptions.plist`) |
|
|
329
405
|
| `signing.certificate` | `string` | - | P12 证书路径(导入临时 keychain 供 xcodebuild 签名用) |
|
|
330
|
-
| `signing.certificatePassword` | `string` | - | P12 密码
|
|
406
|
+
| `signing.certificatePassword` | `string` | - | P12 密码 |
|
|
331
407
|
|
|
332
408
|
### 高级
|
|
333
409
|
|
|
334
410
|
| 字段 | 类型 | 默认 | 说明 |
|
|
335
411
|
| ---------------------------- | --------- | ------ | -------------------------- |
|
|
336
412
|
| `advanced.keepAlive` | `boolean` | `true` | 是否发送心跳保持 Node 进程 |
|
|
337
|
-
| `advanced.heartbeatInterval` | `int` | `5000` | 心跳间隔(毫秒)
|
|
413
|
+
| `advanced.heartbeatInterval` | `int` | `5000` | 心跳间隔(毫秒) |
|
|
338
414
|
|
|
339
415
|
### 扩展点
|
|
340
416
|
|
|
341
|
-
| 字段 | 类型 | 默认 | 说明
|
|
342
|
-
| --------------------- | ---------- | ---- |
|
|
417
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
418
|
+
| --------------------- | ---------- | ---- | --------------------------------------------------- |
|
|
343
419
|
| `keepFiles` | `string[]` | `[]` | 不重置的模板文件(路径相对 `node-mobile-app-build/`) |
|
|
344
420
|
| `extraRnDependencies` | `string[]` | `[]` | 额外 RN 原生依赖包名(需先安装在你的开发字段中) |
|
|
345
421
|
|
|
346
422
|
### 排除 / 白名单
|
|
347
423
|
|
|
348
|
-
| 字段 | 说明
|
|
349
|
-
| -------------- |
|
|
350
|
-
| `excludeFiles` | 复制到 build 目录时跳过的文件/目录(支持 `*.log`,`build/` 等)
|
|
424
|
+
| 字段 | 说明 |
|
|
425
|
+
| -------------- | -------------------------------------------------------------------------- |
|
|
426
|
+
| `excludeFiles` | 复制到 build 目录时跳过的文件/目录(支持 `*.log`,`build/` 等) |
|
|
351
427
|
| `allowScripts` | 移动端 Node 环境里允许跑安装脚本的包(会写入 `nodejs-project/package.json`) |
|
|
352
428
|
|
|
353
429
|
### node_modules 优化
|
|
354
430
|
|
|
355
431
|
构建时自动优化 `node_modules`(默认开启,无需配置),减少打包文件数与体积,加速启动.
|
|
356
432
|
|
|
357
|
-
| 字段 | 类型 | 默认 | 说明
|
|
358
|
-
| --------- | ---------- | ------ |
|
|
359
|
-
| `enabled` | `boolean` | `true` | 是否启用优化
|
|
433
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
434
|
+
| --------- | ---------- | ------ | --------------------------------------------------------- |
|
|
435
|
+
| `enabled` | `boolean` | `true` | 是否启用优化 |
|
|
360
436
|
| `exclude` | `string[]` | `[]` | 排除优化时异常或不想优化的包(写 `package.json` 的 `name`) |
|
|
361
437
|
|
|
362
438
|
**编译与优化顺序**:先交叉编译原生模块(见 `install.js`),再执行以下六阶段优化:
|
|
363
439
|
|
|
364
440
|
1. **清空资源**:扫描各包 `postinstall` 引用的目录/文件,保留目录结构,清空内容;js 文件一律保留,留待合并阶段处理;
|
|
365
|
-
2. **合并 JS**:按包入口 bundle,多个 JS 文件合并为单文件(`bundled/` 目录);合并后同步删除 `package.json` 的 `scripts`
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
441
|
+
2. **合并 JS**:按包入口 bundle,多个 JS 文件合并为单文件(`bundled/` 目录);合并后同步删除 `package.json` 的 `scripts`
|
|
442
|
+
字段(运行时无安装期,且 Gradle `npm rebuild` 会触发脚本导致失败);
|
|
443
|
+
3. **清平台二进制**:按目标平台 + `abiFilters` 判定;`prebuilds/<platform>-<arch>` 按目录整体处理--Android 只保留 `android`,
|
|
444
|
+
`linux` / `darwin` / `win32` 删除;iOS 只保留 `darwin`;其余二进制逐文件按文件头判定;
|
|
445
|
+
4. **清开发文件与编译源文件**:删除 `.md` / `.map` / `.d.ts` / `.h` / `.c` / `.cc` / `.cpp` / `.cxx` 等非运行文件;
|
|
446
|
+
原生模块已在优化前完成编译,编译源文件无需保留;
|
|
447
|
+
5. **清 node-gyp 中间产物**:删除 `build/Release/obj.target/` 下的中间副本,以及 `.o` / `.d` / `.mk` / `.stamp` / `Makefile`
|
|
448
|
+
等编译中间文件;
|
|
369
449
|
6. **清不参与运行的文件和空目录**.
|
|
370
450
|
|
|
371
|
-
**缓存**:快照记录在 `node-mobile-app-build/.deps-snapshot.json`,构建时自动判断"重装并优化 / 仅优化 / 跳过"
|
|
451
|
+
**缓存**:快照记录在 `node-mobile-app-build/.deps-snapshot.json`,构建时自动判断"重装并优化 / 仅优化 / 跳过";
|
|
452
|
+
改动模板或依赖会自动触发重编.
|
|
372
453
|
|
|
373
454
|
**异常排查**:
|
|
374
455
|
|
|
@@ -378,7 +459,8 @@ signing: {
|
|
|
378
459
|
|
|
379
460
|
## 服务地址说明
|
|
380
461
|
|
|
381
|
-
CLI **自动识别 `server.js` 实际监听的协议和端口**--拦截 `net.Server.prototype.listen`,从 `server.address()` 取真实端口,从
|
|
462
|
+
CLI **自动识别 `server.js` 实际监听的协议和端口**--拦截 `net.Server.prototype.listen`,从 `server.address()` 取真实端口,从
|
|
463
|
+
`Server` 类型判断 `http` / `https`;
|
|
382
464
|
|
|
383
465
|
因此 `mobileAppConfig.js` **不需要**配置端口/协议;动态端口(`listen(0)`)会拿到系统分配的真实端口;
|
|
384
466
|
|
|
@@ -394,11 +476,11 @@ CLI **自动识别 `server.js` 实际监听的协议和端口**--拦截 `net.Ser
|
|
|
394
476
|
|
|
395
477
|
`webview.allowSelfSignedCert` 控制是否放行**不受信任的 HTTPS 证书**:
|
|
396
478
|
|
|
397
|
-
| 场景
|
|
398
|
-
|
|
|
399
|
-
| HTTP
|
|
479
|
+
| 场景 | 是否受开关影响 |
|
|
480
|
+
| ------------------------------------------- | ------------------- |
|
|
481
|
+
| HTTP | 无关 |
|
|
400
482
|
| HTTPS + 真证书(Let's Encrypt 等) | 无关 |
|
|
401
|
-
| HTTPS + 自签证书 + 已装进设备信任库
|
|
483
|
+
| HTTPS + 自签证书 + 已装进设备信任库 | 无关 |
|
|
402
484
|
| HTTPS + 自签证书 + 未装设备(本地测试最常见) | **必须设为 `true`** |
|
|
403
485
|
|
|
404
486
|
**实现方式**:
|
|
@@ -417,10 +499,12 @@ CLI **自动识别 `server.js` 实际监听的协议和端口**--拦截 `net.Ser
|
|
|
417
499
|
| 运行时版本 | 官方提供多个版本,可用 `NODE_MOBILE_PREBUILT_VERSION` 切换 | **当前为 v18.20.4**,更高版本后续逐步适配 |
|
|
418
500
|
| Express 版本 | 产物带 full-icu,4.x / 5.x 均可用 | 当前产物不带 full-icu,**必须用 4.x** |
|
|
419
501
|
| full-icu | 自 v22.23.2 产物起支持 | 暂无 |
|
|
420
|
-
| `test` 离线 | ✓(内置 bundle)
|
|
421
|
-
| 图标尺寸 | 5 个密度(48~192)
|
|
502
|
+
| `test` 离线 | ✓(内置 bundle) | ✓(需 `FORCE_BUNDLING=1`) |
|
|
503
|
+
| 图标尺寸 | 5 个密度(48~192) | 9 个尺寸(40~1024) |
|
|
422
504
|
|
|
423
|
-
**iOS 运行时版本**:iOS 附件的实际运行时版本随适配进度变化,**当前对应 v18.20.4**;如需更高版本,可克隆 [nodejs-mobile
|
|
505
|
+
**iOS 运行时版本**:iOS 附件的实际运行时版本随适配进度变化,**当前对应 v18.20.4**;如需更高版本,可克隆 [nodejs-mobile
|
|
506
|
+
仓库](https://github.com/OpenFlun/nodejs-mobile) 自行编译 `NodeMobile.xcframework`,流程与 Android 自编译 `libnode.so`
|
|
507
|
+
类似(见 `自定义libnode指南.md`);
|
|
424
508
|
|
|
425
509
|
---
|
|
426
510
|
|
|
@@ -456,7 +540,9 @@ CLI **自动识别 `server.js` 实际监听的协议和端口**--拦截 `net.Ser
|
|
|
456
540
|
|
|
457
541
|
### Q:`test` 拔掉 USB 后 App 加载慢?
|
|
458
542
|
|
|
459
|
-
`test` 打的是 debug 版,启动时优先连 Metro;CLI 会在 `[9/11]` 自动启动 Metro 并保持后台常驻,但设备通过 `adb reverse` 访问
|
|
543
|
+
`test` 打的是 debug 版,启动时优先连 Metro;CLI 会在 `[9/11]` 自动启动 Metro 并保持后台常驻,但设备通过 `adb reverse` 访问
|
|
544
|
+
`localhost:8081`,**拔掉 USB 后端口转发失效**,设备连不上 Metro,debug 包等待超时后才回落到 APK 内置的 bundle;这个"等超时"是
|
|
545
|
+
RN debug 版的固有行为;
|
|
460
546
|
|
|
461
547
|
拔线后的启动速度(从快到慢):
|
|
462
548
|
|
|
@@ -464,11 +550,13 @@ CLI **自动识别 `server.js` 实际监听的协议和端口**--拦截 `net.Ser
|
|
|
464
550
|
2. **`npx node-mobile-app build`** 打包后安装到手机--次之(debug 版,会先尝试连 Metro 再回退)
|
|
465
551
|
3. **`npx node-mobile-app test`** 后手动打开应用--最慢(同上,且 `test` 面向"连 USB 热更新"场景)
|
|
466
552
|
|
|
467
|
-
若需要**热更新**,保持 USB 连接(维持 `adb reverse` 的端口转发);不需要热更新时,用 `build --release` 打包可避免等待 Metro
|
|
553
|
+
若需要**热更新**,保持 USB 连接(维持 `adb reverse` 的端口转发);不需要热更新时,用 `build --release` 打包可避免等待 Metro
|
|
554
|
+
超时.
|
|
468
555
|
|
|
469
556
|
### Q:`test` 装到手机后拔 USB 就崩?
|
|
470
557
|
|
|
471
|
-
前提是 APK 里有内置 bundle;`test` 每次都会先 `react-native bundle` 打进
|
|
558
|
+
前提是 APK 里有内置 bundle;`test` 每次都会先 `react-native bundle` 打进
|
|
559
|
+
APK;**如果崩,检查 CLI 输出里 `[7/11] 生成 JS bundle(离线可用)` 是否成功**;
|
|
472
560
|
|
|
473
561
|
### Q:Node 进程启动失败怎么排查?
|
|
474
562
|
|
|
@@ -484,7 +572,8 @@ adb logcat | grep -E "NODEJS-MOBILE|ReactNativeJS"
|
|
|
484
572
|
```
|
|
485
573
|
|
|
486
574
|
### Q:`npm install` 时提示 `install-scripts not yet covered by allowScripts`?
|
|
487
|
-
这是 npm 的提醒,表示某些依赖带有 `postinstall` / `install` 脚本,尚未在 `allowScripts` 里显式放行;`@flun/node-mobile-app`
|
|
575
|
+
这是 npm 的提醒,表示某些依赖带有 `postinstall` / `install` 脚本,尚未在 `allowScripts` 里显式放行;`@flun/node-mobile-app`
|
|
576
|
+
及其依赖(`@flun/nodejs-mobile-react-native`、`esbuild` 等)需要执行这些脚本才能完整安装;
|
|
488
577
|
|
|
489
578
|
放行方式见 [允许安装脚本执行](#允许安装脚本执行):在项目根 `package.json` 中添加 `allowScripts` 字段,逐项设为 `true`;
|
|
490
579
|
|
|
@@ -492,7 +581,8 @@ adb logcat | grep -E "NODEJS-MOBILE|ReactNativeJS"
|
|
|
492
581
|
|
|
493
582
|
### Q:Android 构建卡在拉取依赖(`react-android` / `hermes-android` 等)?
|
|
494
583
|
|
|
495
|
-
Android 模板的 `settings.gradle` 与 `build.gradle` 已在 `google()` / `mavenCentral()`
|
|
584
|
+
Android 模板的 `settings.gradle` 与 `build.gradle` 已在 `google()` / `mavenCentral()` 之前插入阿里云镜像,
|
|
585
|
+
国内网络优先走镜像;海外网络镜像不命中会自动回退官方源,不影响功能.
|
|
496
586
|
|
|
497
587
|
若仍卡住:
|
|
498
588
|
|
|
@@ -509,11 +599,12 @@ Express 5 的路由语法与 4 不同(如 `app.get('*')` 要改成 `app.get('/{*
|
|
|
509
599
|
|
|
510
600
|
### Q:`libnode.so` 和 `NodeMobile.xcframework` 是怎么来的?
|
|
511
601
|
|
|
512
|
-
从 `@flun/nodejs-mobile-react-native` 1.0.1 起,两套预编译二进制**不在 npm 包里**,改为 postinstall 阶段自动从 Gitee /
|
|
602
|
+
从 `@flun/nodejs-mobile-react-native` 1.0.1 起,两套预编译二进制**不在 npm 包里**,改为 postinstall 阶段自动从 Gitee /
|
|
603
|
+
GitHub Release 下载:
|
|
513
604
|
|
|
514
|
-
| 资源
|
|
515
|
-
|
|
|
516
|
-
| `android-libnode.zip`
|
|
605
|
+
| 资源 | 目标位置 |
|
|
606
|
+
| ------------------------------ | --------------------------------------------------------------------------- |
|
|
607
|
+
| `android-libnode.zip` | `node_modules/@flun/nodejs-mobile-react-native/android/libnode/` |
|
|
517
608
|
| `ios-nodemobile.zip`(仅 macOS) | `node_modules/@flun/nodejs-mobile-react-native/ios/NodeMobile.xcframework/` |
|
|
518
609
|
|
|
519
610
|
- 默认下载版本以 `@flun/nodejs-mobile-react-native` 的 `package.json` 中 `prebuiltAssets.version` 字段为准
|
|
@@ -537,13 +628,15 @@ NODE_MOBILE_PREBUILT_IOS_SKIP=1 # 只跳过 iOS
|
|
|
537
628
|
2. 如果 `mobileAppConfig.js` 的 `android.abiFilters` 与 libnode 支持的架构不一致,同步调整
|
|
538
629
|
3. 跑 `npx node-mobile-app build` 或 `npx node-mobile-app test`
|
|
539
630
|
|
|
540
|
-
**CLI 会自动处理缓存**:指纹机制检测到 `libnode.so` 或 `abiFilters` 变化,自动清理 `.cxx` / `android/build` / `app/build
|
|
631
|
+
**CLI 会自动处理缓存**:指纹机制检测到 `libnode.so` 或 `abiFilters` 变化,自动清理 `.cxx` / `android/build` / `app/build`,
|
|
632
|
+
全量重编;**你无需手动清任何缓存**;
|
|
541
633
|
|
|
542
634
|
详细流程见 `自定义libnode指南.md`;
|
|
543
635
|
|
|
544
636
|
### Q:iOS 提示 `fallbackSourceURL does not override`?
|
|
545
637
|
|
|
546
|
-
RN 0.87 的 API 若变动,`AppDelegate.swift` 里的 fallback 可能不生效--不影响"连 Mac + Metro"正常开发,只是拔 Mac 后无法
|
|
638
|
+
RN 0.87 的 API 若变动,`AppDelegate.swift` 里的 fallback 可能不生效--不影响"连 Mac + Metro"正常开发,只是拔 Mac 后无法
|
|
639
|
+
fallback 到内置 bundle;届时反馈,我们更新适配;
|
|
547
640
|
|
|
548
641
|
---
|
|
549
642
|
|
|
@@ -556,4 +649,4 @@ RN 0.87 的 API 若变动,`AppDelegate.swift` 里的 fallback 可能不生效--
|
|
|
556
649
|
|
|
557
650
|
## 许可
|
|
558
651
|
|
|
559
|
-
ISC
|
|
652
|
+
ISC
|
package/bin/cli.js
CHANGED
|
@@ -8,17 +8,17 @@ const HELP = `
|
|
|
8
8
|
@flun/node-mobile-app
|
|
9
9
|
|
|
10
10
|
指令:
|
|
11
|
-
node-mobile-app test
|
|
12
|
-
node-mobile-app test --ios iOS
|
|
13
|
-
node-mobile-app build 打 debug APK
|
|
14
|
-
node-mobile-app build --release 打 release APK
|
|
15
|
-
node-mobile-app build --ios 打 IPA
|
|
16
|
-
node-mobile-app clean
|
|
11
|
+
node-mobile-app test 编译并安装到设备(Android,需连 USB,走 Metro 热更新)
|
|
12
|
+
node-mobile-app test --ios iOS 版(仅 macOS)
|
|
13
|
+
node-mobile-app build 打 debug APK(Android,离线可用)
|
|
14
|
+
node-mobile-app build --release 打 release APK(Android,默认 debug keystore 签名,可安装)
|
|
15
|
+
node-mobile-app build --ios 打 IPA(仅 macOS)
|
|
16
|
+
node-mobile-app clean 清理构建缓存(不限平台)
|
|
17
17
|
|
|
18
18
|
选项:
|
|
19
|
-
--device <id>
|
|
20
|
-
--arch <abi> 指定 ABI
|
|
21
|
-
--debug
|
|
19
|
+
--device <id> 指定设备(仅 test)
|
|
20
|
+
--arch <abi> 指定 ABI,逗号分隔(仅 build,Android)
|
|
21
|
+
--debug 显示详细日志(所有指令通用)
|
|
22
22
|
`,
|
|
23
23
|
|
|
24
24
|
parseFlags = args => {
|
package/cli-assets/server.js
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
// ============================================================
|
|
2
|
-
// 这是 @flun/node-mobile-app
|
|
3
|
-
// 请替换为你自己的 Node.js
|
|
2
|
+
// 这是 @flun/node-mobile-app 自动生成的默认入口脚本;
|
|
3
|
+
// 请替换为你自己的 Node.js 启动脚本;
|
|
4
4
|
//
|
|
5
|
-
//
|
|
5
|
+
// 你可以:
|
|
6
6
|
// 1. 直接修改这个文件
|
|
7
7
|
// 2. 或用 mobileAppConfig.js 里的 serverPath 指向你自己的入口文件
|
|
8
8
|
// ============================================================
|
|
@@ -17,7 +17,10 @@ const PORT = 3000,
|
|
|
17
17
|
<title>Node Mobile App</title>
|
|
18
18
|
<style>
|
|
19
19
|
html,body{height:100%;margin:0;padding:0}
|
|
20
|
-
body{display:flex;flex-direction:column;justify-content:center;align-items:center;
|
|
20
|
+
body{display:flex;flex-direction:column;justify-content:center;align-items:center;
|
|
21
|
+
min-height:100vh;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;
|
|
22
|
+
background:linear-gradient(135deg,#667eea 0%,#764ba2 100%);
|
|
23
|
+
color:#fff;text-align:center;padding:24px;box-sizing:border-box}
|
|
21
24
|
h1{margin:0 0 16px;font-size:28px;font-weight:600;letter-spacing:.5px}
|
|
22
25
|
p{margin:0;font-size:16px;opacity:.9;line-height:1.5}
|
|
23
26
|
.hint{margin-top:32px;font-size:13px;opacity:.65}
|