macOS 代码签名配置指南

2025-06-20

概述

配置 macOS 代码签名和公证，确保应用能够在 macOS 上正常分发和运行。

前置要求

Apple Developer 账户
- 需要付费的 Apple Developer Program 会员资格
- 个人账户或组织账户均可
开发者证书
- Developer ID Application Certificate（用于分发）
- Developer ID Installer Certificate（如果需要 pkg 安装包）

步骤一：获取开发者证书

1. 在 Apple Developer 网站创建证书

登录 Apple Developer
进入 “Certificates, Identifiers & Profiles”
点击 “Certificates” → “+”
选择 “Developer ID Application”
按照指引创建并下载证书

2. 导出证书为 p12 格式

在 macOS 上双击下载的证书文件，导入到钥匙串
在钥匙串访问中找到证书
右键点击证书 → “导出”
选择 “.p12” 格式
设置密码（记住这个密码，后面需要用到）

3. 转换为 base64 格式

# 将 p12 文件转换为 base64 编码
base64 -i your-certificate.p12 -o certificate-base64.txt

步骤二：获取 App-Specific Password

登录 Apple ID 管理页面
进入 “Sign-In and Security” → “App-Specific Passwords”
点击 “Generate an app-specific password”
输入标签（如 “EchoLab CI/CD”）
保存生成的密码

步骤三：配置 GitHub Secrets

在 GitHub 仓库中设置以下 Secrets：

必需的 Secrets

Secret 名称	描述	示例值
`APPLE_ID`	Apple ID 邮箱	`your-email@example.com`
`APPLE_APP_SPECIFIC_PASSWORD`	App-Specific Password	`abcd-efgh-ijkl-mnop`
`APPLE_TEAM_ID`	Apple Developer Team ID	`ABCDEFGHIJ`
`CSC_LINK`	证书的 base64 编码	`MIIKxAIBAzCCCn4GCSqGSIb3...`
`CSC_KEY_PASSWORD`	证书密码	`your-certificate-password`

如何获取 Team ID

方法一：通过 Apple Developer 网站

登录 Apple Developer
进入 “Membership” 页面
查看 “Team ID” 字段（10位字符，如 ABCDEFGHIJ）

方法二：通过钥匙串访问

打开 macOS 钥匙串访问
找到您的 Developer ID Application 证书
双击证书查看详情
在 “Organizational Unit” 字段中可以看到 Team ID

方法三：通过命令行

# 列出所有可用的签名身份
security find-identity -v -p codesigning

# 查看证书详情
security find-certificate -c "Developer ID Application" -p | openssl x509 -text | grep "OU="

验证 Team ID
确保您使用的 Apple ID 是该 Team 的成员，并且有相应的权限。

设置 GitHub Secrets

进入 GitHub 仓库
点击 “Settings” → “Secrets and variables” → “Actions”
点击 “New repository secret”
逐一添加上述 Secrets

步骤四：验证配置

1. 检查配置文件

确保以下文件已正确配置：

✅ electron-builder.yml - 已启用 notarize 和 hardenedRuntime
✅ build/entitlements.mac.plist - 包含必要的权限
✅ .github/workflows/build-and-release.yml - 包含环境变量

electron-builder.yml

mac:
  notarize: true
  hardenedRuntime: true

build/entitlements.mac.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <!-- Hardened Runtime 权限 -->
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
    <true/>
    <key>com.apple.security.cs.allow-dyld-environment-variables</key>
    <true/>
    <key>com.apple.security.cs.disable-library-validation</key>
    <true/>

    <!-- 网络访问权限 -->
    <key>com.apple.security.network.client</key>
    <true/>
    <key>com.apple.security.network.server</key>
    <true/>

    <!-- 文件系统访问权限 -->
    <key>com.apple.security.files.user-selected.read-write</key>
    <true/>
    <key>com.apple.security.files.downloads.read-write</key>
    <true/>

    <!-- 音频/视频权限 -->
    <key>com.apple.security.device.audio-input</key>
    <true/>
    <key>com.apple.security.device.camera</key>
    <true/>
  </dict>
</plist>

.github/workflows/build-and-release.yml

      - name: Build for ${{ matrix.platform }}
        run: |
          echo "🏗️ Building for ${{ matrix.platform }}"
          echo "构建平台: ${{ matrix.platform }}"
          pnpm build
          pnpm exec electron-builder ${{ matrix.target }} --publish never
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
          CSC_LINK: ${{ secrets.CSC_LINK }}
          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}

2. 测试构建

手动触发构建但不发布
观察 GitHub Actions 构建过程
检查是否有签名相关的错误

常见问题

Q: 构建时提示 “No identity found”

A: 检查 CSC_LINK 和 CSC_KEY_PASSWORD 是否正确设置

Q: “Invalid or inaccessible developer team ID”

A: 这是最常见的问题，解决步骤：

验证 Team ID 格式：
- Team ID 应该是 10 位字符（字母和数字）
- 例如：ABCDEFGHIJ，不是 68C967093DD97D642FBEEDF86203D42A0776CC59

获取正确的 Team ID：

# 在 macOS 上运行，查看您的证书信息
security find-identity -v -p codesigning

# 或者查看证书详情
security find-certificate -c "Developer ID Application" -p | openssl x509 -text | grep "OU="

确认账户权限：
- 确保您的 Apple ID 是该开发者团队的成员
- 确保有 App Manager 或 Admin 权限
- 个人开发者账户的 Team ID 通常与 Apple ID 关联
检查证书类型：
- 必须使用 “Developer ID Application” 证书
- 不能使用 “Mac Development” 或 “Mac App Store” 证书

Q: 公证失败

A: 确认：

Apple ID 和 App-Specific Password 正确
Team ID 正确（10 位字符）
证书有效且未过期
使用了 App-Specific Password，不是普通密码

Q: 应用无法在其他 Mac 上运行