@flun/node-mobile-app 4.0.6 → 4.0.8

package/Android /346/236/204/345/273/272/346/214/207/345/215/227.md"

@@ -1,65 +1,66 @@
 # Android 构建指南
 
-本文档是 [README.md](./README.md) 的**深度附件**;日常使用（`test` / `build`）不需要看——CLI 自动处理;
+本文档是 [README.md](./README.md) 的**深度附件**;日常使用(`test` / `build`)不需要看--CLI 自动处理;
 
-本文档只讲四件事,都是 README 没细说的：
-1. **环境准备**（JDK / SDK / NDK / adb / 原生模块编译）
-2. **libnode.so**（v18 vs v22、预编译仓库、替换、full-icu 验证）
-3. **Express 版本选择**（踩坑清单）
-4. **调试与缓存排查**（logcat 命令、手动清缓存兜底）
+本文档只讲四件事,都是 README 没细说的:
+1. **环境准备**(JDK / SDK / NDK / adb / 原生模块编译)
+2. **libnode.so**(v18 vs v22、预编译仓库、替换、full-icu 验证)
+3. **Express 版本选择**(踩坑清单)
+4. **调试与缓存排查**(logcat 命令、手动清缓存兜底)
 
 ---
 
 ## 一、环境准备
 
-### 1.1 JDK 17（必须）
+### 1.1 JDK 17(必须)
 
 Android Gradle Plugin 不支持 JDK 18+;
 
