在 macOS 上使用云签工具进行代码签名(云签)

适用于已开通 TrustAsia 云签服务，需要在 macOS 电脑上使用 ssigncode 命令行工具为 Windows 程序签名的用户。整个流程为：准备工具 → 设置 PIN 并添加操作员 → 安装操作员证书 → 获取证书指纹 → 签名并检查结果。

本文以 Windows EXE 文件为例。若要签名和发布 macOS 原生应用，请参考 Apple Developer ID 签名与公证说明。

截图仅供操作参考，部分信息已脱敏，界面以实际使用的平台版本为准。

1. 准备工具和签名信息

开始前，请确认云签订单中的代码签名证书已签发，并准备好可联网的 Mac、macOS 版签名工具和待签名文件。工具安装包可联系技术支持获取。

本文使用的工具文件名为 ssigncode-mac-x86_64。请确认工具与电脑的处理器架构、macOS 版本兼容；使用其他版本时，将命令中的工具名称替换为实际文件名。

后续操作会用到以下信息，请注意区分。

信息	用途与获取位置
签名 PIN	在 云签详情 → 签名安全设置 中设置，用于安装操作员证书及签名验证，对应 --key_pin。
操作员安装 token	在 云签详情 → 操作员管理 中添加操作员后获取，用于安装操作员证书，对应 --auth。
操作员证书指纹	安装操作员证书后，在 操作员管理 中获取，用于指定本次签名使用的操作员，对应 -u。
签名证书指纹	在目标订单的 订单详情 → 证书详情 中获取，用于指定实际签署文件的代码签名证书，对应 --cert_hash。

操作员证书指纹与签名证书指纹用途不同，请勿互换。 文档和命令中的 hash 在上述两处均指证书指纹；--hash sha256 则用于选择文件签名的摘要算法。

打开 macOS 的“终端”，进入工具所在目录：

cd "<签名工具所在目录>"

下文使用 <签名工具所在目录>、<待签名EXE文件的完整路径> 等占位示例。执行前请将尖括号及其中内容整体替换为实际值，并保留路径外侧的引号。

2. 设置 PIN 并添加操作员

设置签名 PIN

进入目标订单的 云签详情 → 签名安全设置，设置签名 PIN。已设置过 PIN 的，请使用当前有效的 PIN。

获取操作员安装 token

1. 在 云签详情 页面找到 操作员管理。
2. 点击“添加”，按页面提示添加本次使用的操作员。
3. 在该操作员记录的 Token 列复制安装 token，供下一步安装证书使用。

请妥善保管 PIN 和安装 token，避免出现在共享脚本、终端录屏、截图或日志中。命令行中填写的敏感参数也可能保留在终端历史记录中。

3. 安装操作员证书

在工具所在目录执行以下命令，将 token 和 PIN 替换为上一步获取的信息：

./ssigncode-mac-x86_64 install \
  --vsign \
  --auth '<操作员安装token>' \
  --key_pin '<签名PIN>' \
  -s https://vsign.trustasia.com

参数	说明
install --vsign	安装用于 VSign 云签的操作员证书。
--auth	操作员安装 token。
--key_pin	在签名安全设置中设置的 PIN。
-s	签名服务器地址。本文使用 https://vsign.trustasia.com。

等待命令完成，确认终端提示“获取操作员证书成功”和“安装操作员证书成功”。若安装失败，请先处理错误，再继续签名。

安装成功后，返回 云签详情 → 操作员管理 并刷新，找到刚安装的操作员，复制 证书哈希 列中的值，作为后续命令的 操作员证书指纹。

4. 获取签名证书指纹

进入需要用于签名的订单，打开 订单详情 → 证书详情，复制“指纹”字段的完整值，作为后续命令的 签名证书指纹。

复制前，请核对证书所属组织、有效期和用途，确认选择的是本次使用的代码签名证书。不要复制证书序列号，也不要将操作员证书指纹填入此处。

5. 签名并添加时间戳

建议先对一个测试文件签名，检查通过后再处理正式发布文件。输入文件与输出文件使用不同路径，便于保留原始文件。

以下示例使用 SHA256 签名，并选择 TrustAsia 时间戳服务：

