@flun/node-mobile-app 2.0.3 → 2.0.5
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 +9 -2
- package/README.md +111 -114
- package/cli-assets/server.js +1 -1
- package/package.json +3 -3
- package/scripts/copy-files.js +22 -23
- package/src/generate.js +3 -3
- package/src/install.js +6 -17
- package/src/patcher.js +2 -2
- package/src/platform-ios.js +1 -1
- package/src/utils.js +1 -1
- package/template/metro.config.js +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,7 +1,14 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 变更日志
|
|
2
|
+
## [2.0.5] - 2026-09-28 11:50
|
|
3
|
+
### 优化
|
|
4
|
+
优化了部分细节;
|
|
2
5
|
|
|
3
|
-
## [2.0.
|
|
6
|
+
## [2.0.4] - 2026-09-27 21:50
|
|
7
|
+
### 更新
|
|
8
|
+
- 依赖包 '@flun/nodejs-mobile-react-native' 更新为 v2.0.2;
|
|
9
|
+
- 优化了 'README.md' 和 'server.js' 一些细节;
|
|
4
10
|
|
|
11
|
+
## [2.0.3] - 2026-09-25 21:33
|
|
5
12
|
### 修复
|
|
6
13
|
|
|
7
14
|
- **`template/metro.config.js` 排除配置更新**：原来的 `blacklistRE` 在 Metro 0.86+ 已完全移除，`metro-config/src/defaults/exclusionList.js` 的深层导入路径在 Metro 0.83 起也不再暴露，会导致新版本 RN 项目加载 Metro 配置失败。改为：
|
package/README.md
CHANGED
|
@@ -1,35 +1,36 @@
|
|
|
1
1
|
# @flun/node-mobile-app
|
|
2
2
|
|
|
3
|
-
将 Node.js 项目一键打包为 Android / iOS
|
|
3
|
+
将 Node.js 项目一键打包为 Android / iOS 移动应用;运行时由 @flun/nodejs-mobile-react-native 提供,无需修改你的 Node 代码;
|
|
4
4
|
|
|
5
|
-
**核心理念**：你的的 Node
|
|
5
|
+
**核心理念**：你的的 Node 项目保持不变,CLI 负责搬运、编译、打包;所有定制集中在 `mobileAppConfig.js` 一个文件;
|
|
6
6
|
|
|
7
7
|
- GitHub：https://github.com/OpenFlun/node-mobile-app
|
|
8
|
-
- Gitee
|
|
8
|
+
- Gitee（中国）：https://gitee.com/OpenFlun/node-mobile-app
|
|
9
9
|
|
|
10
10
|
---
|
|
11
11
|
|
|
12
12
|
## 特性
|
|
13
13
|
|
|
14
|
-
- **零侵入**：Node
|
|
15
|
-
- **自动识别服务地址**：拦截 `server.js` 里的 `listen()`
|
|
16
|
-
- **失败可见**：5
|
|
17
|
-
-
|
|
14
|
+
- **零侵入**：Node 项目源码、依赖、配置都不动,CLI 在独立目录里完成构建
|
|
15
|
+
- **自动识别服务地址**：拦截 `server.js` 里的 `listen()` 调用,动态获取真实协议和端口
|
|
16
|
+
- **失败可见**：5 秒内未启动、加载异常,App 显示错误页并支持展开详情（开发者可查）
|
|
17
|
+
- **增量构建**：文件指纹判断缓存,无变化时 10 秒级重跑
|
|
18
18
|
- **跨平台**：Android（Windows / macOS / Linux）+ iOS（仅 macOS）
|
|
19
|
-
- **离线可用**：`build` 打出的 APK / IPA 内置 JS
|
|
19
|
+
- **离线可用**：`build` 打出的 APK / IPA 内置 JS,无需连电脑也能跑
|
|
20
20
|
|
|
21
21
|
---
|
|
22
22
|
|
|
23
|
-
## 环境要求
|
|
23
|
+
## 环境要求(最低)
|
|
24
24
|
|
|
25
25
|
| 项 | 要求 |
|
|
26
26
|
| ------------ | ------------------------------------------------------------------- |
|
|
27
|
-
| Node.js |
|
|
27
|
+
| Node.js | 需满足 `package.json` 的 `engines.node` 字段 |
|
|
28
28
|
| Android 构建 | JDK **17**、Android SDK（minSdk 29 / targetSdk 36 / compileSdk 37） |
|
|
29
|
-
| iOS 构建 | macOS + Xcode + CocoaPods
|
|
29
|
+
| iOS 构建 | macOS + 完整 Xcode + CocoaPods |
|
|
30
30
|
| 可选 | watchman（提升 Metro 文件监听性能） |
|
|
31
|
+
| Windows 额外 | Visual Studio + Git for Windows（仅编译原生模块时需要,见下方说明） |
|
|
31
32
|
|
|
32
|
-
**JDK 必须是 17
|
|
33
|
+
**JDK 必须是 17**,Android Gradle Plugin 目前不支持更高版本;
|
|
33
34
|
|
|
34
35
|
---
|
|
35
36
|
|
|
@@ -63,9 +64,6 @@
|
|
|
63
64
|
├── template/ # RN 工程模板（运行时复制到你的项目的 node-mobile-app-build/）
|
|
64
65
|
│ ├── android/ # Android 原生工程
|
|
65
66
|
│ ├── ios/ # iOS 原生工程
|
|
66
|
-
│ ├── @types/
|
|
67
|
-
│ │ └── nodejs-mobile-react-native/
|
|
68
|
-
│ │ └── index.d.ts # nodejs-mobile 类型声明
|
|
69
67
|
│ ├── App.tsx # RN 主界面（WebView + Node 桥接 + 错误页）
|
|
70
68
|
│ ├── index.js # RN 入口（注册根组件）
|
|
71
69
|
│ ├── app.json # RN 应用名（CLI 会覆盖）
|
|
@@ -87,13 +85,13 @@
|
|
|
87
85
|
```
|
|
88
86
|
|
|
89
87
|
**关键约定**：
|
|
90
|
-
- `template/`
|
|
91
|
-
- 你的持久化的自定义项应写进 `mobileAppConfig.js
|
|
92
|
-
- `template/.watchmanconfig` 会在 `copyTemplate` 时复制到 `node-mobile-app-build/.watchmanconfig
|
|
88
|
+
- `template/` 是**只读模板**;CLI 每次 `test`/`build` 会把它复制到你的项目的 `node-mobile-app-build/`,你的如手改模板内容会被覆盖
|
|
89
|
+
- 你的持久化的自定义项应写进 `mobileAppConfig.js`,或通过 `keepFiles` 保留特定模板文件
|
|
90
|
+
- `template/.watchmanconfig` 会在 `copyTemplate` 时复制到 `node-mobile-app-build/.watchmanconfig`,供 Metro 的 watchman 使用
|
|
93
91
|
|
|
94
92
|
### .watchmanconfig 说明
|
|
95
93
|
|
|
96
|
-
|
|
94
|
+
位于包根目录,配置 watchman 的文件监控行为：
|
|
97
95
|
|
|
98
96
|
```json
|
|
99
97
|
{
|
|
@@ -108,8 +106,8 @@
|
|
|
108
106
|
}
|
|
109
107
|
```
|
|
110
108
|
|
|
111
|
-
- **`ignore_dirs`**：排除的目录（构建产物、缓存、IDE
|
|
112
|
-
- **`settle
|
|
109
|
+
- **`ignore_dirs`**：排除的目录（构建产物、缓存、IDE 配置）;**不要排除 `node_modules`**,Metro 需要监控它来解析依赖
|
|
110
|
+
- **`settle`**：防抖延迟（毫秒）,短时间内多次文件变更只触发一次重编
|
|
113
111
|
- 改完后需 `watchman watch-del-all && watchman shutdown-server` 才生效
|
|
114
112
|
|
|
115
113
|
---
|
|
@@ -130,26 +128,23 @@
|
|
|
130
128
|
}
|
|
131
129
|
```
|
|
132
130
|
|
|
133
|
-
> 如果你信任所有安装包,也可以直接在项目 `.npmrc` 中设置 `allow-scripts = false`（表示关闭脚本拦截,所有脚本均允许执行）,或删除 `ignore-script`字段;
|
|
134
|
-
|
|
135
131
|
---
|
|
136
|
-
|
|
137
132
|
## 安装
|
|
138
133
|
|
|
139
134
|
```bash
|
|
140
135
|
npm i -D @flun/node-mobile-app
|
|
141
136
|
```
|
|
142
137
|
|
|
143
|
-
|
|
138
|
+
安装完成后,会在你的项目根目录自动生成 `mobileAppConfig.js`（配置文件模板）;
|
|
144
139
|
---
|
|
145
140
|
|
|
146
141
|
## 快速开始
|
|
147
142
|
|
|
148
143
|
```bash
|
|
149
144
|
# 1. 编辑配置
|
|
150
|
-
# 打开 mobileAppConfig.js
|
|
145
|
+
# 打开 mobileAppConfig.js,改 appId / appName / serverPath 等
|
|
151
146
|
|
|
152
|
-
# 2. 开发调试（需连 USB
|
|
147
|
+
# 2. 开发调试（需连 USB,走 Metro 热更新,如需用模拟器请在 mobileAppConfig.js文件中显式配置）
|
|
153
148
|
npx node-mobile-app test
|
|
154
149
|
|
|
155
150
|
# 3. 打包发布
|
|
@@ -160,27 +155,27 @@ npx node-mobile-app build --release
|
|
|
160
155
|
|
|
161
156
|
## 命令说明
|
|
162
157
|
|
|
163
|
-
| 命令 | 用途
|
|
164
|
-
| ------------------------------------- |
|
|
165
|
-
| `npx node-mobile-app test` | 编译并安装到设备（**需连 USB
|
|
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
|
|
169
|
-
| `npx node-mobile-app build --ios` | 打 IPA（仅 macOS）
|
|
170
|
-
| `npx node-mobile-app clean` | 清理构建缓存
|
|
158
|
+
| 命令 | 用途 |
|
|
159
|
+
| ------------------------------------- | --------------------------------------------------------------------------------- |
|
|
160
|
+
| `npx node-mobile-app test` | 编译并安装到设备（**需连 USB**,走 Metro 热更新） |
|
|
161
|
+
| `npx node-mobile-app test --ios` | iOS 版（仅 macOS） |
|
|
162
|
+
| `npx node-mobile-app build` | 打 debug APK（**离线可用**） |
|
|
163
|
+
| `npx node-mobile-app build --release` | 打 release APK（默认用 debug keystore 签名,可安装；上架需配置 `android.signing`） |
|
|
164
|
+
| `npx node-mobile-app build --ios` | 打 IPA（仅 macOS） |
|
|
165
|
+
| `npx node-mobile-app clean` | 清理构建缓存 |
|
|
171
166
|
|
|
172
167
|
### 常用选项
|
|
173
168
|
|
|
174
|
-
| 选项 | 用途
|
|
175
|
-
| --------------- |
|
|
176
|
-
| `--ios` | 目标平台为 iOS（默认 Android）
|
|
177
|
-
| `--release` | 打 release 包（仅 `build`）
|
|
178
|
-
| `--device <id>` | 指定设备（`test`）
|
|
179
|
-
| `--arch <abi>` | 指定 ABI
|
|
169
|
+
| 选项 | 用途 |
|
|
170
|
+
| --------------- | --------------------------------------- |
|
|
171
|
+
| `--ios` | 目标平台为 iOS（默认 Android） |
|
|
172
|
+
| `--release` | 打 release 包（仅 `build`） |
|
|
173
|
+
| `--device <id>` | 指定设备（`test`） |
|
|
174
|
+
| `--arch <abi>` | 指定 ABI,逗号分隔（`build`,仅 Android） |
|
|
180
175
|
|
|
181
176
|
### 安装 APK 到手机
|
|
182
177
|
|
|
183
|
-
`build` 打出的 APK 在 `outputDir`（默认 `./out
|
|
178
|
+
`build` 打出的 APK 在 `outputDir`（默认 `./out/`）里;手动装到手机：
|
|
184
179
|
|
|
185
180
|
```powershell
|
|
186
181
|
# Windows PowerShell
|
|
@@ -197,13 +192,13 @@ adb install -r ./out/<appName>-<versionName>-debug.apk
|
|
|
197
192
|
- `-r` = 覆盖安装（保留应用数据）
|
|
198
193
|
- 不知道 APK 的确切文件名？看 `build` 命令的末尾输出（会打印完整路径）
|
|
199
194
|
- `adb` 找不到？在 `mobileAppConfig.js` 里配 `android.adbPath`
|
|
200
|
-
- `test`
|
|
195
|
+
- `test` 命令已自动安装,无需手动
|
|
201
196
|
|
|
202
197
|
---
|
|
203
198
|
|
|
204
199
|
## 配置文件 `mobileAppConfig.js`
|
|
205
200
|
|
|
206
|
-
|
|
201
|
+
所有定制集中在这一个文件;**不配置也能跑**（用默认值）;
|
|
207
202
|
|
|
208
203
|
### 必填
|
|
209
204
|
|
|
@@ -217,41 +212,41 @@ adb install -r ./out/<appName>-<versionName>-debug.apk
|
|
|
217
212
|
| ------------- | ---------------- | -------------------------------------------------------------------------- |
|
|
218
213
|
| `appName` | `string \| null` | 应用显示名称（默认从 `package.json` 的 `name` 读） |
|
|
219
214
|
| `outputDir` | `string \| null` | APK / IPA 输出目录（默认 `./out`） |
|
|
220
|
-
| `appId` | `string` |
|
|
215
|
+
| `appId` | `string` | 应用唯一标识,反向域名格式（Android `applicationId` / iOS Bundle ID） |
|
|
221
216
|
| `versionCode` | `int` | 内部版本号（Android `versionCode` / iOS `CFBundleVersion`） |
|
|
222
217
|
| `versionName` | `string` | 你的可见版本名（Android `versionName` / iOS `CFBundleShortVersionString`） |
|
|
223
218
|
|
|
224
219
|
### WebView
|
|
225
220
|
|
|
226
|
-
| 字段 | 类型 | 默认 | 说明
|
|
227
|
-
| --------------------- | --------- | ------------------- |
|
|
228
|
-
| `showLoading` | `boolean` | `true` | 是否显示加载指示器
|
|
229
|
-
| `loadingText` | `string` | `'正在启动服务...'` | 加载提示文字
|
|
230
|
-
| `enableJavaScript` | `boolean` | `true` | 是否启用 JavaScript
|
|
231
|
-
| `enableDomStorage` | `boolean` | `true` | 是否启用 DOM Storage
|
|
232
|
-
| `allowFileAccess` | `boolean` | `true` | 是否允许访问本地文件
|
|
233
|
-
| `mixedContentMode` | `string` | `'always'` | 混合内容模式：`never` / `always` / `compatibility`
|
|
234
|
-
| `backgroundColor` | 见下 | `'#ffffff'` | WebView
|
|
235
|
-
| `allowSelfSignedCert` | `boolean` | `false` | 见下文「HTTPS 自签证书」
|
|
221
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
222
|
+
| --------------------- | --------- | ------------------- | ------------------------------------------------------------------------------------------ |
|
|
223
|
+
| `showLoading` | `boolean` | `true` | 是否显示加载指示器 |
|
|
224
|
+
| `loadingText` | `string` | `'正在启动服务...'` | 加载提示文字 |
|
|
225
|
+
| `enableJavaScript` | `boolean` | `true` | 是否启用 JavaScript |
|
|
226
|
+
| `enableDomStorage` | `boolean` | `true` | 是否启用 DOM Storage |
|
|
227
|
+
| `allowFileAccess` | `boolean` | `true` | 是否允许访问本地文件 |
|
|
228
|
+
| `mixedContentMode` | `string` | `'always'` | 混合内容模式：`never` / `always` / `compatibility` |
|
|
229
|
+
| `backgroundColor` | 见下 | `'#ffffff'` | WebView 背景色;支持：固定色 `'#ffffff'` / 跟随系统 `'system'` / 深浅两值 `{ light, dark }` |
|
|
230
|
+
| `allowSelfSignedCert` | `boolean` | `false` | 见下文「HTTPS 自签证书」 |
|
|
236
231
|
|
|
237
232
|
### Android
|
|
238
233
|
|
|
239
|
-
| 字段 | 类型 | 默认 | 说明
|
|
240
|
-
| ----------------------- | ---------------- | -------------------- |
|
|
241
|
-
| `sdkPath` | `string \| null` | `null` | Android SDK 路径（默认自动查找）
|
|
242
|
-
| `adbPath` | `string \| null` | `null` | adb 路径（默认自动查找）
|
|
243
|
-
| `minSdkVersion` | `int` | `29` | 最低 SDK（29=Android 10.0）
|
|
244
|
-
| `targetSdkVersion` | `int` | `36` | 目标 SDK
|
|
245
|
-
| `compileSdkVersion` | `int` | `37` | 编译 SDK
|
|
246
|
-
| `buildToolsVersion` | `string` | `'37.0.0'` | 构建工具版本
|
|
247
|
-
| `abiFilters` | `string[]` | `['arm64-v8a']` | 打包架构（真机 `arm64-v8a
|
|
248
|
-
| `icon` | `string` | `'./build/icon.png'` | 应用图标（建议 512×512 PNG）
|
|
249
|
-
| `usesCleartextTraffic` | `boolean` | `true` | 是否允许明文 HTTP
|
|
250
|
-
| `permissions` | `string[]` | `[]` | 额外权限（如 `'android.permission.CAMERA'`）
|
|
251
|
-
| `signing.keystore` | `string` | — | 签名 keystore
|
|
252
|
-
| `signing.storePassword` | `string` | — | keystore 密码
|
|
253
|
-
| `signing.keyAlias` | `string` | — | key 别名
|
|
254
|
-
| `signing.keyPassword` | `string` | — | key 密码
|
|
234
|
+
| 字段 | 类型 | 默认 | 说明 |
|
|
235
|
+
| ----------------------- | ---------------- | -------------------- | ---------------------------------------------------------------------- |
|
|
236
|
+
| `sdkPath` | `string \| null` | `null` | Android SDK 路径（默认自动查找） |
|
|
237
|
+
| `adbPath` | `string \| null` | `null` | adb 路径（默认自动查找） |
|
|
238
|
+
| `minSdkVersion` | `int` | `29` | 最低 SDK（29=Android 10.0） |
|
|
239
|
+
| `targetSdkVersion` | `int` | `36` | 目标 SDK |
|
|
240
|
+
| `compileSdkVersion` | `int` | `37` | 编译 SDK |
|
|
241
|
+
| `buildToolsVersion` | `string` | `'37.0.0'` | 构建工具版本 |
|
|
242
|
+
| `abiFilters` | `string[]` | `['arm64-v8a']` | 打包架构（真机 `arm64-v8a`,模拟器加 `x86_64`） |
|
|
243
|
+
| `icon` | `string` | `'./build/icon.png'` | 应用图标（建议 512×512 PNG） |
|
|
244
|
+
| `usesCleartextTraffic` | `boolean` | `true` | 是否允许明文 HTTP |
|
|
245
|
+
| `permissions` | `string[]` | `[]` | 额外权限（如 `'android.permission.CAMERA'`） |
|
|
246
|
+
| `signing.keystore` | `string` | — | 签名 keystore 路径（相对你的项目根）;不填则用模板自带的 debug keystore |
|
|
247
|
+
| `signing.storePassword` | `string` | — | keystore 密码 |
|
|
248
|
+
| `signing.keyAlias` | `string` | — | key 别名 |
|
|
249
|
+
| `signing.keyPassword` | `string` | — | key 密码 |
|
|
255
250
|
|
|
256
251
|
### iOS
|
|
257
252
|
|
|
@@ -289,15 +284,15 @@ adb install -r ./out/<appName>-<versionName>-debug.apk
|
|
|
289
284
|
|
|
290
285
|
## 服务地址说明
|
|
291
286
|
|
|
292
|
-
CLI **自动识别 `server.js` 实际监听的协议和端口**——拦截 `net.Server.prototype.listen
|
|
287
|
+
CLI **自动识别 `server.js` 实际监听的协议和端口**——拦截 `net.Server.prototype.listen`,从 `server.address()` 取真实端口,从 `Server` 类型判断 `http` / `https`;
|
|
293
288
|
|
|
294
|
-
因此 `mobileAppConfig.js`
|
|
289
|
+
因此 `mobileAppConfig.js` **不需要**配置端口/协议;动态端口（`listen(0)`）会拿到系统分配的真实端口;
|
|
295
290
|
|
|
296
291
|
**失败场景**：
|
|
297
292
|
- `server.js` 加载抛异常 → App 显示"应用启动失败"
|
|
298
293
|
- 5 秒内未调用 `listen()` → App 显示"应用启动失败"
|
|
299
294
|
|
|
300
|
-
|
|
295
|
+
你的看到简要提示,开发者点开"▶ 查看详细信息"能看到具体原因;
|
|
301
296
|
|
|
302
297
|
---
|
|
303
298
|
|
|
@@ -313,36 +308,37 @@ CLI **自动识别 `server.js` 实际监听的协议和端口**——拦截 `net
|
|
|
313
308
|
| HTTPS + 自签证书 + 未装设备（本地测试最常见） | **必须设为 `true`** |
|
|
314
309
|
|
|
315
310
|
**实现方式**：
|
|
316
|
-
- Android：patch `RNCWebViewClient.java
|
|
317
|
-
- iOS：patch `RNCWebViewImpl.m
|
|
311
|
+
- Android：patch `RNCWebViewClient.java`,仅对 `127.0.0.1` / `localhost` 放行
|
|
312
|
+
- iOS：patch `RNCWebViewImpl.m`,同上
|
|
318
313
|
|
|
319
|
-
|
|
314
|
+
其他域名仍严格校验;生产环境建议关闭;
|
|
320
315
|
|
|
321
316
|
---
|
|
322
317
|
|
|
323
318
|
## Android / iOS 差异
|
|
324
319
|
|
|
325
|
-
| 项 | Android
|
|
326
|
-
| ------------ |
|
|
327
|
-
| 构建环境 | Windows / macOS / Linux
|
|
328
|
-
|
|
|
329
|
-
| Express 版本 |
|
|
330
|
-
|
|
|
331
|
-
|
|
|
320
|
+
| 项 | Android | iOS |
|
|
321
|
+
| ------------ | --------------------------------------------------------- | ---------------------------------------- |
|
|
322
|
+
| 构建环境 | Windows / macOS / Linux | **仅 macOS** |
|
|
323
|
+
| 运行时版本 | 官方提供多个版本,可用 `NODE_MOBILE_PREBUILT_VERSION` 切换 | **当前为 v18.20.4**,更高版本后续逐步适配 |
|
|
324
|
+
| Express 版本 | 产物带 full-icu,4.x / 5.x 均可用 | 当前产物不带 full-icu,**必须用 4.x** |
|
|
325
|
+
| full-icu | 自 v22.23.2 产物起支持 | 暂无 |
|
|
326
|
+
| `test` 离线 | ✓（内置 bundle） | ✓（需 `FORCE_BUNDLING=1`） |
|
|
327
|
+
| 图标尺寸 | 5 个密度（48~192） | 9 个尺寸（40~1024） |
|
|
332
328
|
|
|
333
|
-
**iOS
|
|
329
|
+
**iOS 运行时版本**：iOS 附件的实际运行时版本随适配进度变化,**当前对应 v18.20.4**;如需更高版本,可克隆 [nodejs-mobile 仓库](https://github.com/OpenFlun/nodejs-mobile) 自行编译 `NodeMobile.xcframework`,流程与 Android 自编译 `libnode.so` 类似（见 `自定义libnode指南.md`）;
|
|
334
330
|
|
|
335
331
|
---
|
|
336
332
|
|
|
337
333
|
## 你的项目结构
|
|
338
334
|
|
|
339
|
-
运行 CLI
|
|
335
|
+
运行 CLI 后,你的项目根目录的样子：
|
|
340
336
|
|
|
341
337
|
```
|
|
342
338
|
你的项目/
|
|
343
339
|
├── package.json # 你自己的
|
|
344
340
|
├── mobileAppConfig.js # CLI 生成的配置（可编辑）
|
|
345
|
-
├── server.js # Node
|
|
341
|
+
├── server.js # Node 启动脚本（你写的,或 CLI 生成的示例）
|
|
346
342
|
├── node_modules/ # 你的依赖
|
|
347
343
|
├── build/ # 你的资源（图标、keystore 等）
|
|
348
344
|
│ ├── icon.png
|
|
@@ -350,11 +346,12 @@ CLI **自动识别 `server.js` 实际监听的协议和端口**——拦截 `net
|
|
|
350
346
|
│── 你的其它文件/目录...
|
|
351
347
|
└── node-mobile-app-build/ # CLI 生成的 RN 工程（可整体删除重建）
|
|
352
348
|
├── android/ ios/ App.tsx index.js ...
|
|
353
|
-
├── mobileApp.runtime.ts # CLI
|
|
349
|
+
├── mobileApp.runtime.ts # CLI 生成,App.tsx 读
|
|
354
350
|
└── nodejs-assets/
|
|
355
351
|
└── nodejs-project/ # 你的 Node 项目副本
|
|
356
352
|
├── server.js # 你的源码
|
|
357
|
-
├── main.js # CLI
|
|
353
|
+
├── main.js # CLI 生成,桥接代码
|
|
354
|
+
│── 你允许的其它生产文件/目录...
|
|
358
355
|
├── package.json # 只保留 dependencies
|
|
359
356
|
└── node_modules/ # 你的生产依赖
|
|
360
357
|
```
|
|
@@ -365,18 +362,18 @@ CLI **自动识别 `server.js` 实际监听的协议和端口**——拦截 `net
|
|
|
365
362
|
|
|
366
363
|
### Q：`test` 拔掉 USB 后 App 加载慢？
|
|
367
364
|
|
|
368
|
-
`test` 打的是 debug
|
|
365
|
+
`test` 打的是 debug 版,启动时**先尝试连 Metro**,失败后才 fallback 到内置 bundle;这个"等超时"是 RN debug 版的固有行为;
|
|
369
366
|
|
|
370
367
|
- 需要**秒开**：用 `npx node-mobile-app build`
|
|
371
368
|
- 需要**热更新**：`test` 保持 USB 连接
|
|
372
369
|
|
|
373
370
|
### Q：`test` 装到手机后拔 USB 就崩？
|
|
374
371
|
|
|
375
|
-
前提是 APK 里有内置 bundle
|
|
372
|
+
前提是 APK 里有内置 bundle;`test` 每次都会先 `react-native bundle` 打进 APK;**如果崩,检查 CLI 输出里 `[6/9] 生成 JS bundle` 是否成功**;
|
|
376
373
|
|
|
377
374
|
### Q：Node 进程启动失败怎么排查？
|
|
378
375
|
|
|
379
|
-
App 显示"应用启动失败"页 → 点"▶ 查看详细信息" → 看到具体原因（如 `加载 ./server.js 失败 --
|
|
376
|
+
App 显示"应用启动失败"页 → 点"▶ 查看详细信息" → 看到具体原因（如 `加载 ./server.js 失败 -- ...`）;
|
|
380
377
|
|
|
381
378
|
进一步用 `adb logcat` 看 Node 日志：
|
|
382
379
|
|
|
@@ -393,58 +390,58 @@ adb logcat | grep -E "NODEJS-MOBILE|ReactNativeJS"
|
|
|
393
390
|
|
|
394
391
|
### Q：Express 版本怎么选？
|
|
395
392
|
|
|
396
|
-
-
|
|
397
|
-
-
|
|
393
|
+
- **Android**：内置完整 ICU（full-icu）→ 可以用 Express 5
|
|
394
|
+
- **iOS**：暂无 ICU → 必须用 Express 4
|
|
398
395
|
|
|
399
|
-
Express 5 的路由语法与 4 不同（如 `app.get('*')` 要改成 `app.get('/{*splat}')
|
|
396
|
+
Express 5 的路由语法与 4 不同（如 `app.get('*')` 要改成 `app.get('/{*splat}')`）,迁移时留意;
|
|
400
397
|
|
|
401
398
|
### Q：`libnode.so` 和 `NodeMobile.xcframework` 是怎么来的？
|
|
402
399
|
|
|
403
|
-
从 `@flun/nodejs-mobile-react-native` 1.0.1
|
|
400
|
+
从 `@flun/nodejs-mobile-react-native` 1.0.1 起,两套预编译二进制**不在 npm 包里**,改为 postinstall 阶段自动从 Gitee / GitHub Release 下载：
|
|
404
401
|
|
|
405
|
-
| 资源 |
|
|
406
|
-
| -------------------------------- |
|
|
407
|
-
| `android-libnode.zip` |
|
|
408
|
-
| `ios-nodemobile.zip`（仅 macOS） |
|
|
402
|
+
| 资源 | 目标位置 |
|
|
403
|
+
| -------------------------------- | --------------------------------------------------------------------------- |
|
|
404
|
+
| `android-libnode.zip` | `node_modules/@flun/nodejs-mobile-react-native/android/libnode/` |
|
|
405
|
+
| `ios-nodemobile.zip`（仅 macOS） | `node_modules/@flun/nodejs-mobile-react-native/ios/NodeMobile.xcframework/` |
|
|
409
406
|
|
|
410
|
-
-
|
|
411
|
-
- Gitee
|
|
412
|
-
-
|
|
413
|
-
-
|
|
407
|
+
- 默认下载版本以 `@flun/nodejs-mobile-react-native` 的 `package.json` 中 `prebuiltAssets.version` 字段为准
|
|
408
|
+
- Gitee 优先,失败自动回退 GitHub
|
|
409
|
+
- 已装版本匹配则跳过,不重复下
|
|
410
|
+
- 全部源失败时打印下载链接,**不中断 npm 安装**
|
|
414
411
|
|
|
415
412
|
环境变量：
|
|
416
413
|
|
|
417
414
|
```bash
|
|
418
|
-
NODE_MOBILE_PREBUILT_VERSION
|
|
419
|
-
NODE_MOBILE_PREBUILT_SKIP=1
|
|
420
|
-
NODE_MOBILE_PREBUILT_IOS_SKIP=1
|
|
415
|
+
NODE_MOBILE_PREBUILT_VERSION=<版本号> # 覆盖默认版本（须为该包 Release 中实际存在的 tag）
|
|
416
|
+
NODE_MOBILE_PREBUILT_SKIP=1 # 跳过全部下载
|
|
417
|
+
NODE_MOBILE_PREBUILT_IOS_SKIP=1 # 只跳过 iOS
|
|
421
418
|
```
|
|
422
419
|
|
|
423
420
|
### Q：如何替换成自定义编译的 `libnode.so`？
|
|
424
421
|
|
|
425
|
-
|
|
422
|
+
如果你自编译了 `libnode.so`（如需要特定 Node 版本或自定义 ICU）,可手动覆盖自动下载的产物：
|
|
426
423
|
|
|
427
424
|
1. 把编译好的 `libnode.so` 覆盖到 `android/libnode/bin/<架构>/`（**只放你实际编译的架构**）
|
|
428
|
-
2. 如果 `mobileAppConfig.js` 的 `android.abiFilters` 与 libnode
|
|
425
|
+
2. 如果 `mobileAppConfig.js` 的 `android.abiFilters` 与 libnode 支持的架构不一致,同步调整
|
|
429
426
|
3. 跑 `npx node-mobile-app build` 或 `npx node-mobile-app test`
|
|
430
427
|
|
|
431
|
-
**CLI 会自动处理缓存**：指纹机制检测到 `libnode.so` 或 `abiFilters`
|
|
428
|
+
**CLI 会自动处理缓存**：指纹机制检测到 `libnode.so` 或 `abiFilters` 变化,自动清理 `.cxx` / `android/build` / `app/build`,全量重编;**你的无需手动清任何缓存**;
|
|
432
429
|
|
|
433
|
-
|
|
430
|
+
详细流程见 `自定义libnode指南.md`;
|
|
434
431
|
|
|
435
432
|
### Q：iOS 提示 `fallbackSourceURL does not override`？
|
|
436
433
|
|
|
437
|
-
RN 0.87 的 API
|
|
434
|
+
RN 0.87 的 API 若变动,`AppDelegate.swift` 里的 fallback 可能不生效——不影响"连 Mac + Metro"正常开发,只是拔 Mac 后无法 fallback 到内置 bundle;届时反馈,我们更新适配;
|
|
438
435
|
|
|
439
436
|
---
|
|
440
437
|
|
|
441
438
|
## 相关文档
|
|
442
439
|
|
|
443
440
|
- [Android 构建指南.md](./Android%20构建指南.md) —— Android 环境配置、踩坑清单
|
|
444
|
-
- [自定义libnode指南.md](./自定义libnode指南.md) —— 自编译
|
|
441
|
+
- [自定义libnode指南.md](./自定义libnode指南.md) —— 自编译 `libnode.so` 的完整流程
|
|
445
442
|
|
|
446
443
|
---
|
|
447
444
|
|
|
448
445
|
## 许可
|
|
449
446
|
|
|
450
|
-
ISC
|
|
447
|
+
ISC
|
package/cli-assets/server.js
CHANGED
|
@@ -34,4 +34,4 @@ const PORT = 3000,
|
|
|
34
34
|
res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' }), res.end(html);
|
|
35
35
|
});
|
|
36
36
|
|
|
37
|
-
server.listen(PORT, '0.0.0.0', () => console.log(`
|
|
37
|
+
server.listen(PORT, '0.0.0.0', () => console.log(`Server started on port ${PORT}`));
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@flun/node-mobile-app",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.5",
|
|
4
4
|
"description": "将 Node.js 项目一键打包为 Android / iOS 移动应用,运行时由 @flun/nodejs-mobile-react-native 提供,无需修改你的 Node 代码;",
|
|
5
5
|
"author": "flun <open@flun.top>",
|
|
6
6
|
"keywords": [
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
"eslint-plugin-react": "^7.37.5",
|
|
63
63
|
"eslint-plugin-react-hooks": "^7.1.1",
|
|
64
64
|
"eslint-plugin-react-native": "^5.0.0",
|
|
65
|
-
"@flun/nodejs-mobile-react-native": "^2.0.
|
|
65
|
+
"@flun/nodejs-mobile-react-native": "^2.0.3"
|
|
66
66
|
},
|
|
67
67
|
"allowScripts": {
|
|
68
68
|
"node": true,
|
|
@@ -81,7 +81,7 @@
|
|
|
81
81
|
},
|
|
82
82
|
"license": "ISC",
|
|
83
83
|
"engines": {
|
|
84
|
-
"node": ">= 18
|
|
84
|
+
"node": ">= 18"
|
|
85
85
|
},
|
|
86
86
|
"bin": {
|
|
87
87
|
"node-mobile-app": "./bin/cli.js"
|
package/scripts/copy-files.js
CHANGED
|
@@ -6,31 +6,30 @@ import { fileURLToPath } from 'url';
|
|
|
6
6
|
const __filename = fileURLToPath(import.meta.url), __dirname = path.dirname(__filename),
|
|
7
7
|
initCwd = process.env.INIT_CWD, fileName = 'mobileAppConfig.js', targetDir = initCwd ? path.resolve(initCwd) : '',
|
|
8
8
|
// 要拷贝的文件和目标文件路径
|
|
9
|
-
sourceFile = path.join(__dirname, '..', fileName), targetFile = path.join(targetDir, fileName)
|
|
9
|
+
sourceFile = path.join(__dirname, '..', fileName), targetFile = path.join(targetDir, fileName),
|
|
10
|
+
/**
|
|
11
|
+
* 复制文件到项目根目录
|
|
12
|
+
* >查看定义:@see {@link copyFile}
|
|
13
|
+
* @returns {boolean} - 复制是否成功
|
|
14
|
+
*/
|
|
15
|
+
copyFile = () => {
|
|
16
|
+
console.log(`🔍 检查 ${fileName} 文件...`), console.log(`📁 项目根目录:${targetDir}`);
|
|
17
|
+
try {
|
|
18
|
+
// 无 INIT_CWD（非用户项目安装场景）|| 目标目录不是 Node 项目 || 包自身的 npm install（开发调试）→ 跳过
|
|
19
|
+
if (!targetDir) return true;
|
|
20
|
+
if (!fs.existsSync(path.join(targetDir, 'package.json'))) return true;
|
|
21
|
+
if (targetDir === path.resolve(__dirname, '..')) return true;
|
|
22
|
+
if (fs.existsSync(targetFile)) return true; // 目标文件已存在 → 直接返回
|
|
23
|
+
console.log(`⚠️ 在项目根目录未找到 ${fileName} 文件，正在创建...`);
|
|
10
24
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
try {
|
|
19
|
-
// 无 INIT_CWD（非用户项目安装场景）|| 目标目录不是 Node 项目 || 包自身的 npm install（开发调试）→ 跳过
|
|
20
|
-
if (!targetDir) return true;
|
|
21
|
-
if (!fs.existsSync(path.join(targetDir, 'package.json'))) return true;
|
|
22
|
-
if (targetDir === path.resolve(__dirname, '..')) return true;
|
|
23
|
-
if (fs.existsSync(targetFile)) return true; // 目标文件已存在 → 直接返回
|
|
24
|
-
console.log(`⚠️ 在项目根目录未找到 ${fileName} 文件，正在创建...`);
|
|
25
|
-
|
|
26
|
-
fs.copyFileSync(sourceFile, targetFile); // 复制源文件到项目根目录
|
|
27
|
-
console.log(`✓ 已创建 ${fileName} 示例文件:${targetFile}`);
|
|
28
|
-
return true;
|
|
29
|
-
} catch (error) {
|
|
30
|
-
console.error(`✗ 创建 ${fileName} 文件失败:`, error.message);
|
|
31
|
-
return false;
|
|
25
|
+
fs.copyFileSync(sourceFile, targetFile); // 复制源文件到项目根目录
|
|
26
|
+
console.log(`✓ 已创建 ${fileName} 示例文件:${targetFile}`);
|
|
27
|
+
return true;
|
|
28
|
+
} catch (error) {
|
|
29
|
+
console.error(`✗ 创建 ${fileName} 文件失败:`, error.message);
|
|
30
|
+
return false;
|
|
31
|
+
}
|
|
32
32
|
}
|
|
33
|
-
}
|
|
34
33
|
|
|
35
34
|
// 执行脚本并导出函数
|
|
36
35
|
if (process.argv[1] === __filename) copyFile();
|
package/src/generate.js
CHANGED
|
@@ -94,11 +94,11 @@ const generateMainJs = (targetDir, config, moduleType) => {
|
|
|
94
94
|
enableDomStorage: config.webview.enableDomStorage,
|
|
95
95
|
allowFileAccess: config.webview.allowFileAccess,
|
|
96
96
|
mixedContentMode: config.webview.mixedContentMode,
|
|
97
|
-
backgroundColor: config.webview.backgroundColor
|
|
97
|
+
backgroundColor: config.webview.backgroundColor
|
|
98
98
|
},
|
|
99
99
|
}, content = `// 自动生成，请勿手改\nexport default ${JSON.stringify(data, null, 2)} as const;\n`,
|
|
100
100
|
changed = writeIfChanged(path.join(buildDir, 'mobileApp.runtime.ts'), content);
|
|
101
101
|
console.log(changed ? ' ✓ 已生成 mobileApp.runtime.ts' : ' ✓ mobileApp.runtime.ts 无变化');
|
|
102
|
-
}
|
|
102
|
+
};
|
|
103
103
|
|
|
104
|
-
export { generateMainJs, generateRuntime }
|
|
104
|
+
export { generateMainJs, generateRuntime }
|
package/src/install.js
CHANGED
|
@@ -89,31 +89,20 @@ const hashDeps = (pkgPath, hasNative, forceRebuild) => {
|
|
|
89
89
|
*/
|
|
90
90
|
installUserDeps = (targetDir, userProjectDir, config) => {
|
|
91
91
|
const assetsDir = path.dirname(targetDir), bnmFile = path.join(assetsDir, 'BUILD_NATIVE_MODULES.txt'),
|
|
92
|
-
hashFile = path.join(targetDir, '.deps-hash'),
|
|
93
|
-
|
|
94
|
-
forceRebuild = process.env.NODE_MOBILE_FORCE_REBUILD === '1';
|
|
95
|
-
|
|
96
|
-
// 自动检测是否有原生模块（binding.gyp）
|
|
97
|
-
const hasNative = hasNativeModules(userProjectDir);
|
|
98
|
-
fs.writeFileSync(bnmFile, hasNative ? '1' : '0');
|
|
92
|
+
hashFile = path.join(targetDir, '.deps-hash'), nodeModulesDir = path.join(targetDir, 'node_modules'),
|
|
93
|
+
forceRebuild = process.env.NODE_MOBILE_FORCE_REBUILD === '1', hasNative = hasNativeModules(userProjectDir);
|
|
99
94
|
|
|
95
|
+
fs.writeFileSync(bnmFile, hasNative ? '1' : '0'); // 自动检测是否有原生模块（binding.gyp）
|
|
100
96
|
// 计算当前依赖 hash（含 native + force 状态）
|
|
101
|
-
const pkgPath = path.join(targetDir, 'package.json'),
|
|
102
|
-
currentHash = hashDeps(pkgPath, hasNative, forceRebuild),
|
|
97
|
+
const pkgPath = path.join(targetDir, 'package.json'), currentHash = hashDeps(pkgPath, hasNative, forceRebuild),
|
|
103
98
|
hasModules = fs.existsSync(nodeModulesDir);
|
|
104
99
|
let oldHash = null;
|
|
105
100
|
if (fs.existsSync(hashFile)) try { oldHash = fs.readFileSync(hashFile, 'utf-8').trim(); } catch { };
|
|
106
|
-
|
|
107
|
-
if (hasModules && oldHash === currentHash && !forceRebuild) {
|
|
108
|
-
return console.log(' ✓ 依赖无变化，跳过安装');
|
|
109
|
-
}
|
|
101
|
+
if (hasModules && oldHash === currentHash && !forceRebuild) return console.log(' ✓ 依赖无变化,跳过安装');
|
|
110
102
|
if (forceRebuild) console.log(' ℹ️ NODE_MOBILE_FORCE_REBUILD=1，强制重装依赖');
|
|
111
103
|
|
|
112
104
|
const env = { ...process.env };
|
|
113
|
-
if (hasNative)
|
|
114
|
-
env.NODEJS_MOBILE_BUILD_NATIVE_MODULES = '1';
|
|
115
|
-
console.log(' ℹ️ 检测到原生模块（binding.gyp），将编译原生代码');
|
|
116
|
-
}
|
|
105
|
+
if (hasNative) env.NODEJS_MOBILE_BUILD_NATIVE_MODULES = '1', console.log(' ℹ️ 检测到原生模块（binding.gyp）,将编译原生代码');
|
|
117
106
|
|
|
118
107
|
console.log(' 安装用户生产依赖（nodejs-assets/nodejs-project）...');
|
|
119
108
|
run('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], { cwd: targetDir, env });
|
package/src/patcher.js
CHANGED
|
@@ -53,7 +53,7 @@ const resolveAppName = (userProjectDir, config) => {
|
|
|
53
53
|
stringsFile = path.join(buildDir, 'android', 'app', 'src', 'main', 'res', 'values', 'strings.xml'),
|
|
54
54
|
ktFiles = [
|
|
55
55
|
path.join(buildDir, 'android', 'app', 'src', 'main', 'java', 'com', 'myapp', 'MainActivity.kt'),
|
|
56
|
-
path.join(buildDir, 'android', 'app', 'src', 'main', 'java', 'com', 'myapp', 'MainApplication.kt')
|
|
56
|
+
path.join(buildDir, 'android', 'app', 'src', 'main', 'java', 'com', 'myapp', 'MainApplication.kt')
|
|
57
57
|
];
|
|
58
58
|
// 1. build.gradle
|
|
59
59
|
if (fs.existsSync(gradleFile)) {
|
|
@@ -370,5 +370,5 @@ const resolveAppName = (userProjectDir, config) => {
|
|
|
370
370
|
// ===== 导出 =====
|
|
371
371
|
export {
|
|
372
372
|
resolveAppName, escapeKotlinString, escapeSwiftString, patchAppConfig, patchAndroidConfig, patchSigning,
|
|
373
|
-
patchIcon, patchIosConfig, patchIosIcon
|
|
373
|
+
patchIcon, patchIosConfig, patchIosIcon
|
|
374
374
|
};
|
package/src/platform-ios.js
CHANGED
package/src/utils.js
CHANGED
|
@@ -99,7 +99,7 @@ const ensureDir = dir => {
|
|
|
99
99
|
candidates = [
|
|
100
100
|
path.join(localAppData, 'Android', 'Sdk', 'platform-tools', 'adb.exe'),
|
|
101
101
|
path.join(home, 'Library', 'Android', 'sdk', 'platform-tools', 'adb'),
|
|
102
|
-
path.join(home, 'Android', 'Sdk', 'platform-tools', 'adb')
|
|
102
|
+
path.join(home, 'Android', 'Sdk', 'platform-tools', 'adb')
|
|
103
103
|
];
|
|
104
104
|
for (const c of candidates) if (c && fs.existsSync(c)) return c;
|
|
105
105
|
return 'adb';
|
package/template/metro.config.js
CHANGED
|
@@ -3,15 +3,15 @@ import exclusionListModule from 'metro-config/private/defaults/exclusionList';
|
|
|
3
3
|
import { dirname, resolve } from 'path';
|
|
4
4
|
import { fileURLToPath } from 'url';
|
|
5
5
|
|
|
6
|
-
const exclusionList = exclusionListModule.default
|
|
7
|
-
|
|
6
|
+
const exclusionList = exclusionListModule.default,
|
|
7
|
+
__filename = fileURLToPath(import.meta.url), __dirname = dirname(__filename), workspaceRoot = resolve(__dirname, '..'),
|
|
8
8
|
config = {
|
|
9
9
|
watchFolders: [__dirname, resolve(workspaceRoot, 'node_modules')],
|
|
10
10
|
resolver: {
|
|
11
11
|
nodeModulesPaths: [resolve(__dirname, 'node_modules'), resolve(workspaceRoot, 'node_modules')],
|
|
12
12
|
blockList: exclusionList([
|
|
13
|
-
/[/\\]nodejs-assets[/\\]
|
|
14
|
-
])
|
|
13
|
+
/[/\\]nodejs-assets[/\\].*/
|
|
14
|
+
])
|
|
15
15
|
}
|
|
16
16
|
};
|
|
17
17
|
|