@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/harmonyos-pc-resources/references/contribute/develop-guide//351/270/277/350/222/231/345/272/224/347/224/250/345/265/214/345/205/245Node.js/350/277/220/350/241/214/346/227/266-ArkTS/344/270/216Node.js/346/267/267/345/220/210/345/274/200/345/217/221/345/256/236/346/210/230.md

@@ -0,0 +1,748 @@
+# 在鸿蒙应用中嵌入 Node.js 运行时：ArkTS + Node.js 混合开发实战
+
+> 本文是"鸿蒙应用嵌入运行时"系列的第三篇。在 Java（JVM）和 Python（CPython）之后，我们探讨 Node.js 在鸿蒙上的嵌入方案。Node.js v24.13.0 已原生适配鸿蒙平台（`process.platform === 'openharmony'`），拥有完整的 V8 引擎、npm 生态和 Node C API 嵌入能力。与 Python 的 `Python.h` 嵌入方式类似，Node.js 同样可以通过子进程调用或进程内嵌入两种方式集成到鸿蒙应用中，实现应用自包含。
+
+---
+
+## 一、为什么要在鸿蒙上跑 Node.js
+
+除了 Java 和 Python，Node.js 在鸿蒙应用中嵌入也有独特的价值：
+
+| 场景 | 说明 |
+|------|------|
+| **npm 生态复用** | npm 拥有超过 200 万个包，涵盖 HTTP 客户端、数据校验、加密、模板引擎等 |
+| **Web 开发者友好** | 前端/全栈开发者用 JavaScript 即可开发鸿蒙应用后端逻辑 |
+| **高并发 I/O** | Node.js 的事件循环模型天然适合网络请求、文件处理等 I/O 密集型任务 |
+| **同语言栈** | ArkTS 本身就是 TypeScript 的超集，与 JavaScript 无缝衔接，心智负担最低 |
+| **Express/Koa 等框架** | 可在鸿蒙端直接运行本地 HTTP 服务，实现设备端 Web 管理界面 |
+
+---
+
+## 二、鸿蒙上的 Node.js 验证
+
+我们首先在设备上验证 Node.js 的能力：
+
+```
+$ node --version
+v24.13.0
+
+$ node -e "console.log(process.platform)"
+openharmony
+```
+
+**Node.js v24.13.0 已原生适配鸿蒙平台**，`process.platform` 返回 `openharmony`（而非 `linux`）。
+
+### 2.1 版本信息
+
+```
+Node.js:  v24.13.0
+V8:       13.6.233.17
+npm:      11.6.2
+N-API:    10
+libuv:    1.51.0
+OpenSSL:  3.5.4
+ICU:      77.1
+```
+
+### 2.2 标准模块可用性测试
+
+所有核心模块均可用：
+
+| 模块 | 状态 | 说明 |
+|------|------|------|
+| fs | ✅ | 文件系统读写 |
+| http/https | ✅ | HTTP 客户端和服务端 |
+| net | ✅ | TCP/UDP 网络编程 |
+| crypto | ✅ | 加密（SHA256、AES 等均正常） |
+| child_process | ✅ | 子进程执行 |
+| worker_threads | ✅ | 多线程并行 |
+| vm | ✅ | 沙箱执行 JavaScript |
+| stream | ✅ | 流式处理 |
+| tls | ✅ | TLS/SSL |
+| dns | ✅ | DNS 解析 |
+| os | ✅ | 系统信息 |
+| path | ✅ | 路径处理 |
+| assert | ✅ | 断言 |
+| events | ✅ | 事件发射器 |
+| readline | ✅ | 交互式输入 |
+| cluster | ✅ | 多进程集群 |
+| dgram | ✅ | UDP 数据报 |
+| repl | ✅ | 交互式解释器 |
+
+### 2.3 Node.js 运行时组成
+
+将 Node.js 打包进 HAP，需要以下组件：
+
+```
+node-runtime/                          # ~135MB
+├── bin/
+│   └── node           (113MB)         # Node.js 主二进制（ELF aarch64）
+├── lib/
+│   └── node_modules/
+│       └── npm/       (~20MB)         # npm 包管理器
+└── include/
+    └── node/          (~66MB)         # C API 头文件（嵌入方案 B 需要）
+        ├── node.h                     # Node C API 入口
+        ├── node_api.h                 # N-API 接口
+        ├── node_buffer.h              # Buffer API
+        ├── node_object_wrap.h         # 对象包装
+        ├── v8*.h                      # V8 引擎头文件
+        └── uv.h                       # libuv 头文件
+```
+
+---
+
+## 三、整体架构
+
+与 Java、Python 方案一样，Node.js 运行时打包在 HAP 内部，应用完全自包含。
+
+### 方案 A：子进程调用（推荐）
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                HarmonyOS 应用 (.hap)                      │
+│                                                          │
+│  ┌──────────────────────────────────────────┐            │
+│  │  ArkTS 层                                │            │
+│  │  - XXXAbility (应用生命周期)              │            │
+│  │  - Index.ets (UI)                        │            │
+│  └─────────────────┬────────────────────────┘            │
+│                    │ NAPI                                │
+│  ┌─────────────────▼────────────────────────┐            │
+│  │  C++ 桥接层 (libxxxlauncher.so)          │            │
+│  │  - startNode() → fork/exec node app.js  │            │
+│  │  - stopNode() → kill + waitpid          │            │
+│  │  - stdin/stdout 管道通信                  │            │
+│  └─────────────────┬────────────────────────┘            │
+│                    │ fork/exec                           │
+│  ┌─────────────────▼────────────────────────┐            │
+│  │  Node.js 运行时层                         │            │
+│  │  ┌──────────────────────────────────┐    │            │
+│  │  │  node 二进制 (libs/arm64-v8a/)    │    │            │
+│  │  │  + 标准库 + npm + 用户 JS 脚本    │    │            │
+│  │  └──────────────────────────────────┘    │            │
+│  └──────────────────────────────────────────┘            │
+│                                                          │
+│  entry/libs/arm64-v8a/                                   │
+│  ├── node/bin/node             # Node.js 二进制          │
+│  ├── node/lib/node_modules/npm/ # npm + 标准库           │
+│  └── libxxxlauncher.so         # C++ 桥接库              │
+│                                                          │
+│  entry/src/main/resources/resfile/                       │
+│  ├── app.js                   # 用户 JS 脚本             │
+│  └── node_modules/            # npm 三方包               │
+└──────────────────────────────────────────────────────────┘
+```
+
+### 方案 B：进程内嵌入（进阶）
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                HarmonyOS 应用 (.hap)                      │
+│                                                          │
+│  ┌──────────────────────────────────────────┐            │
+│  │  ArkTS 层                                │            │
+│  │  - XXXAbility (应用生命周期)              │            │
+│  └─────────────────┬────────────────────────┘            │
+│                    │ NAPI                                │
+│  ┌─────────────────▼────────────────────────┐            │
+│  │  C++ 桥接层 (libxxxlauncher.so)          │            │
+│  │  - node::CreatePlatform()                │            │
+│  │  - node::LoadEnvironment() → 执行 JS    │            │
+│  │  - 与 ArkTS 共享进程空间                  │            │
+│  └─────────────────┬────────────────────────┘            │
+│                    │ Node C API                          │
+│  ┌─────────────────▼────────────────────────┐            │
+│  │  libnode.so (V8 + libuv + Node.js)       │            │
+│  │  + 标准库 + 用户 JS 脚本                  │            │
+│  └──────────────────────────────────────────┘            │
+└──────────────────────────────────────────────────────────┘
+```
+
+| 方案 | 复杂度 | 通信效率 | 适用场景 |
+|------|--------|---------|---------|
+| A：子进程 | 低 | 中（IPC） | 脚本工具、数据处理、快速原型 |
+| B：进程内嵌入 | 高 | 高（共享内存） | 高频交互、需要与 ArkTS 双向调用 |
+
+---
+
+## 四、项目结构
+
+```
+NodeAppForArkUI/
+├── AppScope/
+│   └── app.json5                         # 应用全局配置
+├── entry/
+│   ├── libs/arm64-v8a/                   # ⭐ 原生库 + Node.js 运行时
+│   │   ├── node/                         # Node.js 运行时（从预编译包复制）
+│   │   │   ├── bin/node                  # node 二进制
+│   │   │   └── lib/node_modules/npm/     # npm + 标准库
+│   │   └── libxxxlauncher.so             # C++ 桥接库
+│   ├── src/main/
+│   │   ├── cpp/
+│   │   │   ├── CMakeLists.txt            # C++ 构建配置
+│   │   │   └── xxxlauncher.cpp           # ⭐ 核心：Node.js 启动器
+│   │   ├── ets/
+│   │   │   ├── ability/
+│   │   │   │   └── XXXAbility.ets        # 应用入口
+│   │   │   └── pages/
+│   │   │       └── Index.ets             # 主页面
+│   │   ├── resources/
+│   │   │   └── resfile/
+│   │   │       ├── app.js                # ⭐ 用户 JS 脚本入口
+│   │   │       ├── package.json          # npm 配置
+│   │   │       └── node_modules/         # npm 三方包
+│   │   └── module.json5
+│   └── build-profile.json5
+└── build-profile.json5
+```
+
+---
+
+## 五、关键配置
+
+### 5.1 module.json5
+
+```json5
+{
+  "module": {
+    "type": "entry",
+    "deviceTypes": ["2in1"],
+    "extractNativeLibs": true,  // ⭐ 必须为 true！node 二进制需要解压到文件系统
+    "abilities": [{
+      "name": "XXXAbility",
+      "srcEntry": "./ets/ability/XXXAbility.ets",
+      "launchType": "specified"
+    }],
+    "requestPermissions": [
+      { "name": "ohos.permission.INTERNET" }
+    ]
+  }
+}
+```
+
+**`extractNativeLibs: true` 是关键配置。** Node.js 的 `node` 二进制需要存在于文件系统上才能被 `fork/exec` 执行。这与 Java 方案中 JVM 的 SO 库需要解压是同样的原理。
+
+### 5.2 build-profile.json5
+
+```json5
+{
+  "buildOption": {
+    "nativeLib": {
+      "collectAllLibs": true  // ⭐ 收集 libs/ 下所有文件到 HAP 包
+    },
+    "externalNativeOptions": {
+      "path": "./src/main/cpp/CMakeLists.txt",
+      "cppFlags": "--std=c++17"
+    }
+  }
+}
+```
+
+`collectAllLibs: true` 确保 `entry/libs/arm64-v8a/` 下的 Node.js 运行时（二进制 + 标准库）都被打包进 HAP。
+
+### 5.3 CMakeLists.txt
+
+```cmake
+cmake_minimum_required(VERSION 3.5.0)
+project(NodeLauncher)
+
+add_library(xxxlauncher SHARED xxxlauncher.cpp)
+target_link_libraries(xxxlauncher PUBLIC libace_napi.z.so libhilog_ndk.z.so)
+
+# 方案 B（进程内嵌入）才需要链接 Node.js 头文件和库：
+# set(NODE_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/thirdparty/include)
+# target_include_directories(xxxlauncher PRIVATE ${NODE_INCLUDE_DIR})
+```
+
+方案 A（子进程）不需要链接 Node.js 的任何头文件或库，只需要 C++ 标准库和 NAPI。
+
+---
+
+## 六、方案 A 实现：子进程调用
+
+### 6.1 xxxlauncher.cpp — Node.js 启动器
+
+```cpp
+#include <string>
+#include <unistd.h>
+#include <sys/wait.h>
+
+// Node.js 二进制和脚本都在应用沙箱内
+static std::string gNodeBinPath = 
+    "/data/storage/el1/bundle/entry/libs/arm64/node/bin/node";
+static std::string gScriptDir = 
+    "/data/storage/el1/bundle/entry/resources/resfile";
+static std::string gNodePath = 
+    "/data/storage/el1/bundle/entry/libs/arm64/node/lib/node_modules";
+static pid_t gNodePid = -1;
+
+// 启动 Node.js 子进程
+int startNodeProcess(const std::string& scriptName) {
+    std::string scriptPath = gScriptDir + "/" + scriptName;
+    
+    pid_t pid = fork();
+    if (pid == 0) {
+        // 子进程：设置环境变量
+        setenv("NODE_PATH", gNodePath.c_str(), 1);
+        
+        // 执行 node scriptPath
+        execl(gNodeBinPath.c_str(), "node", scriptPath.c_str(), NULL);
+        _exit(1);  // exec 失败
+    } else if (pid > 0) {
+        gNodePid = pid;
+        return 0;  // 启动成功
+    }
+    return -1;  // fork 失败
+}
+
+// 停止 Node.js 子进程
+void stopNodeProcess() {
+    if (gNodePid > 0) {
+        kill(gNodePid, SIGTERM);
+        waitpid(gNodePid, NULL, 0);
+        gNodePid = -1;
+    }
+}
+```
+
+**关键设计点：**
+
+1. **自包含路径**：所有路径都指向应用沙箱内部（`/data/storage/el1/bundle/...`），不依赖系统预装的 Node.js
+2. **`NODE_PATH` 环境变量**：指向应用内的 npm 模块路径，让 Node.js 能找到 `node_modules`
+3. **子进程隔离**：Node.js 运行在独立进程中，不会影响 ArkTS 的 UI 线程
+
+### 6.2 NAPI 接口
+
+```cpp
+#include "napi/native_api.h"
+
+static napi_value StartNode(napi_env env, napi_callback_info info) {
+    // 可选：从参数获取脚本名
+    size_t argc = 1;
+    napi_value args[1];
+    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
+    
+    char scriptName[256] = "app.js";  // 默认脚本
+    if (argc > 0) {
+        napi_get_value_string_utf8(env, args[0], scriptName, sizeof(scriptName), nullptr);
+    }
+    
+    int ret = startNodeProcess(scriptName);
+    napi_value result;
+    napi_create_int32(env, ret, &result);
+    return result;
+}
+
+static napi_value StopNode(napi_env env, napi_callback_info info) {
+    stopNodeProcess();
+    return nullptr;
+}
+
+static napi_value Init(napi_env env, napi_value exports) {
+    napi_property_descriptor desc[] = {
+        { "startNode", nullptr, StartNode, nullptr, nullptr, nullptr, napi_default, nullptr },
+        { "stopNode", nullptr, StopNode, nullptr, nullptr, nullptr, napi_default, nullptr },
+    };
+    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
+    return exports;
+}
+
+static napi_module demoModule = {
+    .nm_version = 1,
+    .nm_flags = 0,
+    .nm_filename = nullptr,
+    .nm_register_func = Init,
+    .nm_modname = "xxxlauncher",
+    .nm_priv = ((void*)0),
+    .reserved = { 0 },
+};
+
+extern "C" __attribute__((constructor)) void RegisterModule(void) {
+    napi_module_register(&demoModule);
+}
+```
+
+### 6.3 ArkTS 层
+
+```typescript
+// XXXAbility.ets
+import xxxlauncher from 'libxxxlauncher.so';
+
+export default class XXXAbility extends UIAbility {
+  onWindowStageCreate(windowStage) {
+    windowStage.loadContent('pages/Index');
+    // 启动内嵌的 Node.js 运行时
+    xxxlauncher.startNode('app.js');
+  }
+
+  onDestroy() {
+    xxxlauncher.stopNode();
+  }
+}
+```
+
+```typescript
+// Index.ets
+import xxxlauncher from 'libxxxlauncher.so';
+
+@Entry
+@Component
+struct Index {
+  build() {
+    Column() {
+      Button('启动 Node.js 业务')
+        .onClick(() => xxxlauncher.startNode('app.js'))
+      Button('停止')
+        .onClick(() => xxxlauncher.stopNode())
+    }
+  }
+}
+```
+
+### 6.4 Node.js 脚本
+
+将 Node.js 脚本放入 `resfile` 目录：
+
+```
+entry/src/main/resources/resfile/
+├── app.js              # 业务入口
+├── package.json        # npm 配置
+└── node_modules/       # npm install 产物
+```
+
+```javascript
+// app.js
+const http = require('http');
+const crypto = require('crypto');
+const os = require('os');
+
+console.log(`Node.js ${process.version} on ${process.platform}`);
+
+// 启动本地 HTTP 服务，供 ArkTS 端调用
+const server = http.createServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+        platform: process.platform,   // 'openharmony'
+        arch: process.arch,           // 'arm64'
+        version: process.version,     // 'v24.13.0'
+        uptime: os.uptime(),
+        freemem: os.freemem(),
+        cpus: os.cpus().length
+    }));
+});
+
+server.listen(3456, '127.0.0.1', () => {
+    console.log('Node.js service running on port 3456');
+});
+```
+
+### 6.5 进程间通信
+
+子进程方案需要 IPC 机制传递数据，推荐方式：
+
+| 方式 | 复杂度 | 适用场景 |
+|------|--------|---------|
+| **HTTP 服务** | 低 | 结构化请求-响应，ArkTS 端用 `@ohos.net.http` 调用 |
+| **TCP Socket** | 低 | 双向流式通信 |
+| **stdin/stdout 管道** | 低 | 简单的命令式交互 |
+| **Unix Domain Socket** | 中 | 高频双向通信 |
+| **临时文件** | 最低 | 批量数据传输 |
+
+HTTP 通信示例（最常用）：
+
+```javascript
+// Node.js 端 (app.js)
+const http = require('http');
+const crypto = require('crypto');
+
+const handlers = {
+    '/hash': (body) => ({
+        algorithm: 'sha256',
+        input: body.data,
+        result: crypto.createHash('sha256').update(body.data).digest('hex')
+    }),
+    '/info': () => ({
+        platform: process.platform,
+        version: process.version,
+        memory: process.memoryUsage()
+    })
+};
+
+http.createServer((req, res) => {
+    const handler = handlers[req.url];
+    if (handler) {
+        let body = '';
+        req.on('data', c => body += c);
+        req.on('end', () => {
+            const data = body ? JSON.parse(body) : {};
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(handler(data)));
+        });
+    }
+}).listen(3456, '127.0.0.1');
+```
+
+```typescript
+// ArkTS 端
+import http from '@ohos.net.http';
+
+async function callNodeAPI(path: string, data?: object) {
+    const httpRequest = http.createHttp();
+    const url = `http://127.0.0.1:3456${path}`;
+    const response = await httpRequest.request(url, {
+        method: data ? http.RequestMethod.POST : http.RequestMethod.GET,
+        extraData: data ? JSON.stringify(data) : undefined,
+    });
+    return JSON.parse(response.result as string);
+}
+
+// 调用 Node.js 计算哈希
+const hashResult = await callNodeAPI('/hash', { data: 'hello harmonyos' });
+// hashResult = { algorithm: 'sha256', result: 'a45df...' }
+```
+
+---
+
+## 七、方案 B：进程内嵌入（进阶）
+
+Node.js 提供了完整的 C API（`node.h`），可以在进程内嵌入 V8 + libuv + Node.js 运行时。这与 Python 的 `Python.h` 嵌入方式类似。
+
+### 7.1 嵌入 API 概览
+
+```
+node.h 提供的核心函数：
+├── node::CreatePlatform()           # 创建 V8 平台
+├── node::CommonEnvironmentSetup()   # 创建运行环境
+├── node::LoadEnvironment()          # 加载 Node.js 环境（执行 JS）
+├── node::SpinEventLoop()            # 运行事件循环
+└── node::FreeEnvironment()          # 清理环境
+```
+
+### 7.2 理论嵌入代码
+
+```cpp
+#include <node.h>
+#include <uv.h>
+
+int embedNode(const std::string& scriptPath) {
+    // 1. 初始化 V8 平台
+    std::unique_ptr<node::CommonEnvironmentSetup> setup =
+        node::CommonEnvironmentSetup::Create(
+            uv_default_loop(),
+            node::EnvironmentFlags::kOwnsProcess,
+            [&](const std::vector<std::string>& args,
+                const std::vector<std::string>& exec_args) {
+                // 返回 SnapshotData
+            }
+        );
+
+    // 2. 获取 V8 isolate 和环境
+    v8::Isolate* isolate = setup->isolate();
+    node::Environment* env = setup->env();
+
+    // 3. 加载并执行 Node.js 脚本
+    v8::Locker locker(isolate);
+    v8::Isolate::Scope isolate_scope(isolate);
+    v8::HandleScope handle_scope(isolate);
+    node::LoadEnvironment(env, "require('./app.js')");
+
+    // 4. 运行事件循环
+    node::SpinEventLoop(env).FromJust();
+
+    // 5. 清理
+    setup.reset();
+    return 0;
+}
+```
+
+### 7.3 方案 B 的挑战
+
+| 挑战 | 说明 | 难度 |
+|------|------|------|
+| **SO 化** | Node.js 编译为单文件可执行（113MB ELF），需要编译为共享库 `libnode.so` | 高 |
+| **符号冲突** | V8 引擎和 libuv 的符号可能与鸿蒙 NAPI 运行时冲突 | 高 |
+| **头文件适配** | 嵌入 API 需要 V8 内部头文件，完整编译环境配置复杂 | 中 |
+| **构建工具链** | Node.js 使用 GN/Ninja 构建，与鸿蒙的 CMake 构建体系需要桥接 | 中 |
+
+**建议**：方案 A（子进程）适合大多数场景，且实现简单。方案 B 适合需要高性能 ArkTS ↔ JS 双向调用的深度集成场景，可作为进阶目标。
+
+---
+
+## 八、准备 Node.js 运行时
+
+将 Node.js 打包进 HAP 需要从鸿蒙的 Node.js 预编译包中提取运行时文件。
+
+### 8.1 获取 Node.js 预编译包
+
+鸿蒙平台已有 Node.js 预编译包（hnp 格式），解压后包含完整的 Node.js 运行时：
+
+```bash
+# 系统预装的 Node.js 路径（可作为来源）
+ls /data/service/hnp/node.org/node_v24.13.0/
+# bin/  include/  lib/  share/
+```
+
+### 8.2 复制到 HAP 项目
+
+```
+# 将 Node.js 运行时复制到项目 libs 目录
+cp -r /path/to/node/bin/entry/libs/arm64-v8a/node/bin/
+cp -r /path/to/node/lib/entry/libs/arm64-v8a/node/lib/
+
+# 头文件（仅方案 B 需要）
+cp -r /path/to/node/include/entry/src/main/cpp/thirdparty/include/
+```
+
+最终目录结构：
+
+```
+entry/libs/arm64-v8a/
+├── node/
+│   ├── bin/
+│   │   └── node            # 113MB Node.js 二进制
+│   └── lib/
+│       └── node_modules/
+│           └── npm/         # ~20MB npm + 标准库
+└── libxxxlauncher.so        # C++ 桥接库
+```
+
+### 8.3 npm 三方包安装
+
+在开发机上安装 npm 包，然后复制到 `resfile`：
+
+```bash
+# 在开发机上
+mkdir -p entry/src/main/resources/resfile/
+cd entry/src/main/resources/resfile/
+
+# 初始化并安装依赖
+npm init -y
+npm install express axios lodash uuid
+
+# node_modules 会被打包到 HAP 的 resfile 中
+```
+
+---
+
+## 九、npm 生态与三方包
+
+### 9.1 纯 JavaScript 包
+
+纯 JS 包（不包含 native 模块）可以直接使用：
+
+| 包 | 用途 | 类型 |
+|----|------|------|
+| lodash | 工具函数库 | 纯 JS |
+| express / koa | HTTP 框架 | 纯 JS |
+| axios | HTTP 客户端 | 纯 JS |
+| uuid | UUID 生成 | 纯 JS |
+| dayjs | 日期处理 | 纯 JS |
+| yaml / js-yaml | YAML 解析 | 纯 JS |
+| handlebars | 模板引擎 | 纯 JS |
+| marked | Markdown 解析 | 纯 JS |
+
+### 9.2 含 Native 模块的包
+
+包含 C/C++ 原生模块的包（如 `sharp`、`bcrypt`）需要为鸿蒙 aarch64 重新编译。大多数常用包都提供了纯 JS fallback。
+
+### 9.3 NODE_PATH 配置
+
+在 C++ 启动器中通过 `setenv("NODE_PATH", ...)` 指定模块搜索路径：
+
+```cpp
+// 标准库路径（应用内）
+setenv("NODE_PATH", 
+    "/data/storage/el1/bundle/entry/libs/arm64/node/lib/node_modules",
+    1);
+```
+
+Node.js 的 `require()` 会自动搜索 `NODE_PATH` 下的模块。
+
+---
+
+## 十、与 Java、Python 方案对比
+
+| 维度 | Node.js 方案 | Python 方案 | Java 方案 |
+|------|-------------|-------------|----------|
+| **运行时大小** | 大（node 二进制 113MB + npm ~20MB） | 小（libpython ~5MB + 标准库） | 大（libjvm ~13MB + JRE ~108MB） |
+| **平台适配度** | ⭐ 最高（`process.platform=openharmony`） | 中（需配置 PYTHONHOME） | 低（需 ELF 签名等额外工作） |
+| **启动速度** | 快（V8 编译执行） | 快（解释执行） | 慢（JVM 启动） |
+| **嵌入复杂度** | 方案A低/方案B高 | 低（Python C API） | 高（NAPI+JNI） |
+| **三方库生态** | npm（200万+包） | PyPI | Maven Central |
+| **与 ArkTS 语言亲和度** | ⭐ 最高（都是 JavaScript） | 低（跨语言） | 低（跨语言） |
+| **运行时性能** | 高（V8 JIT） | 低（解释执行） | 高（JIT） |
+| **C 扩展兼容** | 需要为鸿蒙编译 | 需要为鸿蒙编译 | 需要为鸿蒙编译 + 签名 |
+
+**Node.js 的独特优势：**
+
+1. **原生平台适配**：`process.platform === 'openharmony'`，是三种运行时中唯一被官方识别的鸿蒙平台
+2. **语言栈统一**：ArkTS 是 TypeScript 的超集，JavaScript 开发者零门槛
+3. **方案 A 极简**：子进程调用只需 `fork/exec`，无需链接任何 Node.js 库
+4. **V8 引擎性能**：JIT 编译，长期运行性能接近 Java，远超 Python
+
+---
+
+## 十一、注意事项
+
+### 11.1 文件路径
+
+所有路径都指向应用沙箱内部，应用完全自包含：
+
+```
+/data/storage/el1/bundle/entry/libs/arm64-v8a/node/    # Node.js 运行时
+/data/storage/el1/bundle/entry/resources/resfile/       # JS 脚本和 node_modules
+/data/storage/el2/base/haps/entry/files/                 # 可读写目录
+```
+
+### 11.2 包体积优化
+
+Node.js 运行时约 135MB，可通过以下方式优化：
+
+| 优化项 | 节省 | 说明 |
+|--------|------|------|
+| 移除 npm | ~20MB | 如果不需要运行时安装包 |
+| 移除 include/ | ~66MB | 仅方案 B 需要 |
+| strip 调试符号 | ~50MB | `strip` 命令去掉 debug_info |
+| 裁剪标准库 | 可变 | 移除不用的内置模块 |
+
+### 11.3 process.platform 差异
+
+```javascript
+process.platform   // 'openharmony'（不是 'linux'！）
+process.arch       // 'arm64'
+```
+
+如果 npm 包内部使用 `process.platform === 'linux'` 判断，可能需要 patch。
+
+### 11.4 ELF 签名
+
+Node.js 二进制是 ELF 可执行文件，在鸿蒙上运行可能需要签名。如果签名校验导致执行失败，需要使用 `binary-sign-tool` 进行自签名。
+
+### 11.5 extractNativeLibs
+
+`module.json5` 中必须设置 `extractNativeLibs: true`，否则 `node` 二进制不会被解压到文件系统，`fork/exec` 无法执行。
+
+---
+
+## 十二、总结
+
+通过将 Node.js 运行时打包进 HAP，可以实现**自包含的 ArkTS + Node.js 混合开发模式**。
+
+**核心优势：**
+
+1. **原生平台适配**：Node.js v24.13.0 已原生适配鸿蒙，29 个核心模块全部可用
+2. **语言栈统一**：ArkTS 和 JavaScript 同源，开发者零门槛
+3. **嵌入极简**：方案 A 只需 `fork/exec` + IPC，无需链接 Node.js 库
+4. **npm 生态**：200 万+ 纯 JS 包开箱即用
+5. **V8 性能**：JIT 编译，长期运行性能出色
+
+**方案选择：**
+
+| 需求 | 推荐方案 |
+|------|---------|
+| 快速运行 JS 脚本/工具 | 方案 A（子进程 + HTTP IPC） |
+| 需要 npm 包支持 | 方案 A + resfile 中的 node_modules |
+| 高频 ArkTS ↔ JS 交互 | 方案 B（进程内嵌入，需编译 libnode.so） |
+
+结合本系列三篇文章，开发者可以根据场景灵活选择 Java、Python 或 Node.js 作为鸿蒙应用的嵌入式运行时，扩展鸿蒙开发模式的边界。