使用 SecKeychainAddGenericPassword 存令牌前必须用 CFStringCreateWithBytes 构造 UTF-8 编码的 CFStringRef，并显式设置 kSecAttrAccessGroup（如 "com.example.myapp.keychain"），且需在 Xcode 中启用 Keychain Sharing、在 entitlements 中声明 com.apple.security.keychain-access-groups 权限，否则沙盒下静默失败。
用 SecKeychainAddGenericPassword 存令牌前必须处理 UTF-8 编码和访问组
macOS Keychain 不接受裸字符串，CFStringRef 必须由 UTF-8 字节构造，且需显式指定访问组（kSecAttrAccessGroup）才能跨进程/沙盒读取。不设访问组时，令牌默认绑定到当前应用的临时组，重启或升级后可能丢失。
常见错误是直接传 std::string.c_str() 给 SecKeychainAddGenericPassword，这会触发 errSecParam 错误。正确做法是用 CFStringCreateWithBytes 构造带编码声明的字符串：
CFStringRef service = CFStringCreateWithBytes(
kCFAllocatorDefault,
reinterpret_cast<const UInt8*>(service_name.c_str()),
service_name.length(),
kCFStringEncodingUTF8,
false
);- 服务名（
service）建议用 Bundle ID 格式，如"com.example.myapp" - 账户名（
account）可用用户唯一标识，如邮箱哈希值，避免明文邮箱 - 必须传
kSecAttrAccessGroup，值为字符串（如"com.example.myapp.keychain"），且需在 Xcode 的 Signing & Capabilities 中勾选 Keychain Sharing 并添加同一组名
用 SecKeychainFindGenericPassword 检索时要手动释放内存并检查返回码
Keychain API 返回的密码数据是原始字节指针（void**）和长度（UInt32*），不会自动管理内存，忘记调用 SecKeychainItemFreeContent 会导致内存泄漏；而返回码为 errSecItemNotFound 是正常情况（非异常），不应抛 C++ 异常。
典型误操作是把 *passwordData 当作 null-terminated C 字符串直接 std::string 构造，结果读到乱码或崩溃 —— 因为 Keychain 存的是二进制 blob，不保证结尾有 \0。
立即学习“C++免费学习笔记（深入）”；
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 检索后必须检查返回值：
if (status == errSecSuccess)才继续 - 用
std::string(reinterpret_cast<char>(*passwordData), *passwordLength)</char>安全构造 - 立即调用
SecKeychainItemFreeContent(nullptr, *passwordData)，第一个参数传nullptr即可 - 若应用启用了 Hardened Runtime，还需在
entitlements文件中添加keychain-access-groups权限项
沙盒环境下必须配置 com.apple.security.keychain-access-groups entitlement
Mac App Store 上架或启用沙盒的应用，即使代码完全正确，也会因权限缺失静默失败 —— SecKeychainAddGenericPassword 返回 errSecInteractionNotAllowed，SecKeychainFindGenericPassword 返回 errSecNotAvailable，但控制台无提示。
这不是代码 bug，而是系统级拦截。Xcode 自动生成的 entitlements 文件默认不含 Keychain 权限，必须手动添加：
<key>com.apple.security.keychain-access-groups</key>
<array>
<string>com.example.myapp.keychain</string>
</array>- 数组中字符串必须与代码中传给
kSecAttrAccessGroup的值严格一致（包括大小写和点号） - 若用 macOS 13+ 的 App Sandbox + Notarization 流程，还需在 Xcode 的 Signing & Capabilities → Keychain Sharing 中启用，并确保 Team 已在 Apple Developer Portal 配置对应 Access Group
- 调试时可在终端运行
codesign -d --entitlements :- /path/to/app验证 entitlement 是否生效
避免用 SecKeychainItemCopyAttributesAndData 替代标准流程
有些示例用这个函数“一步获取所有字段”，但它在沙盒下更易失败，且返回的 CFTypeRef 属性字典结构不稳定（比如 kSecAttrCreationDate 可能为 NULL），还额外增加内存管理复杂度。标准的 Add/Find 流程足够可靠，也更易测试。
另一个坑是混淆 SecKeychainItemRef 和 SecKeychainRef：前者是单个条目句柄，后者是钥匙串文件句柄。绝大多数场景只需用默认钥匙串（nullptr），无需调用 SecKeychainCopyDefault —— 多此一举反而可能因权限问题失败。
- 不要尝试用
SecKeychainItemModifyAttributesAndData更新令牌，直接Delete + Add更安全（Keychain 不支持原子更新） - 删除操作要用
SecKeychainFindGenericPassword先查出SecKeychainItemRef，再传给SecKeychainItemDelete，不能只靠 service/account 删除 - Release 模式下务必关闭 Keychain 调试日志（
SecKeychainSetPreferenceDomain等调试 API 仅限开发使用）
Keychain 的坑不在 API 复杂，而在 macOS 安全模型层层叠加：编码、访问组、entitlement、沙盒、签名、notarization —— 少一个环节，就静默失败。最常被忽略的是 entitlement 文件没同步更新，或者 Xcode 自动勾选了 Keychain Sharing 却没填对 Access Group 字符串。
