简介

跨进程通信管理器。负责创建、管理和终止外部子进程（Go/Python/Java 后端），支持动态端口分配和双索引追踪（pid 和 name）。包括 Cross 类（管理器）、CrossProcess 类（单进程实例）和 cross 单例。

重要

跨进程 API 仅在主进程中可用。不能在子进程（jobs）或渲染进程中使用。

导入

// CJS
const { cross, Cross, CrossProcess } = require('ee-core/cross');

// ESM
import { cross, Cross, CrossProcess } from 'ee-core/cross';

// 类型（CJS / ESM）
import type { CrossRunOptions, CrossProcessOptions, CrossHost, CrossTargetConfig } from 'ee-core/cross';
// 或
import type { CrossTargetConfig } from 'ee-core/types';

API

Cross 类

Cross 类是跨进程管理器。实现了 CrossHost 接口，为子进程提供事件通知能力。通过 children（pid 索引）和 childrenMap（name 索引）双索引管理进程，支持按 pid 或 name 操作。

---

cross.create()

说明：创建并启动配置中 enable=true 的所有跨进程服务。遍历 config.cross 配置，为每个 enable=true 的服务调用 run()。

返回值：Promise<void>

示例：

import { cross } from 'ee-core/cross';
await cross.create();

参见：cross.run()

---

cross.run(service, opt)

说明：运行指定的跨进程服务。合并配置默认值与运行时选项，如指定则动态分配端口，创建 CrossProcess 子进程，并将其注册到 pid 和 name 双索引中。如果存在重复的服务名，追加 pid 后缀以避免冲突。

参数：

参数	类型	必填	说明
service	string	是	服务名（config.cross 中的键）
opt	CrossRunOptions	否	覆盖配置默认值的运行时选项

返回值：Promise<CrossProcess> — 创建的子进程实例

抛出：当服务配置不存在于 config.cross 时抛出 Error

示例：

import { cross } from 'ee-core/cross';
import { getExtraResourcesDir } from 'ee-core/ps';
import path from 'path';

// 使用配置默认值运行
const entity = await cross.run('go');

// 使用运行时覆盖选项运行
const opt = {
  name: 'goapp',
  cmd: path.join(getExtraResourcesDir(), 'goapp'),
  directory: getExtraResourcesDir(),
  args: ['--port=7073'],
  appExit: true,
};
const entity = await cross.run('go', opt);

---

cross.kill(pid)

说明：按 pid 终止子进程。

参数：

参数	类型	必填	说明
pid	string | number	是	进程 ID

返回值：void

---

cross.killByName(name)

说明：按 name 终止子进程。

参数：

参数	类型	必填	说明
name	string	是	服务名

返回值：void

---

cross.killAll()

说明：终止所有子进程。

返回值：void

示例：

cross.killAll();

---

cross.getUrl(name)

说明：获取指定服务的 URL。

参数：

参数	类型	必填	说明
name	string	是	服务名

返回值：string | undefined — 服务 URL（如 http://127.0.0.1:7070），进程不存在时返回 undefined

示例：

const url = cross.getUrl('goServer');
// http://127.0.0.1:7070

---

cross.getProcByName(name)

说明：按 name 获取 CrossProcess 实例。

参数：

参数	类型	必填	说明
name	string	是	服务名

返回值：CrossProcess — 进程实例

抛出：当指定 name 的进程不存在时抛出 Error

---

cross.getProc(pid)

说明：按 pid 获取 CrossProcess 实例。

参数：

参数	类型	必填	说明
pid	string | number	是	进程 ID

返回值：CrossProcess — 进程实例

抛出：当指定 pid 的进程不存在时抛出 Error

---

cross.getPids()

说明：获取所有子进程 pid 列表。

返回值：string[] — pid 字符串数组

---

CrossProcess 类

CrossProcess 类封装外部进程的完整生命周期：创建 → 运行 → 监听事件 → 终止。通过 host 的 emitter 向 Cross 管理器通知子进程事件（exit/error）。

