node-simctl

中文文档
9.1.2发布于 2026/11/04Apache-2.0TypeScriptES Module构建来源已验证

包装苹果的simctl二进制文件

中文使用文档
文档目录5 节
  1. node-simctl
  2. 安装
  3. API
  4. 高级用法
  5. 在一台计算机上运行多个模拟器sdk

node-simctl

NPM version Downloads

Release

ES6/7节点围绕苹果的包装 simctl binary,“控制iOS模拟器的命令行实用程序”。 simctl 的子命令运行 xcrun

安装

安装在 npm。

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 方法,该方法接受子命令本身 作为第一个参数和一组选项,其中可能包含额外的命令参数, 环境变量、编码等。例如:

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());

看到 规格 举例说明用法。

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

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

读到这 MacOps文章 了解更多详情。

版本与发布记录

node-simctl 共发布 183 个版本,首次发布于 2014/12/05;过去 12 个月发布了 26 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
9.1.2latest2026/11/04今天
9.1.12026/07/273 个月前
9.1.02026/07/263 个月前
9.0.02026/07/253 个月前
8.2.92026/07/153 个月前
8.2.82026/07/064 个月前

关于 node-simctl 的常见问题

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 和提交记录判断。