# @electron/osx-sign 中文文档

规范地址：https://npmcn.com/package/%40electron/osx-sign/

版本：2\.7\.2
npm 元数据更新时间：2026-10-25T22:10:40.801Z
中文译文更新时间：2026-11-13T11:54:08.918Z
软件包许可：BSD-2-Clause

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

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

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

- 包体积（解压后）：311 kB，79 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.12\.0
- 运行依赖：4 个
- 首次发布：2022-03-24T07:39:04.390Z
- 最新版本发布：2026-10-25T22:10:40.479Z
- 近 30 天下载量：34984515（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 9 个）

## 中文简介

代号为 Electron macOS 应用程序

## 安装

```sh
npm install @electron/osx-sign
```

也可以使用：`pnpm add @electron/osx-sign`、`yarn add @electron/osx-sign`、`bun add @electron/osx-sign`

## README

# @ electron/ osx 签名

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

代号为 Electron macOS 应用程序

## 关于

[`@electron/osx-sign`](https://github.com/electron/osx-sign) 尽量减少最终准备所需的额外工作 您的应用程序用于运输,为大多数应用程序提供在框外有效的选项. 可通过它的API获得额外的配置.

有两个主要功能通过这个软件包曝光:

-   通过 macOS 程序签名 `sign` 函数。 在车盖下,这个用的是 `codesign` 函数.
-   创建 `.pkg` 通过安装器包 `flat` 函数。 在车盖下,这个用的是 `productbuild` 函数.

## 安装

`@electron/osx-sign` 并可以相应配置:

-   [电子包件器](https://electron.github.io/packager/main/interfaces/OsxSignOptions.html)
-   [电子福尔格](https://www.electronforge.io/guides/code-signing/code-signing-macos)

您也可以安装 `@electron/osx-sign` 如果您的包装管道不涉及这些工具:

```sh
npm install --save-dev @electron/osx-sign
```

## 代码签名

本套装中实施的签名程序是基于Electron's的描述 [代码签名指南](https://github.com/electron/electron/blob/main/docs/tutorial/code-signing.md)。 。 。 .

### 先决条件

-   您必须是注册会员 [苹果开发者程序](https://developer.apple.com/programs/)。 。 。 . 请注意,您可以被苹果公司收取费用,以便获得所需的证书.
-   你一定有过 [X代码](https://developer.apple.com/xcode/) 安装于 [Mac App 存储器](https://apps.apple.com/us/app/xcode/id497799835)不建议下载您的 出于安全考虑,从其他第三方消息来源收到.
-   您必须安装 Xcode 命令行工具 。 为了查查有没有, 尝试 `xcode-select --install` 并遵守指示.
-   要在Mac App Store上分发您的应用程序, 您必须创建一个 Mac App [App Store 连接](https://appstoreconnect.apple.com/)。 。 。 .
-   你必须给你的应用程序 一个独特的包 ID.
-   您必须给您的应用程序一个版本号 .

### 证书

为了在Mac App Store内外分发您的应用程序, 在成为注册开发商后,您需要从苹果获得以下证书.

证书可以通过 [证书、 身份和配置文件](https://developer.apple.com/account/resources/certificates/add) 在苹果开发者网站上或通过 [Xcode 中的账户首选项](https://help.apple.com/xcode/mac/current/#/dev3a05256b8)。 。 。 .

为了在Mac App Store内部发行,您需要创建:

-   Mac App 分布 : `3rd Party Mac Developer Application: * (*)`
-   Mac 安装器分布 : `3rd Party Mac Developer Installer: * (*)`

用于Mac App Store外的分发 :

-   开发者 ID 应用程序 : `Developer ID Application: * (*)`
-   开发者 ID 安装器 : `Developer ID Installer: * (*)`

在您创建必要的认证之后, 下载并打开每个证书, 以便它们成为 安装在您的密钥链中。 我们建议在您的系统中安装它们 默认键链 那个 `@electron/osx-sign` 可以自动检测到它们.

> \[TIP\] 苹果开发商证书往往以相干对来. 安装起来最简单 二者为后用. 然而,如果你只想在Mac App Store外发行, 不需要安装第三党Mac开发者,反之亦然.

### API 密码

```javascript
import { sign } = from '@electron/osx-sign'
const opts = {
  app: 'path/to/my.app'
};
sign(opts)
  .then(function () {
    // Application signed
  })
  .catch(function (err) {
    // Handle the error
  })
```

唯一的强制性选项 `sign` 一条通往你的路 `.app` 软件包. 大多数 Electron apps 的配置应该能用到框外. 完整的配置选项见 [API 文档](https://packages.electronjs.org/osx-sign)。 。 。 .

### 用法实例

#### Mac App Store 发行签名

```javascript
import { sign } from '@electron/osx-sign'
const opts = {
  app: 'path/to/my.app',
  // optional parameters for additional customization
  platform: "mas", // should be auto-detected if your app was packaged for MAS via Packager or Forge
  type: "distribution", // defaults to "distribution" for submission to App Store Connect
  provisioningProfile: 'path/to/my.provisionprofile', // defaults to the current working directory
  keychain: 'my-keychain', // defaults to the system default login keychain
};
sign(opts)
  .then(function () {
    // Application signed
  })
  .catch(function (err) {
    // Handle the error
  })
```

麦克App 存储应用程序需要 [提供配置](https://www.electronjs.org/docs/latest/tutorial/mac-app-store-submission-guide#prepare-provisioning-profile) 提交到 App Store 连接。 我们建议把配置图公布于众 放在当前工作目录和默认密钥链所安装的签名身份.

该应用程序预计不会在代号后运行,因为没有提供设备,它是 仅打算提交 App Store 连接。 自兹 `@electron/osx-sign` 添加条目 `com.apple.developer.team-identifier` 转到指定的应享权利文件的临时副本 (带有默认选项) `preAutoEntitlements`,),发行架构不能再直接运行.

要在代码签名后运行本地发行的应用代码, 您可以手动添加 `ElectronTeamID` 在你身边 `Info.plist` 财务报告和审定财务报表 `com.apple.security.application-groups` 输入 应享权利文件,并设定 `preAutoEntitlements: false` 页:1 `@electron/osx-sign` 为避免 这额外一点。 注意:"某些特性只允许在团队识别值匹配的应用程序之间使用" (单位:千美元)[技术说明TN2415](https://developer.apple.com/library/content/technotes/tn2415/_index.html#//apple_ref/doc/uid/DTS40016427-CH1-ENTITLEMENTSLIST)) (中文(简体) ).

或者,设置应用程序 `type` 改为 `development` 以编码您的应用程序的开发版本, 它可以运行在您的开发提供机器上。 Apps 签名开发 无法通过 App Store 连接提交.

#### 签名 `--deep`

您可能包含在您的 Electron app 中的一些子资源可能需要与 `--deep`。 。 。 . 这通常不适用于整个电子软件,因此应适用于 _刚刚_ 你的档案.

```javascript
sign({
  app: 'path/to/my.app',
  optionsForFile: (filePath, { platform }) => {
    // The second argument provides additional context about the current signing
    // operation, such as the resolved `platform` ('darwin' or 'mas').

    // For our one specific file we can pass extra options to be merged
    // with the default options
    if (path.basename(filePath) === 'myStrangeFile.jar') {
      return {
        additionalArguments: ['--deep'],
      };
    }

    // Just use the default options for everything else
    return null;
  },
});
```

#### 签名 Electron 遗留版本

`@electron/osx-sign` 与旧版本的Electron保持后向兼容,但 通常认为您是最新的稳定版本.

如果你正在运行一个更古老的无支持的Electron版本, 你应该通过在 `version` 选项

```javascript
sign({
  app: 'path/to/my.app',
  version: '0.34.0',
});
```

## 平面安装器包装

此模块还处理平面安装器包的创建( P)`.pkg` 安装者).

> \[注\] 现代 `.pkg` 安装器也被命名为"平面"包,用于历史目的. 上一个 至 Mac OS X Leopard (10.5),安装包按等级排列 目录. OS X Leopard采用了新的平面包格式,用于现代 `.pkg` 安装器.

### API 使用情况

```javascript
import { flat } = '@electron/osx-sign'
flat({
  app: 'path/to/my.app'
})
  .then(function () {
    // Application flattened
  })
  .catch(function (err) {
    // Handle the error
  })
```

唯一的强制性选项 `flat` 一条通往你的路 `.app` 软件包. 完整的配置选项见 [API 文档](https://packages.electronjs.org/osx-sign)。 。 。 .

### 纯-贾瓦脚本包装

默认 `flat` 向苹果公司发射炮弹 `pkgbuild`编号 :`productbuild` 二进制. 通过 `implementation: 'js'` 切换到捆绑的纯 Java 脚本执行 典型的平面包格式 **4 - 5× 较快** 在真正的电子应用程序和工作 在任何平台上(包含Linux/Windows),用于未签名的软件包:

```javascript
await flat({
  app: 'path/to/my.app',
  implementation: 'js',
});
```

联合来文的执行重新实施整个平装货堆——cpio有效载荷 存档 :`Bom`二进制格式 `PackageInfo`编号 :`Distribution` 文档和外部 xar 归档。 其产出根据本地工具进行核实 广泛的平等测试套件(`spec/pkg-utils/`: 未压缩的有效载荷为 字节相同, `lsbom` 每个字段的输出匹配, XML 文档是 字节-同声调 `generator-version` 属性。 运行 `yarn bench` 复制 机器上的性能比较.

关于与本地工具的故意差异的说明:

-   有效载荷作为符合标准的多成员流被压缩,因此成员 可平行压缩。 压缩后输出大于 ~3% 苹果私人 zlib口味;被解压的内容相同.
-   扩展属性不保存( 无 AppleDouble ) `._*` 条目生成).
-   应用程序 `Info.plist` 必须是 XML; 二进制属性列表被错误拒绝.
-   硬链接文件作为独立副本存储,而不是复制方式 pkgbuilt 归档它们(Electron Apps使用同义链接,而不是硬链接).
-   超过 4 GB 的单个文件被拒绝( 平面包 Bom 格式存储) 32-位大小; `Size64` 支持没有执行).
-   使用 NFC 规范化( 组合) Unicode 名称的文件包装正确; 本地 `pkgbuild` 默默地将此类文件从有效载荷中省去.
-   当一个签名 `identity` 提供已建软件包,并签名 `productsign`, (中文(简体) ), 这需要macOS.

## 国 际

`@electron/osx-sign` 还曝光了遗留下来的用于两个签名的指令行接口(CLI) 和安装器的生成。 然而,我们建议使用JavaScript API,因为它有更多的 完整 API 表面( 例如). `optionsForFile` 仅通过联合来文提供).

```sh
# install the package locally into devDependencies
npm install --save-dev @electron/osx-sign

# Sign a packaged .app bundle
npx electron-osx-sign path/to/my.app [options ...]

# Create a .pkg installer from a packaged .app bundle
npx electron-osx-flat path/to/my.app [options ...]
```

对于全部选项,请使用 `--help` 两个命令的旗帜.

## 调试

这个 [`debug`](https://www.npmjs.com/package/debug) 模块用于显示高级日志和信件. 如果你有问题 签署你的应用程序 `@electron/osx-sign`,运行您的签名脚本 页:1 `DEBUG=electron-osx-sign*` 环境变量.

## 测试

该项目的配置是为了在GitHub Actions上运行自动测试.

如果您想要手动测试模块, 您需要首先生成自签名证书 通过 `spec/ci/generate-identity.sh` 剧本.

## 常见问题

### @electron/osx-sign 是什么？

代号为 Electron macOS 应用程序

### 如何安装 @electron/osx-sign？

在项目目录运行 npm install @electron/osx-sign，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 electron-osx-flat、electron-osx-sign，可以用 npx electron-osx-flat 直接运行。

### @electron/osx-sign 支持 TypeScript 吗？

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

### @electron/osx-sign 支持 ESM 还是 CommonJS？

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

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

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

### @electron/osx-sign 可以商用吗？

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

### @electron/osx-sign 的下载量有多少？

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

### @electron/osx-sign 还在维护吗？

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