# @capawesome/capacitor-nodejs 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-nodejs/

版本：0\.2\.0
npm 元数据更新时间：2026-10-15T12:12:56.120Z
中文译文更新时间：2026-11-09T10:34:51.042Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-nodejs
原文对照：https://npmcn.com/package/%40capawesome/capacitor-nodejs/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/nodejs/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：137 kB，51 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-05T18:00:21.020Z
- 最新版本发布：2026-10-15T12:12:55.703Z
- 近 30 天下载量：2898（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

在Android和iOS上的移动应用程序中运行Node.js的Capacitor插件.

## 安装

```sh
npm install @capawesome/capacitor-nodejs
```

也可以使用：`pnpm add @capawesome/capacitor-nodejs`、`yarn add @capawesome/capacitor-nodejs`、`bun add @capawesome/capacitor-nodejs`

## README

# 电容节点.js插件

用于运行的电容插件 [节点.js](https://nodejs.org/) 在移动应用程序中。\[^1\]\[^2\]

[![Thousands of teams ship faster with Capawesome Cloud Native Builds and Live Updates](https://capawesome.io/assets/banners/cloud-teams-ship-faster-with-capacitor.png)](https://capawesome.io/)

## 特征

Capacitor Node.js插件是Capacitor apps中运行Node.js最完整的解决方案之一. 以下是一些关键特征:

-   🖥️ **跨平台**: 支持Android和iOS.
-   🚀 **节点.js 运行时间**: 基于 [移动应用程序的节点.js](https://github.com/nodejs-mobile/nodejs-mobile)。 。 。 .
-   🧵 **背景线程**:在专用背景线上运行节点.js引擎以避免阻塞UI.
-   🔁 **双向通信**:基于事件的信息在Capacitor app和Node.js运行时间之间传递.
-   📦 **npm 生态系统**: 使用不兼容浏览器并依赖Node.js核心模块的npm包.
-   🛠️ **可配置**:以自定义参数,环境变量和脚本自动或手动启动节点.js运行时间.
-   🤝 **兼容性**: 与 [背景任务](https://capawesome.io/docs/sdks/capacitor/background-task/), (中文(简体) ), [SQL 点](https://capawesome.io/docs/sdks/capacitor/sqlite/) 财务报告和审定财务报表 [齐普](https://capawesome.io/docs/sdks/capacitor/zip/) 插件 .
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

节点Js插件通常在应用程序需要只有节点Js生态系统提供的功能时使用,例如:

-   **仅节点.js 库**: 使用不兼容浏览器的npm包,因为它们依赖于Node.js核心模块.
-   **代码再使用**:在您的移动应用程序中重新使用已存在的Node.js代码,而不是为浏览器重写.
-   **背景处理**: 卸载重活到Node.js引擎,该引擎运行在专用背景线上而不会阻断UI.
-   **当地数据处理**: 使用 Node.js runtime提供的可写目录处理和坚持设备数据.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.0.x (韩语) | \>=8.x.x | 积极支持 |

## 演示

可以找到一个实例 [这里](https://github.com/capawesome-team/capacitor-plugins/tree/main/packages/nodejs/example)。 。 。 .

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-nodejs` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capawesome/capacitor-nodejs
npx cap sync
```

**请注意**: 此插件嵌入 [移动应用程序的节点.js](https://github.com/nodejs-mobile/nodejs-mobile) 运行时间 二进制 。 二进制不包含在npm软件包中,而是按要求下载:Android二进制由Gradle架构下载,iOS二进制期间下载 `npm install` (只在macOS上). 设定 `CAPACITOR_NODEJS_SKIP_DOWNLOAD` 环境变量改为 `1` 以跳过 iOS 下载.

### 机器人

#### 变量

如果需要, 您可以在您的应用程序中定义以下工程变量 `variables.gradle` 要使用不同运行时间二进制的文件 :

-   `$nodejsMobileAndroidUrl` 下载 Android 运行时二进制的 URL( 默认: GitHub 发布) `18.20.4-capawesome.3`页:1 [16 KB 页面大小兼容构建](https://github.com/capawesome-team/nodejs-mobile/releases)(中文(简体) )
-   `$nodejsMobileAndroidSha256` Android 运行时二进制下载的 SHA-256 检查和( 默认: 检查和默认下载)

### iOS系统

此插件目前仅支持 **Swift 软件包管理器**. CocoaPods 不支持 .

如果安装有已禁用生命周期脚本的依赖性(例如. `npm install --ignore-scripts`),iOS运行时二进制不自动下载. 在此情况下, 在构建您的应用程序前手动运行下载脚本 :

```bash
node node_modules/@capawesome/capacitor-nodejs/scripts/postinstall.js
```

## 配置

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`nodeDir`** | `string` | 相对于 Capacitor 的 Node.js 项目目录 `webDir`。只在Android和iOS上提供. | `'nodejs'` | 0.0.1 资源 |
| **`startMode`** | `'manual' | 'auto'` | 节点.js运行时间的启动模式. 如果设置为 `auto`,当应用程序启动时,节点.js运行时间会自动启动. 如果设置为 `manual`时,必须使用 `start(...)` 方法。 仅在Android和iOS上提供. | `'auto'` | 0.0.1 资源 |

### 实例

单位 `capacitor.config.json`数字 :

```json
{
  "plugins": {
    "Nodejs": {
      "nodeDir": 'custom-nodejs',
      "startMode": 'manual'
    }
  }
}
```

单位 `capacitor.config.ts`数字 :

```ts
/// <reference types="@capawesome/capacitor-nodejs" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    Nodejs: {
      nodeDir: 'custom-nodejs',
      startMode: 'manual',
    },
  },
};

export default config;
```

## 使用量

以下例子展示了如何设置Node.js项目,在Node.js和Capacitor app之间沟通,手动启动运行时间,等待其准备,并与它交换消息.

### 建立Node.js项目

插件运行位于 `nodejs` 目录(参见 `nodeDir` 配置选项) `webDir`。确保您的网页将 Node.js 项目输出到此目录,例如将其放置在 `public` 您的网络工程目录 :

```
my-app
├── capacitor.config.json   // webDir: 'dist'
└── src
    └── public
        └── nodejs
            ├── package.json
            └── index.js
```

这个 `package.json` node.js 工程的文件定义了要运行的脚本文件 `main` 字段 :

```json
{
  "name": "nodejs-project",
  "version": "1.0.0",
  "main": "index.js"
}
```

### 与来自Node.js的 Capacitor app 通信

脚本文件内部( E)`index.js` 在此例子中 `bridge` 模块为 Capacitor app 提供通信通道:

```js
const { app, channel } = require('bridge');

// Receive messages from the Capacitor app.
channel.on('my-event', (...args) => {
  // Send messages to the Capacitor app.
  channel.post('my-response', 'Hello from Node.js!');
});

// Get a writable directory for persistent file storage.
const dataDir = app.datadir();

// Listen for app lifecycle events.
app.on('pause', pauseLock => {
  pauseLock.release();
});
app.on('resume', () => {});
```

**请注意**:Node.js项目目录可能在应用程序更新期间被覆盖. 在返回的目录中存储持久性数据 `app.datadir()`。 。 。 .

### 手动启动节点运行时间

默认情况下,"节点"(Node.js runtime)在应用程序启动后自动启动. 如果 `startMode` 配置选项设置为 `manual`,从自定义参数、环境变量和脚本开始:

```typescript
import { Nodejs } from '@capawesome/capacitor-nodejs';

const start = async () => {
  // Only available if the `startMode` configuration option is set to `manual`.
  await Nodejs.start({
    args: ['--option', 'value'],
    env: { MY_ENV_VAR: 'value' },
    script: 'custom-main.js',
  });
};
```

### 等待节点运行时间准备好

节点js运行时间在节点js项目要求完成后即被视为已准备好 `bridge` 模块。 检查当前状态为 `isReady()` 或听为 `ready` 事件:

```typescript
import { Nodejs } from '@capawesome/capacitor-nodejs';

const isReady = async () => {
  const { ready } = await Nodejs.isReady();
  return ready;
};

const addReadyListener = async () => {
  await Nodejs.addListener('ready', () => {
    console.log('The Node.js runtime is ready.');
  });
};
```

### 与 Node.js 运行时间交换消息

一旦Node.js的运行时间准备好,就向它发送消息,并收听从它收到的消息:

```typescript
import { Nodejs } from '@capawesome/capacitor-nodejs';

const send = async () => {
  await Nodejs.send({
    eventName: 'my-event',
    args: ['Hello from Capacitor!'],
  });
};

const addMessageListener = async () => {
  await Nodejs.addListener('message', event => {
    console.log('Received message:', event.eventName, event.args);
  });
};
```

### 使用 npm 软件包

要使用 npm 软件包, 请运行 `npm install --omit=dev` 在构建您的网络项目之前, 在 Node.js 项目目录中 。 建议将Node.js项目捆绑成一个文件(例如: [兴建](https://esbuild.github.io/))改善起步时间.

## API 密码

-   [`isReady()`](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-isready)
-   [`send(...)`](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-send)
-   [`start(...)`](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-start)
-   [`addListener('message', ...)`](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-addlistenermessage-)
-   [`addListener('ready', ...)`](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-addlistenerready-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-type-aliases)

### 已读取( E)

```typescript
isReady() => Promise<IsReadyResult>
```

检查Node.js运行时间是否准备好接收消息 .

节点js运行时间在节点js项目完成后即被视为就绪 已经要求 `bridge` 模块.

仅在Android和iOS上提供.

**回返情况:** `Promise<[IsReadyResult](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-isreadyresult)>`

**自:** 0.0.1 资源

* * *

### 发送(...)

```typescript
send(options: SendOptions) => Promise<void>
```

发送消息给节点.js运行时间.

这种方法只有在Node.js运行时间准备好时才可用. 使用 `isReady()` 方法或该方法 `ready` 检查是否为 节点.js运行时间准备好了.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[SendOptions](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-sendoptions)` |

**自:** 0.0.1 资源

* * *

### 启动(...)

```typescript
start(options?: StartOptions | undefined) => Promise<void>
```

手动启动节点运行时间 .

只有在 `startMode` 配置选项 设置为 `manual`。 。 。 .

**请注意**: 节点 发射 不支持停止并重新启动 Node.js 运行时间 .

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[StartOptions](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-startoptions)` |

**自:** 0.0.1 资源

* * *

### 添加 listener('message',...)

```typescript
addListener(eventName: 'message', listenerFunc: (event: MessageEvent) => void) => Promise<PluginListenerHandle>
```

当收到Node.js运行时间发来的消息时调用.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'message'` |
| **`listenerFunc`** | `(event: [MessageEvent](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-messageevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-pluginlistenerhandle)>`

**自:** 0.0.1 资源

* * *

### 添加倾听器( 已准备好,...)

```typescript
addListener(eventName: 'ready', listenerFunc: () => void) => Promise<PluginListenerHandle>
```

当Node.js运行时间准备好接收消息时调用.

仅在Android和iOS上提供.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'ready'` |
| **`listenerFunc`** | `() => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-pluginlistenerhandle)>`

**自:** 0.0.1 资源

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除此插件的所有听众 .

**自:** 0.0.1 资源

* * *

### 接口

#### 正在读取结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`ready`** | `boolean` | 节点.js运行时间是否准备好接收消息. | 0.0.1 资源 |

#### 发送选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`args`** | `MessageArg[]` | 要发送到 Node.js 运行时的参数 . | 0.0.1 资源 |
| **`eventName`** | `string` | 发送到 Node.js 运行时间的事件名称 . | 0.0.1 资源 |

#### 开始选项

| Prop | 类型 | 说明 | 默认 | 自兹 |
| --- | --- | --- | --- | --- |
| **`args`** | `string[]` | 传递给Node.js进程的论点. |  | 0.0.1 资源 |
| **`env`** | `{ [key: string]: string; }` | 为Node.js进程设置的环境变量. |  | 0.0.1 资源 |
| **`script`** | `string` | 运行的脚本文件的路径,相对于节点.js项目目录. | ``The `main` field of the `package.json` file of the Node.js project.`` | 0.0.1 资源 |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 信件事件

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`args`** | `MessageArg[]` | 从Node.js运行时收到的论据. | 0.0.1 资源 |
| **`eventName`** | `string` | 活动名称从Node.js runtime收到. | 0.0.1 资源 |

### 类型异名

#### 信件标记

与 Node.js 运行时交换消息的单个参数 .

价值必须是JSON的可连载性.

`string | number | boolean | null | MessageArg[] | { [key: string]: [MessageArg](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-messagearg) }`

## 限制

基础 [移动应用程序的节点.js](https://github.com/nodejs-mobile/nodejs-mobile) 运行时间有一些限制,您应该知道:

-   **单一实例**:Node.js运行时间只能在每次应用发布后启动. 不支持停止和重新启动运行时间 .
-   **无儿童流程**编号: `child_process` 在移动平台上不支持模块.
-   **IOS上没有JIT**: 在iOS上,JavaScript引擎运行时只使用解释器模式(没有JIT编译),这导致JavaScript执行比Android慢.
-   **应用程序大小**:嵌入Node.js runtime使应用程序大小每CPU架构增加数十兆字节.
-   **原生添加剂**: Node.js 原生添加剂只有在作为预建物提供时才在Android上得到支持(见 [`node-gyp-build`](https://github.com/prebuild/node-gyp-build))用于目标建筑.
-   **`process.exit()`**调用 `process.exit()` app Store准则不允许这样做.

## 财务问题

### 支持哪个节点.js版本 ?

该插件目前运行节点.js `18.20.4`,最新版本可从 [移动应用程序的节点.js](https://github.com/nodejs-mobile/nodejs-mobile). 支持更新的Node.js版本需要自建的移动平台运行时间二进制,我们正在对此进行评估.

### 为什么没有 `stop()` 方法吗?

基本的运行时间只支持每个应用启动一个单一的Node.js实例,并且没有提供API来阻止或重启. A 类 `stop()` 因此,方法会让应用程序处于Node.js在应用程序重新启动前永远无法启动的状态. 如果您需要在节点运行时停止工作,请发送信息(例如 a) `shutdown` )并让您的节点.js代码停止它的服务器和定时器。 闲置的运行时间消耗的资源微不足道.

### 在Node.js项目中,我应该在哪里存储持续的数据?

在返回的目录中存储持久性数据 `app.datadir()` 内置 `bridge` 模块。 节点.js工程目录本身可能在应用更新期间被覆盖,所以那里所写的任何文件都可以丢失.

### 为什么JavaScript执行iOS比Android慢?

在iOS上,JavaScript引擎在没有JIT编译的情况下只以解释器模式运行,这导致JavaScript执行比Android慢. 这是对移动Apps运行时间的基本节点.js的限制. 见 [限制](https://npmcn.com/package/%40capawesome/capacitor-nodejs/#readme-limitations) 详细情况.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [背景任务](https://capawesome.io/docs/sdks/capacitor/background-task/): 在您的 Capacitor app 中运行背景任务 .
-   [SQL 点](https://capawesome.io/docs/sdks/capacitor/sqlite/): 访问 SQLite 数据库,支持加密,交易和计划迁移.
-   [齐普](https://capawesome.io/docs/sdks/capacitor/zip/): Zip和unzip文件和目录.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nodejs/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/nodejs/LICENSE)。 。 。 .

嵌入式Node.js运行时间及其捆绑的依赖(V8, OpenSSL, ICU, libuv等)根据自己的许可证进行分配. 见 [节点Js许可证](https://github.com/capawesome-team/nodejs-mobile/blob/main/LICENSE)。 。 。 .

\[^1\]: 本项目不附属于OpenJS基金会或其任何子公司或子公司,不获其认可、赞助或批准. \[^2\]: `Node.js` 是OpenJS基金会的注册商标.

## 常见问题

### @capawesome/capacitor-nodejs 是什么？

在Android和iOS上的移动应用程序中运行Node\.js的Capacitor插件\.

### 如何安装 @capawesome/capacitor-nodejs？

在项目目录运行 npm install @capawesome/capacitor-nodejs，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capawesome/capacitor-nodejs 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capawesome/capacitor-nodejs 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capawesome/capacitor-nodejs 可以商用吗？

@capawesome/capacitor-nodejs 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-nodejs 的下载量有多少？

根据 npm 官方下载统计，@capawesome/capacitor-nodejs 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,898 次，日均约 97 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capawesome/capacitor-nodejs 还在维护吗？

最新版本 0\.2\.0 发布于 2026/10/15（24 天前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/07/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。