electron-builder macOS 签名密钥链密码修复：`set-key-partition-list` 与临时钥匙串密码的解析

electron-builder macOS 签名密钥链密码修复set-key-partition-list与临时钥匙串密码的解析【免费下载链接】electron-builderA complete solution to package and build a ready for distribution Electron app with “auto update” support out of the box项目地址: https://gitcode.com/gh_mirrors/el/electron-builder导读本文围绕 electron-builder 仓库中针对 macOS 代码签名的一处关键修复changesetfix-mac-keychain-partition-list-password.md展开深入剖析在通过CSC_LINK导入证书进行签名时security set-key-partition-list命令应当使用临时钥匙串自身密码而非证书导入密码的根本原因。读完本文你将理解security import -P与set-key-partition-list -k两种密码的语义差异、macOS 钥匙串分区列表partition list与访问控制的机制以及 electron-builder 内部完整的安全命令调用链并掌握排查SecKeychainUnlock: The user name or passphrase you entered is not correct这一经典报错的方法。一、问题背景CSC_LINK签名失败与 SecKeychainUnlock 报错在 macOS 上electron-builder 支持两种证书来源一种是直接使用登录钥匙串login keychain中已安装的证书通过CSC_NAME指定身份另一种是通过环境变量CSC_LINK指向一个.p12/.pfx证书文件可以是本地路径、Base64 编码字符串或https://远程 URL由构建工具动态创建临时钥匙串并将证书导入其中完成签名。在修复之前当开发者使用CSC_LINK方式在较新版本的 macOS 上执行签名时可能遭遇如下报错SecKeychainUnlock: The user name or passphrase you entered is not correct该错误出现的根本原因正如 changeset 所述security import -P使用的密码证书的导入密码只对导入操作有效而set-key-partition-list -k要求的是钥匙串自身的解锁密码。在会校验密码的 macOS 版本上若将证书导入密码错误地传给-k便会导致钥匙串解锁失败进而使整个CSC_LINK签名流程失败。对应 issue 为 electron-builder #10066。二、修复内容为set-key-partition-list传入钥匙串自身密码本次修复是一个app-builder-lib包级别的patch变更核心修改位于 macCodeSign.ts 的importCerts函数。修复后的关键代码如下macCodeSign.tsasync function importCerts(keychainFile: string, paths: Arraystring, keyPasswords: Arraystring, keychainPassword: string): PromiseCodeSigningInfo { for (let i 0; i paths.length; i) { const password keyPasswords[i] ?? await exec(/usr/bin/security, [import, paths[i], -k, keychainFile, -T, /usr/bin/codesign, -T, /usr/bin/productbuild, -P, password]) // -k expects the keychains own unlock password (as used by create-keychain/unlock-keychain above), // not the imported items password used by security import -P. await exec(/usr/bin/security, [set-key-partition-list, -S, apple-tool:,apple:, -s, -k, keychainPassword, keychainFile]) } return { keychainFile, } }修复前后行为对比命令参数修复前错误修复后正确security import-P password证书导入密码keyPasswords[i]证书导入密码keyPasswords[i]不变security set-key-partition-list-k password证书导入密码钥匙串自身密码keychainPassword修复的核心差异仅在set-key-partition-list的-k参数来源从每个证书各自的导入密码password即keyPasswords[i]改为创建钥匙串时生成的统一密码keychainPassword。三、源码深挖临时钥匙串的完整生命周期要理解这次修复必须看清 electron-builder 创建临时钥匙串的完整调用链。整个流程由 macPackager.ts 中的codeSigningInfo一个MemoLazy惰性单例触发最终调用 macCodeSign.ts 的createKeychain。3.1 证书信息的采集CSC_LINK / CSC_KEY_PASSWORD在 platformPackager.ts 中证书链接与密码的解析优先级如下getCscLink(extraEnvName?: string | null): string | Nullish { const envValue chooseNotNull(extraEnvName null ? null : process.env[extraEnvName], process.env.CSC_LINK) return chooseNotNull(chooseNotNull(this.info.config.cscLink, this.platformSpecificBuildOptions.cscLink), envValue) } doGetCscPassword(): string | Nullish { return chooseNotNull(chooseNotNull(this.info.config.cscKeyPassword, this.platformSpecificBuildOptions.cscKeyPassword), process.env.CSC_KEY_PASSWORD) }即优先级为构建配置config.cscLink/config.cscKeyPassword→ 平台级构建选项 → 环境变量CSC_LINK/CSC_KEY_PASSWORD。getCscPassword在密码为空时只会记录一条CSC_KEY_PASSWORD is not defined的 info 日志并以空字符串继续platformPackager.ts。3.2 下载与解码证书importCertificatecreateKeychain通过 codesign.ts 的importCertificate将CSC_LINK解析为本地.p12文件路径支持三种形态https://开头的远程 URL下载到临时目录suffix.p12Base64 编码的证书内容decodeCscLinkBase64解码后写入临时.p12文件本地文件路径解析后校验存在性与文件类型否则抛出InvalidConfigurationError。3.3 创建钥匙串一串 security 命令createKeychainmacCodeSign.ts依次执行以下命令security create-keychain -p keychainPassword keychainFile创建临时钥匙串keychainPassword即该钥匙串自身的密码由randomBytes(32).toString(base64)生成见 macCodeSign.tssecurity unlock-keychain -p keychainPassword keychainFile解锁该钥匙串同样使用自身密码security set-keychain-settings keychainFile关闭钥匙串的自动锁定等交互行为security list-keychains -d user -s keychainFile ...把临时钥匙串加入用户钥匙串搜索列表保证后续codesign能发现其中的身份。其中钥匙串文件名由currentDir的 SHA-256 哈希加app-builder后缀生成位于APP_BUILDER_TMP_DIR或系统临时目录macCodeSign.ts保证同一项目重复构建时使用稳定路径。3.4 导入证书import set-key-partition-list随后进入被修复的importCertsmacCodeSign.tssecurity import p12 -k keychainFile -T /usr/bin/codesign -T /usr/bin/productbuild -P certPassword将证书导入临时钥匙串。-P传入的是证书文件自身p12的密码即CSC_KEY_PASSWORD或cscKeyPassword配置-T授权codesign与productbuild使用该证书避免弹出 GUI 授权对话框security set-key-partition-list -S apple-tool:,apple: -s -k keychainPassword keychainFile将apple-tool:与apple:加入钥匙串的分区列表并把该分区设置为默认secure。-k传入的是钥匙串自身密码。关于第 2 步代码注释引用了两条关键历史资料见 macCodeSign.tsmacOS Sierra 及之后钥匙串引入分区列表partition list机制——非分区列表内工具的访问会被忽略即使codesign已被-T授权-k参数期望的是create-keychain/unlock-keychain使用的钥匙串自身解锁密码而非security import -P使用的条目密码。正是这两条语义的差异构成了本次 bug 的根源也是修复方案的理论依据。3.5 清理构建结束删除临时钥匙串MacPackager通过this.info.disposeOnBuildFinish(() removeKeychain(keychainFile))注册清理回调macPackager.ts构建结束后调用security delete-keychain删除临时钥匙串删除失败时降级为直接删除文件macCodeSign.ts。四、测试验证macCodeSignTest仓库中的 macCodeSignTest.ts 对该流程进行了回归验证。测试用例describe.ifMac(macos keychain)中create keychain以 Base64 编码的.p12证书p12Base64与密码构造CreateKeychainOptions调用createKeychain断言返回的keychainFile非空随后removeKeychain清理create keychain with installers验证带安装器证书cscILink场景的钥匙串创建路径。这两个用例仅在 macOSifMac上运行且顺序执行sequential: true直接覆盖了被修复的importCerts路径确保createKeychain在真实security工具链上能够成功完成导入与分区列表配置。五、对使用者的影响与排查建议5.1 谁需要关注此次修复CI 中通过CSC_LINKCSC_KEY_PASSWORD签名的 macOS 构建本修复主要面向该场景在较新版本 macOS验证密码的版本上构建并遭遇SecKeychainUnlock: The user name or passphrase you entered is not correct的开发者直接使用app-builder-lib内部createKeychainAPI 的二次开发者。5.2 升级与验证建议升级app-builder-lib本修复作为 patch 随包发布升级到包含该 changeset 的版本即可获得修复若使用electron-builder顶层包请同步升级。回归验证命令在 macOS 上运行pnpm test -- macCodeSignTest或直接运行 macCodeSignTest.ts 所在测试套件确认临时钥匙串创建与清理正常。手动复现排查若仍出现密码错误可按以下顺序核对# 1) 确认 CSC_LINK 指向的证书可被解析 echo $CSC_LINK | head -c 64 # 2) 确认 CSC_KEY_PASSWORD 与 p12 文件导出时设置的密码一致 # 3) 观察构建日志中 create-keychain / import / set-key-partition-list 命令顺序权限与钥匙串搜索列表临时钥匙串必须位于用户钥匙串搜索列表list-keychains -d user -s中否则codesign无法发现其中的身份——这是与密码问题并列的另一个经典坑macCodeSign.ts 中的bundledCertKeychainAdded还会把内置根证书钥匙串一并加入搜索列表。六、总结本次 changeset 修复的虽是一行参数来源背后却是 macOS 钥匙串安全模型的两个不同密码域security import -P认证的对象是被导入的证书条目p12使用的是证书的导入密码security set-key-partition-list -k认证的对象是钥匙串数据库本身使用的是create-keychain时设定的钥匙串解锁密码。electron-builder 在 macCodeSign.ts 中修正了这一参数混用使CSC_LINK签名流程在验证密码的 macOS 版本上不再触发SecKeychainUnlock错误。理解这两条security子命令的语义边界不仅有助于排查 electron-builder 的签名问题也能帮助你在手写 macOS 签名脚本创建钥匙串 → 导入证书 → 配置分区列表 → codesign时避开同类陷阱。参考链接变更记录.changeset/fix-mac-keychain-partition-list-password.md核心实现packages/app-builder-lib/src/codeSign/mac/macCodeSign.ts证书解析packages/app-builder-lib/src/codeSign/codesign.ts调用方packages/app-builder-lib/src/macPackager.ts环境变量解析packages/app-builder-lib/src/platformPackager.ts测试用例test/src/mac/macCodeSignTest.ts【免费下载链接】electron-builderA complete solution to package and build a ready for distribution Electron app with “auto update” support out of the box项目地址: https://gitcode.com/gh_mirrors/el/electron-builder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考