MacOS Electron应用中使用Universal Links的签名问题排查

通过Electron Forge构建并签名自行分发的macOS Electron应用时，在授权文件中添加com.apple.developer.associated-domains后，启动应用出现错误：

Library not loaded: @rpath/Electron Framework.framework/Electron Framework

两种可正常运行的情况：

• 手动从应用的/Contents/embedded.provisionprofile配置配置文件，应用正常启动且Universal Links功能正常
• 从授权文件中移除com.apple.developer.associated-domains选项，应用正常启动但无法使用Universal Links功能

需求：如何签名应用以避免手动安装配置文件？

附带配置信息 #

forge.config.ts #

osxSign: {
  identity: 'Developer ID Application: ***',
  provisioningProfile: './embedded.provisionprofile',
  optionsForFile: () => ({
    entitlements: './entitlements.plist'
  })
},

embedded.provisionprofile #

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.security.cs.allow-jit</key>
  <true/>
  <key>com.apple.security.device.audio-input</key>
  <true/>
  <key>com.apple.security.device.bluetooth</key>
  <true/>
  <key>com.apple.security.device.camera</key>
  <true/>
  <key>com.apple.security.device.print</key>
  <true/>
  <key>com.apple.security.device.usb</key>
  <true/>
  <key>com.apple.security.personal-information.location</key>
  <true/>
  <key>com.apple.developer.associated-domains</key>
  <array>
      <string>applinks:mydomain.com</string>
      <string>webcredentials:mydomain.com</string>
  </array>
</dict>
</plist>

配置文件授权信息 #

'com.apple.developer.associated-domains': '*',
'com.apple.application-identifier': 'ZZ67H7XXXX.pro.***.***',
'keychain-access-groups': [ 'ZZ67H7XXXX.*' ],
'com.apple.developer.team-identifier': 'ZZ67H7XXXX'

• 拆分授权文件，匹配不同组件需求
  问题根源是给所有文件（包括Electron Framework）统一设置了包含com.apple.developer.associated-domains的授权文件，而该权限仅属于主应用，框架不需要此权限，导致签名后框架加载失败。

• 修改forge.config.ts的签名规则
  针对主应用、Electron Framework分别指定对应的授权文件，不要全局统一设置：

osxSign: {
  identity: 'Developer ID Application: ***',
  provisioningProfile: './embedded.provisionprofile',
  optionsForFile: (filePath) => {
    // 仅给主应用进程设置包含associated-domains的授权
    if (filePath.endsWith('.app/Contents/MacOS/[你的应用主程序文件名]')) {
      return {
        entitlements: './entitlements.plist'
      };
    }
    // 给Electron Framework使用专用的框架授权文件
    if (filePath.includes('Electron Framework.framework')) {
      return {
        entitlements: './entitlements-framework.plist'
      };
    }
    // 其他文件保持默认签名配置
    return {};
  }
},

• 创建entitlements-framework.plist文件
  该文件仅保留Electron框架运行所需的权限，不要包含com.apple.developer.associated-domains：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <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.disable-executable-page-protection</key>
  <true/>
</dict>
</plist>

• 验证签名有效性
  构建完成后，执行以下命令检查签名是否正确：

codesign --display --verbose=4 /path/to/your.app
spctl -a -t exec -vv /path/to/your.app

内容的提问来源于stack exchange，提问作者JasonDesh