进程路径解析规则：

• 配置有 cmd → 使用 cmd 作为可执行文件路径（相对路径基于 directory 或生产环境的 extraResourcesDir 解析）
• 配置无 cmd → 使用 extraResourcesDir/{name} 作为路径
• Windows 平台在 windowsExtname=true 或生产环境下自动添加 .exe 扩展名
• 开发环境相对于项目根目录解析；生产环境相对于 extraResources 目录解析

---

CrossProcess 属性

属性	类型	说明
pid	number	子进程 PID
name	string	唯一服务名（可能被 Cross 管理器重写以避免冲突）
port	number	分配的端口编号
config	CrossTargetConfig	服务配置
child	ChildProcess | undefined	通过 cross-spawn 生成的进程对象
emitter	EventEmitter	每个进程的 EventEmitter 实例
host	CrossHost	Host（Cross 管理器），用于通知进程事件

---

entity.kill(timeout)

说明：终止子进程。先发送 SIGINT 信号以优雅退出，若 SIGINT 失败则发送 SIGKILL 强制终止。超时安全网：如果在超时时间内未触发 exit 事件，手动调用 _exitElectron。

参数：

参数	类型	必填	说明
timeout	number	否	等待退出超时时间（毫秒，默认：1000）

返回值：void

示例：

const entity = await cross.run('goServer');
entity.kill();      // 默认 1000ms 超时
entity.kill(3000);  // 自定义超时

---

entity.getUrl()

说明：获取子进程的服务 URL。从启动参数解析主机名和 ssl 标志，构造 HTTP/HTTPS URL。端口为 0 时输出警告。

返回值：string — 服务 URL（如 http://127.0.0.1:7070）

示例：

const entity = await cross.run('goServer');
const url = entity.getUrl();
// http://127.0.0.1:7070

---

entity.getArgsObj()

说明：从 config.args 解析启动参数为键值对象。

返回值：Record<string, unknown> — 解析后的参数对象

示例：

const entity = await cross.run('goServer');
const args = entity.getArgsObj();
// { port: '7070', hostname: '127.0.0.1' }

---

entity.setPort(port)

说明：设置端口编号。字符串会被转换为数字。

参数：

参数	类型	必填	说明
port	string | number	是	端口编号

返回值：void

---

类型

CrossRunOptions

type CrossRunOptions = Partial<CrossTargetConfig>;

此处所有 CrossTargetConfig 属性均为可选，因为它们用于覆盖配置默认值。

CrossProcessOptions

interface CrossProcessOptions {
  /** 目标服务配置 */
  targetConf: CrossTargetConfig;
  /** 分配的端口编号 */
  port: number;
}

CrossHost

interface CrossHost {
  /** 接收子进程退出/错误事件的事件发射器 */
  emitter: EventEmitter | undefined;
}

Cross 实现的接口。CrossProcess 通过此接口与 host 通信，发送子进程退出和错误事件。

CrossTargetConfig

interface CrossTargetConfig {
  /** 目标进程名称标识（如 'go'、'python'） */
  name: string;
  /** 是否启用此跨进程目标 */
  enable?: boolean;
  /** 传递给子进程的命令行参数 */
  args?: string[];
  /** 启动命令（如 'go'、'python3'），为空表示使用脚本直接 fork */
  cmd?: string;
  /** 子进程工作目录，默认为项目根目录 */
  directory?: string;
  /** 是否在 Windows 上自动添加 .exe 扩展名 */
  windowsExtname?: boolean;
  /** 子进程 stdio 配置 */
  stdio?: ('pipe' | 'ignore' | 'inherit' | 'ipc')[];
  /** 子进程退出时是否退出主应用 */
  appExit?: boolean;
  /** 子进程监听端口 */
  port?: number;
  /** 子进程服务 URL（如 http://localhost:port） */
  url?: string;
}