用途
macOS 的 TCC(透明度、同意与控制)基于应用的 Bundle ID 加代码签名来授予屏幕录制、麦克风、辅助功能等权限。使用临时签名(CODE_SIGN_IDENTITY="-")时,每次重新构建都会产生不同的签名哈希,macOS 会将其视为新应用并撤销已授予的权限,导致用户每次构建后都要重新授权。本技能用于创建并统一使用一个自签名代码签名证书,使同一 Bundle ID 加同一证书在 TCC 看来就是同一应用身份,权限可在反复重建后持续有效。
主要能力
- 一次性创建自签名代码签名证书(默认有效期 10 年),导入登录钥匙串并设置 codesign 信任
- 通过 XcodeGen(project.yml)统一配置 CODE_SIGN_IDENTITY、CODE_SIGNING_ALLOWED、CODE_SIGN_STYLE 等签名设置
- 给出 UI 测试目标(bundle.ui-testing)必须将 BUNDLE_LOADER 与 TEST_HOST 置空的覆盖配置,避免嵌入 .xctest 后 codesign 失败
- 提供首次运行后授予权限的构建与启动命令
- 可集成到项目的 init.sh 初始化脚本中,在构建前检查并创建证书
- 提供证书未找到、codesign 报 “bundle format unrecognized, invalid, or unsuitable”、重建后权限仍被撤销、构建时提示 “User interaction is not allowed” 等问题的排查步骤,以及删除证书并回退到临时签名的方法
使用方式
整体流程分三步:
- 一次性创建证书:设定证书名(建议与项目同名),先检查是否已存在;不存在时用 openssl 生成自签名证书与密钥,再用 security import 导入登录钥匙串、security add-trusted-cert 设为信任根,最后清理临时文件并用 security find-identity 验证。创建过程中用户可能看到一次钥匙串访问确认对话框,这属于一次性授权。
- 配置项目:在 project.yml 的 base 设置中指定 CODE_SIGN_IDENTITY 与证书名完全一致、CODE_SIGNING_ALLOWED 为 YES、CODE_SIGN_STYLE 为 Manual,并将 ENABLE_HARDENED_RUNTIME 设为 NO(开发构建下强化运行时会使 codesign 拒绝嵌入的测试包)。UI 测试目标需额外将 BUNDLE_LOADER 与 TEST_HOST 覆盖为空。修改后运行 xcodegen generate 重新生成工程;不要手动编辑 .xcodeproj,因为它属于生成物,会被下一次生成覆盖。
- 首次运行授予权限:用 xcodebuild 构建并启动应用,在“系统设置 > 隐私与安全性”中授予屏幕录制、麦克风、辅助功能等所需权限。
若项目有 init.sh,可在构建步骤之前加入证书存在性检查与创建逻辑。
适用场景
- 需要在多次重建之间保持屏幕录制、麦克风、辅助功能等 TCC 权限的 macOS 应用开发
- 依赖权限弹窗的 XCUITests 自动化测试与 CI/CD 流程
- 由自动化智能体实现并验证依赖权限的功能
限制与注意事项
- 资料仅描述自签名证书方案,未提供其他签名或分发方式的说明
- 证书名必须在 project.yml 与创建脚本中保持一致,否则权限仍会在重建后被撤销
- UI 测试目标未清空 BUNDLE_LOADER/TEST_HOST,或存在过期 DerivedData 时,codesign 会出现 “bundle format unrecognized, invalid, or unsuitable” 错误
- 构建时若提示钥匙串锁定,需先用 security unlock-keychain 解锁登录钥匙串
- 删除证书使用 security delete-identity -c "MyApp Dev",之后应将 project.yml 回退为临时签名(CODE_SIGN_IDENTITY: "-")并重新运行 xcodegen generate
- 资料的命令与配置示例未涉及具体收费、价格或平台支持范围等信息,暂未提供