# @electron/universal 中文文档

规范地址：https://npmcn.com/package/%40electron/universal/

版本：3\.0\.6
npm 元数据更新时间：2026-07-02T21:13:04.609Z
中文译文更新时间：2026-11-13T11:52:56.547Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：84.5 kB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.12\.0
- 运行依赖：3 个
- 首次发布：2020-11-13T22:27:35.935Z
- 最新版本发布：2026-07-02T21:13:04.361Z
- 近 30 天下载量：35489877（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 4 个）

## 中文简介

从两个x64和arm64电子应用程序创建通用macOS应用程序的工具

## 安装

```sh
npm install @electron/universal
```

也可以使用：`pnpm add @electron/universal`、`yarn add @electron/universal`、`bun add @electron/universal`

## README

# @ electron/ 普遍

> 创建通用macOS电子应用程序

[![Test](https://github.com/electron/universal/actions/workflows/test.yml/badge.svg)](https://github.com/electron/universal/actions/workflows/test.yml) [![NPM package](https://img.shields.io/npm/v/@electron/universal)](https://npm.im/@electron/universal) [![API docs](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.npmjs.org%2F%40electron%2Funiversal%2Flatest&query=%24.version&logo=typescript&logoColor=white&label=API%20Docs)](https://packages.electronjs.org/universal)

## 使用量

这个软件包需要一个x64的应用程序和一个arm64的应用程序,把它们粘在一起成一个 [通用macOS 二进制](https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary)。 。 。 .

注意参数必须是: **绝对** 路径.

```typescript
import { makeUniversalApp } from '@electron/universal';

await makeUniversalApp({
  x64AppPath: 'path/to/App_x64.app',
  arm64AppPath: 'path/to/App_arm64.app',
  outAppPath: 'path/to/App_universal.app',
});
```

API 的全用法见 [API 文档](https://packages.electronjs.org/universal)。 。 。 .

## 高级配置

基本使用模式将适用于大多数出盒的应用程序. 其他配置 高级用例的选项.

### 合并 ASAR 档案以减少应用大小

**已添加 [页:1](https://github.com/electron/universal/commit/38ab1c3559e25382957d608e49e624dc72a4409c)**

如果您正在使用 ASAR 档案存储您的 Electron app 的 JavaScript 代码, 您可以使用 `mergeASARs` 选项来合并您的 x64 和 arm64 ASAR 文件,以减少捆绑大小 输出通用应用程序.

如果一些文件只存在于x64应用中,而不存在于arm64版本(或反之), 您可以指定一个 `minimatch` 模式 内 `singleArchFiles`。 。 。 .

```typescript
import { makeUniversalApp } from '@electron/universal';

await makeUniversalApp({
  x64AppPath: 'path/to/App_x64.app',
  arm64AppPath: 'path/to/App_arm64.app',
  outAppPath: 'path/to/App_universal.app',
  mergeASARs: true,
  singleArchFiles: 'node_modules/some-native-module/lib/binding/Release/**', // if you have files in your asar that are unique to x64 or arm64 apps
});
```

若为 `@electron/universal` 检测未覆盖的架构独有文件 `singleArchFiles` 规则,错误将被丢出.

### 在您的通用应用程序中为某些二进制跳过唇形

**已添加 [1.3.0 (单位:千美元)](https://github.com/electron/universal/commit/01dfb8a9636965fe154192b07934670dd42509f3)**

如果您的 Electron app 包含已合并的二进制资源 `lipo` 工具,提供 [`minimatch`](https://github.com/isaacs/minimatch?tab=readme-ov-file#features) 模式以匹配 `x64ArchFiles` 参数将防止 `@electron/universal` 不再试图再次合并它们.

```typescript
import { makeUniversalApp } from '@electron/universal';

await makeUniversalApp({
  x64AppPath: 'path/to/App_x64.app',
  arm64AppPath: 'path/to/App_arm64.app',
  outAppPath: 'path/to/App_universal.app',
  mergeASARs: true,
  x64ArchFiles: '*/electron-helper', // `electron-helper` is a binary merged using `lipo`
});
```

若为 `@electron/universal` 检测到一个没有覆盖的唇形文件 `x64ArchFiles` 规则, 会出现错误.

### 包括已编码的应用程序捆绑到您的通用应用程序

**已添加 [页:1](https://github.com/electron/universal/commit/b02ce7697fd2a3c2c79e1f6ab6bf7052125865cc)**

默认情况下,合并进程将生成 `ElectronAsarIntegrity` 键 任意 `Info.plist` 在您的电子应用程序中的文件.

如果你的Electron应用 捆绑了另一个 `.app` 已经签名,您需要使用 页:1 `infoPlistsToIgnore` 选项来避免修改该应用程序的列表.

```typescript
import { makeUniversalApp } from '@electron/universal';

await makeUniversalApp({
  x64AppPath: 'path/to/App_x64.app',
  arm64AppPath: 'path/to/App_arm64.app',
  outAppPath: 'path/to/App_universal.app',
  infoPlistsToIgnore: 'my-internal.app/Contents/Info.plist'
});
```

## 财务问题

#### 为什么?

一个通用的应用程序只是x64的应用程序,而arm64的应用程序被粘合在一起,形成一个单一的应用程序. 因为它包含一个中的两个应用程序,所以其体积大了一倍.

合并您的 ASAR 捆绑可以显著缩小应用大小, 取决于大小  `app.asar` 档案是.

#### 本地模块呢?

在盒子外,你不需要担心 建立通用版本你的 本地模块 。 只要您的x64和arm64应用在孤立状态下工作, 通用 应用也行.

请注意,如果您正在使用 `mergeASARs`,您可能需要添加特定架构 二进制资源到 `singleArchFiles` 模式. 见 [合并辅助搜索和救援区的使用](https://npmcn.com/package/%40electron/universal/#readme-merging-asar-archives-to-reduce-app-size) 举个例子.

## 常见问题

### @electron/universal 是什么？

从两个x64和arm64电子应用程序创建通用macOS应用程序的工具

### 如何安装 @electron/universal？

在项目目录运行 npm install @electron/universal，或使用 pnpm add / yarn add / bun add。

### @electron/universal 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/electron\_\_universal 是否存在。

### @electron/universal 支持 ESM 还是 CommonJS？

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

### @electron/universal 需要什么版本的 Node\.js？

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

### @electron/universal 可以商用吗？

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

### @electron/universal 的下载量有多少？

根据 npm 官方下载统计，@electron/universal 在 2026/10/14 – 2026/11/12 这 30 天内被下载 35,489,877 次，日均约 1,182,996 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @electron/universal 还在维护吗？

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