./ssigncode-mac-x86_64 vsign \
  -s https://vsign.trustasia.com \
  --cert_from csign \
  --cert_hash '<签名证书指纹>' \
  -u '<操作员证书指纹>' \
  --key_pin '<签名PIN>' \
  -i '<待签名EXE文件的完整路径>' \
  -o '<已签名EXE文件的完整路径>' \
  --ts TrustAsia \
  --hash sha256

参数	填写方法
vsign	使用云签服务进行签名。
-s	签名服务器地址，与安装操作员证书时保持一致。
--cert_from csign	指定本流程使用的证书来源，按示例填写 csign。
--cert_hash	第 4 步获取的签名证书指纹。
-u	第 3 步获取的操作员证书指纹。
--key_pin	当前有效的签名 PIN；也可使用简写 -k。
-i	待签名文件的完整路径。
-o	签名后文件的输出路径，请确认目标目录已存在且可写。
--ts	时间戳服务，本文使用 TrustAsia。
--hash sha256	使用 SHA256 摘要算法。

命令执行时，工具会读取文件、发送文件摘要进行签名，并附加时间戳。确认终端出现“签名成功”提示，且输出路径中已生成签名后的文件，再继续检查结果。

选择时间戳服务

可按需要设置以下时间戳服务。正式发布前，请确认服务可访问，并验证输出文件中的时间戳。

服务	参数
TrustAsia（默认）	--ts TrustAsia
DigiCert	--ts DigiCert
GlobalSign	--ts GlobalSign

如需使用 DigiCert，将签名命令中的 --ts TrustAsia 替换为 --ts DigiCert，其他参数按实际签名信息填写。

为已签名文件添加时间戳

需要单独为已签名文件添加时间戳时，可使用 timestamp 命令。以下示例使用 DigiCert 服务，并另存为新文件：

./ssigncode-mac-x86_64 timestamp \
  -i '<已签名EXE文件的完整路径>' \
  -o '<添加时间戳后文件的输出路径>' \
  --ts DigiCert

此命令用于添加时间戳，不代替首次代码签名。完成后应对新生成的文件重新检查签名和时间戳。

6. 检查签名结果

将最终输出的 EXE 文件复制到 Windows 电脑上，检查签名是否有效。

1. 右键点击文件，选择 属性 → 数字签名。
2. 选中本次签名，核对签名者名称、摘要算法和时间戳。
3. 点击“详细信息”，确认签名有效，并检查签名证书是否为预期证书。

数字签名列表中出现一条记录，不等于签名已通过信任验证。 请继续查看详细信息，确认没有证书信任或签名验证错误。

如已安装 Windows SDK SignTool，也可在能够调用 signtool 的 Windows 命令行中执行：

signtool verify /pa /all /v /tw "<待验证的已签名EXE文件的完整路径>"

/pa 使用默认 Authenticode 验证策略，/all 验证所有签名，/v 输出详细信息，/tw 在缺少时间戳时发出警告。若上一步单独添加了时间戳，请填写最终输出文件的完整路径。命令参考：Microsoft SignTool。

检查通过后再分发最终文件。签名后若再次修改程序内容，需要重新签名。

常见问题

情况	处理方法
终端提示找不到工具或文件	确认当前目录、工具名称及输入文件路径正确；路径含空格时使用引号。
工具无法执行或提示架构不兼容	确认安装包来源及文件执行权限，并联系技术支持确认工具与当前 Mac 的兼容性。
操作员证书安装失败	核对操作员安装 token、PIN、服务器地址和网络连接，保留脱敏后的错误提示。
提示找不到操作员证书	确认已在当前使用环境完成安装，刷新操作员管理页面并核对 -u 对应的证书指纹。
提示证书不存在或无权限	核对 --cert_hash 是否来自目标代码签名订单，并检查操作员状态和签名权限。
PIN 验证失败	使用签名安全设置中的当前 PIN，不要填写安装 token，也不要反复猜测 PIN。
时间戳添加失败	检查时间戳服务及网络连接，必要时选择其他服务重试，并对最终文件重新验证。
Windows 验证失败	查看签名详细信息及 SignTool 输出，检查文件是否被修改、是否选错证书，以及证书链和信任状态。
已签名但仍出现 SmartScreen 提示	参考 软件已签名，为什么仍被 Edge 或 SmartScreen 拦截？。