-下载：[Adoptium JDK 17](https://adoptium.net/temurin/releases/?version=17)
+下载:[Adoptium JDK 17](https://adoptium.net/temurin/releases/?version=17)
 
 **CLI 不读 `JAVA_HOME`**,直接用系统 PATH 里的 `java`;确保 `java -version` 输出是 17;
 
 ### 1.2 Android SDK
 
-CLI 自动查找,顺序：
+CLI 自动查找,顺序:
 
 1. `mobileAppConfig.js` 的 `android.sdkPath`
 2. 环境变量 `ANDROID_HOME` / `ANDROID_SDK_ROOT`
-3. 常见默认路径（Windows：`%LOCALAPPDATA%\Android\Sdk`）
+3. 常见默认路径(Windows:`%LOCALAPPDATA%\Android\Sdk`)
 
-**必需组件**：
+**必需组件**:
 
 | 组件           | 版本                                                                      |
 | -------------- | ------------------------------------------------------------------------- |
 | SDK Platform   | 与 `mobileAppConfig.js` 的 `android.compileSdkVersion` 一致的 Platform    |
 | Build-Tools    | 与 `mobileAppConfig.js` 的 `android.buildToolsVersion` 一致               |
 | Platform-Tools | 含 adb 的较新版本                                                         |
-| NDK            | 与模板 `android/build.gradle` 的 `ndkVersion` 一致（libnode.so 编译依赖） |
+| NDK            | 与模板 `android/build.gradle` 的 `ndkVersion` 一致(libnode.so 编译依赖) |
 
 ### 1.3 adb
 
-查找顺序同 SDK;常用命令：
+查找顺序同 SDK;常用命令:
 
 ```powershell
 $adb = "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe"
 & $adb devices
 ```
 
-### 1.4 原生模块编译（自动检测）
+### 1.4 原生模块编译(自动检测)
 
-CLI 会扫描 `<buildDir>/nodejs-assets/nodejs-project/node_modules/` 下是否有 `binding.gyp` 文件（原生模块的标志）,自动写：
+CLI 会扫描 `<buildDir>/nodejs-assets/nodejs-project/node_modules/` 下是否有 `binding.gyp` 文件(原生模块的标志),自动写:
 
 ```
 <buildDir>/nodejs-assets/BUILD_NATIVE_MODULES.txt   # 1=有原生模块,0=无
 ```
 
-- **检测到原生模块**（如 `bcrypt`、`sqlite3`）：写 `1`,并设环境变量 `NODEJS_MOBILE_BUILD_NATIVE_MODULES=1`,`npm install` 时自动重编
-- **未检测到**：写 `0`,跳过编译
+- **检测到原生模块**(如 `bcrypt`、`sqlite3`):写 `1`,并设环境变量 `NODEJS_MOBILE_BUILD_NATIVE_MODULES=1`,`npm install` 
+  时自动重编
+- **未检测到**:写 `0`,跳过编译
 
 **用户无需手动配置**;检测结果会纳入依赖哈希,装/卸原生模块时会自动触发重装重编;
 
-**手动强制重编**：换过 `libnode.so` 但依赖没变、需要重新编译原生模块时：
+**手动强制重编**:换过 `libnode.so` 但依赖没变、需要重新编译原生模块时:
 
 ```bash
 # Linux / macOS
@@ -71,7 +72,9 @@ NODE_MOBILE_FORCE_REBUILD=1 npx node-mobile-app test
 $env:NODE_MOBILE_FORCE_REBUILD=1; npx node-mobile-app test
 ```
 
-**Windows 编译原生模块的前置条件**：需 Android SDK 中的 NDK（提供交叉编译工具链与 `make.exe`）与 Git for Windows（提供 `sh` / `sed` / `rm` 等 GNU 工具，`nodejs-mobile-gyp` 会从注册表或常见路径自动定位）；二者缺失时编译阶段报错；Linux / macOS 使用系统自带的同类工具，无需额外安装;
+**Windows 编译原生模块的前置条件**:需 Android SDK 中的 NDK(提供交叉编译工具链与 `make.exe`)与 Git for Windows(提供 `sh` / 
+`sed` / `rm` 等 GNU 工具,`nodejs-mobile-gyp` 会从注册表或常见路径自动定位);二者缺失时编译阶段报错;Linux / macOS 
+使用系统自带的同类工具,无需额外安装;
 
 ---
 
@@ -81,15 +84,16 @@ $env:NODE_MOBILE_FORCE_REBUILD=1; npx node-mobile-app test
 
 ### 2.0 预编译二进制怎么来的
 
-从 `@flun/nodejs-mobile-react-native` 1.0.1 起,`libnode.so` **不在 npm 包里**,安装时由 postinstall 脚本从 Gitee / GitHub Release 自动下载：
+从 `@flun/nodejs-mobile-react-native` 1.0.1 起,`libnode.so` **不在 npm 包里**,安装时由 postinstall 脚本从 Gitee / GitHub 
+Release 自动下载:
 
-- **下载源**：Gitee 优先,失败自动回退 GitHub
-- **下载内容**：`android-libnode.zip`（双架构约 88 MB），含 `bin/` + `include/`；具体大小以实际下载为准；
-- **覆盖目标**：`node_modules/@flun/nodejs-mobile-react-native/android/libnode/`
-- **幂等**：已装版本匹配则跳过,不重复下载
-- **失败处理**：全部源失败时打印下载链接,不中断 npm 安装
+- **下载源**:Gitee 优先,失败自动回退 GitHub
+- **下载内容**:`android-libnode.zip`(双架构约 88 MB),含 `bin/` + `include/`;具体大小以实际下载为准;
+- **覆盖目标**:`node_modules/@flun/nodejs-mobile-react-native/android/libnode/`
+- **幂等**:已装版本匹配则跳过,不重复下载
+- **失败处理**:全部源失败时打印下载链接,不中断 npm 安装
 
-环境变量（按需）：
+环境变量(按需):
 
 ```bash
 NODE_MOBILE_PREBUILT_VERSION=v22.23.2   # 覆盖默认版本
@@ -97,17 +101,17 @@ NODE_MOBILE_PREBUILT_SKIP=1             # 跳过全部下载
 NODE_MOBILE_PREBUILT_ANDROID_SKIP=1     # 只跳过 Android
 ```
 
-**用户不需要手动下载和替换**——除非要换成自编译的版本,见 2.2;
+**用户不需要手动下载和替换**--除非要换成自编译的版本,见 2.2;
 
 ### 2.1 自动下载的预编译产物
 
-路径：
+路径:
 
 ```
 <你的项目>/node_modules/@flun/nodejs-mobile-react-native/android/libnode/bin/<架构>/libnode.so
 ```
 
-以下为 v18 产物的实测大小；其它版本的体积以实际下载为准：
+以下为 v18 产物的实测大小;其它版本的体积以实际下载为准:
 
 | 架构        | 大小    |
 | ----------- | ------- |
@@ -115,18 +119,19 @@ NODE_MOBILE_PREBUILT_ANDROID_SKIP=1     # 只跳过 Android
 | armeabi-v7a | 56 MB   |
 | x86_64      | 62.3 MB |
 
-**版本特性**：v18 产物使用 `--with-intl=none`，不含 ICU，不能用 `\p{...}` / `\P{...}` Unicode 正则，必须配 Express 4；v22 起产物带 full-icu，可用 Unicode 正则与 Express 5；下载版本由 `package.json` 的 `prebuiltAssets.version` 决定；
+**版本特性**:v18 产物使用 `--with-intl=none`,不含 ICU,不能用 `\p{...}` / `\P{...}` Unicode 正则,必须配 Express 4;v22 
+起产物带 full-icu,可用 Unicode 正则与 Express 5;下载版本由 `package.json` 的 `prebuiltAssets.version` 决定;
 
 ### 2.2 替换为自编译产物
 
-自动下载的产物若不含 full-icu（见 2.3 的 `strings` 验证），且需跑 Express 5 或使用 Unicode 正则，替换为自编译的 full-icu 版本；
+自动下载的产物若不含 full-icu(见 2.3 的 `strings` 验证),且需跑 Express 5 或使用 Unicode 正则,替换为自编译的 full-icu 版本;
 
-**预编译产物仓库**：
+**预编译产物仓库**:
 
-- GitHub：https://github.com/OpenFlun/nodejs-mobile
-- Gitee（国内）：https://gitee.com/OpenFlun/nodejs-mobile
+- GitHub:https://github.com/OpenFlun/nodejs-mobile
+- Gitee(国内):https://gitee.com/OpenFlun/nodejs-mobile
 
-**架构支持（按版本）**：
+**架构支持(按版本)**:
 
 | 架构        | v18 | v22 |
 | ----------- | --- | --- |
@@ -134,16 +139,17 @@ NODE_MOBILE_PREBUILT_ANDROID_SKIP=1     # 只跳过 Android
 | x86_64      | ✓   | ✓   |
 | armeabi-v7a | ✓   | ✗   |
 
-架构支持随产物版本变化；具体以 Releases 页面各版本的产物说明为准；
+架构支持随产物版本变化;具体以 Releases 页面各版本的产物说明为准;
 
-**替换步骤**：
+**替换步骤**:
 
-1. 下载 `android-libnode.zip`（含 `bin/` + `include/`）
+1. 下载 `android-libnode.zip`(含 `bin/` + `include/`)
 2. **整体替换** `你的项目/node_modules/@flun/nodejs-mobile-react-native/android/libnode/`
-3. `mobileAppConfig.js` 的 `android.abiFilters` 只写该产物实际包含的架构（见解压后的 `libnode/bin/` 目录）
+3. `mobileAppConfig.js` 的 `android.abiFilters` 只写该产物实际包含的架构(见解压后的 `libnode/bin/` 目录)
 4. 跑 `npx node-mobile-app test` 或 `build`
 
-CLI 指纹机制检测到 `libnode.so` 变化后，会清 `.cxx` / `android/build` / `app/build`，并清 `nodejs-assets` 与依赖快照，触发重装、重编、重优化——**无需手动清缓存**；
+CLI 指纹机制检测到 `libnode.so` 变化后,会清 `.cxx` / `android/build` / `app/build`,并清 `nodejs-assets` 与依赖快照,
+触发重装、重编、重优化--**无需手动清缓存**;
 
 **完整自编译流程**见 `自定义libnode指南.md`;
 
@@ -154,34 +160,34 @@ CLI 指纹机制检测到 `libnode.so` 变化后，会清 `.cxx` / `android/buil
 strings libnode.so | grep -c icudt78l
 ```
 
-- 输出几千（约 4300）→ 带 full-icu
+- 输出几千(约 4300)→ 带 full-icu
 - 输出 0 → 不带
 
-**体积对照**（实测,strip 后）：
+**体积对照**(实测,strip 后):
 
 | 版本                   | arm64-v8a | x86_64   |
 | ---------------------- | --------- | -------- |
-| v18（官方,无 ICU）     | 59.6 MB   | 62.3 MB  |
-| v22（自编译,full-icu） | 112.4 MB  | 117.2 MB |
+| v18(官方,无 ICU)     | 59.6 MB   | 62.3 MB  |
+| v22(自编译,full-icu) | 112.4 MB  | 117.2 MB |
 
-体积差异约 50 MB,来自三部分：Node v22 核心引擎 + full-icu 数据（约 25–30 MB）+ V8 版本升级;**不是编译出错**;
+体积差异约 50 MB,来自三部分:Node v22 核心引擎 + full-icu 数据(约 25–30 MB)+ V8 版本升级;**不是编译出错**;
 
 ---
 
-## 三、Express 版本选择（踩坑清单）
+## 三、Express 版本选择(踩坑清单)
 
-**选错版本会在 Node 进程启动时崩溃**,且错误信息极具误导性（如 `number 116 is not a function`）;
+**选错版本会在 Node 进程启动时崩溃**,且错误信息极具误导性(如 `number 116 is not a function`);
 
 ### 3.1 版本对照
 
 | libnode.so            | Node.js | ICU | Express                |
 | --------------------- | ------- | --- | ---------------------- |
-| 官方 v18              | v18     | 无  | **4.x**（如 `4.22.2`） |
-| 自编译 v22 + full-icu | v22     | 有  | **5.x**（如 `5.2.1`）  |
+| 官方 v18              | v18     | 无  | **4.x**(如 `4.22.2`) |
+| 自编译 v22 + full-icu | v22     | 有  | **5.x**(如 `5.2.1`)  |
 
-### 3.2 场景 A（v18 + Express 4）
+### 3.2 场景 A(v18 + Express 4)
 
-`nodejs-project/package.json`：
+`nodejs-project/package.json`:
 
 ```json
 {
@@ -191,13 +197,13 @@ strings libnode.so | grep -c icudt78l
 }
 ```
 
-依赖里如有 `\P{ASCII}` 等 Unicode 正则,改写成 ASCII 等价：
+依赖里如有 `\P{ASCII}` 等 Unicode 正则,改写成 ASCII 等价:
 
 | 原写法      | ASCII 写法     |
 | ----------- | -------------- |
 | `\P{ASCII}` | `[^\x00-\x7F]` |
 
-### 3.3 场景 B（v22 + full-icu + Express 5）
+### 3.3 场景 B(v22 + full-icu + Express 5)
 
 ```json
 {
@@ -207,15 +213,16 @@ strings libnode.so | grep -c icudt78l
 }
 ```
 
-**三个前提**：
+**三个前提**:
 
-1. `libnode.so` 确实带 full-icu（用 `strings` 验证过）
-2. **不要**用 `@alloc/path-to-regexp` 替换原版——它的 `exports` 只有 `import` 条件,CJS 下 `require()` 报 `No "exports" main defined`
+1. `libnode.so` 确实带 full-icu(用 `strings` 验证过)
+2. **不要**用 `@alloc/path-to-regexp` 替换原版--它的 `exports` 只有 `import` 条件,CJS 下 `require()` 报 
+   `No "exports" main defined`
 3. **不要**加任何 `overrides` 强制替换 `path-to-regexp`
 
 ### 3.4 Express 5 路由语法迁移
 
-`app.get('*')` 会抛 `TypeError: Missing parameter name`：
+`app.get('*')` 会抛 `TypeError: Missing parameter name`:
 
 | Express 4                    | Express 5                         |
 | ---------------------------- | --------------------------------- |
@@ -234,7 +241,7 @@ npm ls express --all
 npm ls path-to-regexp --all
 ```
 
-**期望（场景 B）**：
+**期望(场景 B)**:
 
 ```
 express@5.2.1
@@ -242,7 +249,7 @@ express@5.2.1
   └── path-to-regexp@8.4.2
 ```
 
-如出现 `@alloc/path-to-regexp`,说明 `package-lock.json` 里有残留 `overrides`;**彻底清理**：
+如出现 `@alloc/path-to-regexp`,说明 `package-lock.json` 里有残留 `overrides`;**彻底清理**:
 
 ```powershell
 Remove-Item -Recurse -Force node_modules, package-lock.json
@@ -251,9 +258,10 @@ npm install
 
 ### 3.6 三个常见误区
 
-- **误区 1**：以为 `@alloc/path-to-regexp` 能解决 ESM 问题 → 它的 `exports` 也是纯 `import`,`require()` 依然失败
-- **误区 2**：只改路由语法就想让 Express 5 跑 → 若 `libnode.so` 无 full-icu,加载 `path-to-regexp@8` 时仍崩
-- **误区 3**：用 `overrides` 强制替换 `path-to-regexp` → 破坏依赖链,且 `package-lock.json` 会残留解析结果,删掉 `overrides` 也不生效
+- **误区 1**:以为 `@alloc/path-to-regexp` 能解决 ESM 问题 → 它的 `exports` 也是纯 `import`,`require()` 依然失败
+- **误区 2**:只改路由语法就想让 Express 5 跑 → 若 `libnode.so` 无 full-icu,加载 `path-to-regexp@8` 时仍崩
+- **误区 3**:用 `overrides` 强制替换 `path-to-regexp` → 破坏依赖链,且 `package-lock.json` 会残留解析结果,删掉 `overrides` 
+  也不生效
 
 ---
 
@@ -275,55 +283,55 @@ $adb = "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe"
 & $adb logcat -d | Select-String 'NODEJS-MOBILE|ReactNativeJS'
 ```
 
-**正常日志**：
+**正常日志**:
 ```
 NODEJS-MOBILE: [node-mobile-app] server URL: http://127.0.0.1:3000
 NODEJS-MOBILE: Express started on port 3000
 ReactNativeJS: Node started on http://127.0.0.1:3000
 ```
 
-**失败日志**：
+**失败日志**:
 ```
 NODEJS-MOBILE: [node-mobile-app] failed: Node 服务 5 秒内未启动 -- 请检查 ./server.js 是否调用了 listen()
 ```
 
-**崩溃日志**：
+**崩溃日志**:
 
 ```powershell
 & $adb logcat -c
 & $adb logcat | Select-String 'FATAL|AndroidRuntime|NODEJS-MOBILE'
 ```
 
-### 4.2 手动清缓存（兜底）
+### 4.2 手动清缓存(兜底)
 
-**正常情况不需要**——CLI 指纹机制自动清;以下仅当指纹判断失效（如手动改过 `node-mobile-app-build/` 内文件）时用：
+**正常情况不需要**--CLI 指纹机制自动清;以下仅当指纹判断失效(如手动改过 `node-mobile-app-build/` 内文件)时用:
 
 ```powershell
-# 最彻底：删整个 RN 工程
+# 最彻底:删整个 RN 工程
 Remove-Item -Recurse -Force D:\你的项目\node-mobile-app-build
 
 # 或删插件 CMake 缓存
 Remove-Item -Recurse -Force D:\你的项目\node_modules\@flun\nodejs-mobile-react-native\android\.cxx
 Remove-Item -Recurse -Force D:\你的项目\node_modules\@flun\nodejs-mobile-react-native\android\build
 
-# 或删指纹文件（下次跑 = 全新构建）
+# 或删指纹文件(下次跑 = 全新构建)
 Remove-Item -Force D:\你的项目\node-mobile-app-build\.build-fingerprint.json
 ```
 
-或直接：
+或直接:
 
 ```powershell
 npx node-mobile-app clean
 ```
 
-### 4.3 手动端口转发（`test` 会自动做）
+### 4.3 手动端口转发(`test` 会自动做)
 
 ```powershell
 & "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" reverse tcp:8081 tcp:8081
 & "$env:LOCALAPPDATA\Android\Sdk\platform-tools\adb.exe" reverse --list
 ```
 
-### 4.4 模拟器（x86_64）
+### 4.4 模拟器(x86_64)
 
 ```powershell
 # 列出 AVD
@@ -333,7 +341,7 @@ npx node-mobile-app clean
 & "$env:LOCALAPPDATA\Android\Sdk\emulator\emulator.exe" -avd Pixel_7_API_34
 ```
 
-**三个必须**：
+**三个必须**:
 - `mobileAppConfig.js` 的 `abiFilters` 含 `x86_64`
 - `libnode/bin/x86_64/libnode.so` 存在
 - 模拟器镜像是 **x86_64 架构**
@@ -342,6 +350,6 @@ npx node-mobile-app clean
 
 ## 相关文档
 
-- [README.md](./README.md) —— 快速开始、配置字段、命令
-- [自定义libnode指南.md](./自定义libnode指南.md) —— 自编译 v22 + full-icu 完整流程
-- [libnode.so 预编译仓库](https://github.com/OpenFlun/nodejs-mobile)（[Gitee](https://gitee.com/OpenFlun/nodejs-mobile)）
+- [README.md](./README.md) -- 快速开始、配置字段、命令
+- [自定义libnode指南.md](./自定义libnode指南.md) -- 自编译 v22 + full-icu 完整流程
+- [libnode.so 预编译仓库](https://github.com/OpenFlun/nodejs-mobile)([Gitee](https://gitee.com/OpenFlun/nodejs-mobile))

package/CHANGELOG.md

@@ -1,12 +1,14 @@
 # 变更日志
-## [4.0.6] - 2026-10-22 16:31
-### 更新
-- 同步升级了一些依赖包;
+## [4.0.8] - 2026-10-26 09:56
+### 修复
+- 修复 `src/copy.js` 中 `out.allowScripts` 赋值语句缺少等号导致的运行时报错 `out.allowScripts is not a function`;
+- 该问题由 4.0.7 版本折行时断点落在等号处、丢失赋值运算符引起;
 
-## [4.0.5] - 2026-10-21 12:10
+## [4.0.7] - 2026-10-25 15:16
 ### 优化
-- 进一步优化 .md 文件;
+- 项目标点已改为以英文标点为主;
+- 行宽改为以 123 为主,部分超宽表格改为了列表;
 
-## [4.0.4] - 2026-10-21 10:02
-### 优化
-- 优化了大量文件细节
+## [4.0.6] - 2026-10-22 16:31
+### 更新
+- 同步升级了一些依赖包;

package/LICENSE

@@ -1,12 +1,17 @@
 ISC 许可证 (ISC License)
 
-版权所有 (c) 2026, flun <open@flun.top>
+Copyright (c) 2026, flun <open@flun.top>
 
-特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人,不受限制地处理本软件的权利,包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件副本的权利,并允许向其提供本软件的人这样做,但须满足以下条件：
+特此免费授予任何获得本软件及相关文档文件("软件")副本的人,不受限制地处理本软件的权利,
+包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件副本的权利,
+并允许向其提供本软件的人这样做,但须满足以下条件:
 
 上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中;
 
-本软件按“原样”提供,不作任何形式的明示或暗示的保证,包括但不限于适销性、特定用途的适用性和不侵权的保证;在任何情况下,作者或版权持有人均不对因本软件或本软件的使用或其他交易而产生的任何索赔、损害或其他责任负责,无论是合同之诉、侵权之诉还是其他行为之诉;
+本软件按"原样"提供,不作任何形式的明示或暗示的保证,
+包括但不限于适销性、特定用途的适用性和不侵权的保证;
+在任何情况下,作者或版权持有人均不对因本软件或本软件的使用或其它交易而产生的
+任何索赔、损害或其它责任负责,无论是合同之诉、侵权之诉还是其它行为之诉;
 
 ---
 
@@ -26,4 +31,4 @@ MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.