# node-simctl 中文文档

规范地址：https://npmcn.com/package/node-simctl/

版本：9\.1\.2
npm 元数据更新时间：2026-11-04T07:05:43.255Z
中文译文更新时间：2026-11-04T07:53:42.424Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/node-simctl
原文对照：https://npmcn.com/package/node-simctl/?lang=original
项目主页：https://github.com/appium/node-simctl#readme
源码仓库：https://github.com/appium/node-simctl

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

- 包体积（解压后）：258 kB，154 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| ^22\.12\.0 \|\| \>=24\.0\.0
- 运行依赖：6 个
- 首次发布：2014-12-04T23:26:40.462Z
- 最新版本发布：2026-11-04T07:05:42.902Z
- 已发布版本数：183（近 12 个月 26 个）

## 中文简介

包装苹果的simctl二进制文件

## 安装

```sh
npm install node-simctl
```

也可以使用：`pnpm add node-simctl`、`yarn add node-simctl`、`bun add node-simctl`

## README

## node-simctl

[![NPM version](http://img.shields.io/npm/v/node-simctl.svg)](https://npmjs.org/package/node-simctl) [![Downloads](http://img.shields.io/npm/dm/node-simctl.svg)](https://npmjs.org/package/node-simctl)

[![Release](https://github.com/appium/node-simctl/actions/workflows/publish.js.yml/badge.svg?branch=master)](https://github.com/appium/node-simctl/actions/workflows/publish.js.yml)

ES6/7节点围绕苹果的包装 `simctl` binary，“控制iOS模拟器的命令行实用程序”。 `simctl` 的子命令运行 [xcrun](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/xcrun.1.html)

### 安装

安装在 [npm](https://www.npmjs.com/package/node-simctl)。

```
npm install node-simctl
```

### API

模块导出单个类 `Simctl`． 这个类包含方法 它封装了以下simctl子命令：

#### create（创建新设备）

-   createDevice `*`

#### 克隆（克隆现有设备）

_无_

#### 升级（将设备升级到更新的运行时）

_无_

#### delete（删除指定设备、删除不可用设备、删除所有设备）

-   deleteDevice

#### pair（创建一个新的手表和手机对）

_无_

#### 解除配对（解除手表和手机配对）

_无_

#### pair\_activate（将给定的一对设置为活动的）

_无_

#### 擦除（擦除设备的内容和设置）

-   eraseDevice

#### boot（启动设备）

-   bootDevice

#### shutdown（关闭设备）

-   shutdownDevice

#### rename（重命名设备）

_无_

#### getenv（从运行的设备打印环境变量）

-   采用

#### openurl（在设备中打开URL）

-   openUrl

#### addmedia（将照片、实时照片、视频或联系人添加到设备库）

-   addMedia

#### install（在设备上安装应用程序）

-   installApp

#### 卸载（从设备上卸载应用程序）

-   uninstallApp

#### get\_app\_container（打印已安装应用的容器路径）

-   getAppContainer

#### 启动（通过设备上的标识符启动应用程序）

-   launchApp

#### terminate（通过设备上的标识符终止应用程序）

-   terminateApp

#### spawn（通过在设备上执行一个给定的可执行文件来生成一个进程）

-   spawnProcess
-   spawnSubProcess

#### list（列出可用设备、设备类型、运行时或设备对）

-   getDevicesByParsing `*`
-   getDevices `*`
-   getRuntimeForPlatformVersionViaJson `*`
-   getRuntimeForPlatformVersion `*`
-   getDeviceTypes `*`
-   列表 `*`

#### icloud\_sync（触发设备上的iCloud同步）

_无_

#### pbsync（从一个粘贴板到另一个粘贴板同步内容）

_无_

#### pbcopy（将标准输入复制到设备粘贴板上）

-   setPasteboard

#### pbpaste（将设备的粘贴板的内容打印到标准输出）

-   getPasteboard

#### help（打印给定子命令的用法）

_无_

#### 设置设备io操作

-   getScreeenshot

#### diagnostic（收集诊断信息和日志）

_无_

#### 日志详细信息（启用或禁用设备的详细日志记录）

_无_

#### status\_bar（设置或清除状态栏覆盖）

_无_

#### ui（获取或设置ui选项）

-   getAppearance
-   setAppearance

#### 推送（发送模拟推送通知）

-   pushNotification

#### 隐私（授予、撤销或重置隐私和权限）

-   grantPermission
-   revokePermission
-   resetPermission

#### keychain（操作设备的钥匙链）

-   addRootCertificate
-   addCertificate
-   resetKeychain

#### appinfo(无证)

-   appInfo

#### bootstatus(无证)

-   startBootMonitor

方法用星号(`*`)字符 _不_ 要求 `udid` 属性设置 在 `Simctl` 实例。所有其他方法 _抛出错误_ 如果 `udid` 属性在调用时未设置。

所有公共方法都提供了描述其参数和返回值的文档字符串。

这个 `Simctl` 类构造函数支持以下选项：

-   `xcrun` （对象）：xrun属性。目前只有一个属性 是支持的，是什么 `path` 默认情况下包含 `null`，它强制执行 要自动检测其完整路径的实例 `xcrun` 工具和投掷 如果无法检测到，则表示异常。如果路径是在创建实例时设置的 然后它会被 `exec` 并且不会发生自动检测。
-   `execTimeout` （number\[600000\]）：最大毫秒数 等待单个同步的xcrun命令。
-   `logErrors` （boolean\[true\]）：是否写入xrun错误消息 在将它们作为错误抛出之前，将它们放入调试日志中。
-   `udid` （string\[null\]）：当前设备的唯一标识符，为 将隐式传递给所有需要它的方法（见上文）。它可以被设置 在实例创建时（如果已经知道）或稍后在需要时（如果需要）通过相应的 setter。
-   `devicesSetPath` （string\[null\]）：要管理的设备集的全路径。 默认情况下，此路径通常等于~/Library/Developer/CoreSimulator/Devices。这个选项 有一个getter和一个setter，允许在多个设备集之间切换Simctl 实例生命周期。

### 高级用法

任何simctl子命令都可以通过 `exec` 方法，该方法接受子命令本身 作为第一个参数和一组选项，其中可能包含额外的命令参数， 环境变量、编码等。例如:

```js
import Simctl from 'node-simctl';

const simctl = new Simctl();
const name = 'My Device Name';
simctl.udid = await simctl.createDevice(name, 'iPhone X', '13.3');
await simctl.bootDevice();
await simctl.startBootMonitor({timeout: 120000});
await simctl.exec('pbsync');
console.log(`Pasteboard content: ${await simctl.getPasteboard()}`);
const {stdout} = await simctl.exec('status_bar', {
  args: [simctl.udid, 'list']
});
console.log(output);
simctl.udid = void(await simctl.deleteDevice());
```

看到 [规格](https://npmcn.com/package/node-simctl/test/simctl-specs.js) 举例说明用法。

### 在一台计算机上运行多个模拟器sdk

可以在一台机器上使用不同的Xcode sdk运行多个模拟器。 只需将适当的值设置为 `DEVELOPER_DIR` 每个进程的环境变量。

读到这 [MacOps文章](https://macops.ca/developer-binaries-on-os-x-xcode-select-and-xcrun/) 了解更多详情。

## 常见问题

### node-simctl 是什么？

包装苹果的simctl二进制文件

### 如何安装 node-simctl？

在项目目录运行 npm install node-simctl，或使用 pnpm add / yarn add / bun add。

### node-simctl 支持 TypeScript 吗？

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

### node-simctl 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### node-simctl 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19\.0 \|\| ^22\.12\.0 \|\| \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### node-simctl 可以商用吗？

node-simctl 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### node-simctl 还在维护吗？

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