macOS主应用启动捆绑辅助程序失败，求解决Load failed报错

核心问题分析 #

你遇到的报错本质是以下几个配置错误叠加导致：

• launchctl load未指定plist完整路径，系统无法定位文件
• Launch Agent的plist被错误放置在主应用包内，launchctl不会扫描该目录加载Agent
• plist中BundleProgram路径配置不符合规范
• 旧版launchctl load命令在现代macOS（Ventura及以后）兼容性差，官方推荐使用bootstrap

分步解决步骤 #

1. 修正Launch Agent plist配置

修改com.example.helper.agent.plist，替换BundleProgram为Program（后续会用绝对路径填充），可选添加KeepAlive确保进程持续运行：

<?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>
    <key>Label</key>
    <string>com.example.helper.agent</string>
    <key>Program</key>
    <string></string>
    <key>MachServices</key>
    <dict>
        <key>com.example.helper.agent</key>
        <true/>
    </dict>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

2. 调整文件复制逻辑

• 将helper-agent通过「复制捆绑资源」复制到主应用的Contents/Resources目录
• 移除Build Phase中复制plist到应用包内的步骤，改为在代码中动态复制到用户级LaunchAgents目录（~/Library/LaunchAgents）

3. 重写启动辅助程序的代码

替换原applicationDidFinishLaunching中的代码，完成路径拼接、plist复制、权限设置和Agent加载：

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    // 获取主应用与辅助程序路径
    NSString *appBundlePath = [[NSBundle mainBundle] bundlePath];
    NSString *helperPath = [appBundlePath stringByAppendingPathComponent:@"Contents/Resources/helper-agent"];
    
    // 处理plist的复制与路径更新
    NSString *sourcePlistPath = [appBundlePath stringByAppendingPathComponent:@"Contents/Library/LaunchAgents/com.example.helper.agent.plist"];
    NSString *userLaunchAgentsDir = [NSHomeDirectory() stringByAppendingPathComponent:@"Library/LaunchAgents"];
    NSString *destPlistPath = [userLaunchAgentsDir stringByAppendingPathComponent:@"com.example.helper.agent.plist"];
    
    NSMutableDictionary *plistDict = [NSMutableDictionary dictionaryWithContentsOfFile:sourcePlistPath];
    if (plistDict) {
        // 更新plist中的辅助程序绝对路径
        plistDict[@"Program"] = helperPath;
        [plistDict writeToFile:destPlistPath atomically:YES];
        
        // 确保辅助程序拥有可执行权限
        [[NSFileManager defaultManager] setAttributes:@{NSFilePosixPermissions: @0755} ofItemAtPath:helperPath error:nil];
        
        // 使用现代launchctl bootstrap命令加载Agent
        NSTask *task = [NSTask new];
        task.launchPath = @"/bin/launchctl";
        NSString *userDomain = [NSString stringWithFormat:@"gui/%d", getuid()];
        task.arguments = @[@"bootstrap", userDomain, destPlistPath];
        
        // 捕获命令输出用于调试
        NSPipe *pipe = [NSPipe pipe];
        task.standardOutput = pipe;
        task.standardError = pipe;
        
        [task launch];
        [task waitUntilExit];
        
        NSData *outputData = [[pipe fileHandleForReading] readDataToEndOfFile];
        NSString *outputString = [[NSString alloc] initWithData:outputData encoding:NSUTF8StringEncoding];
        NSLog(@"Launchctl执行结果: %@", outputString);
    }
}

4. 调试验证方法

• 运行主应用后，检查~/Library/LaunchAgents/com.example.helper.agent.plist是否存在，且Program路径正确
• 执行命令launchctl list com.example.helper.agent，若返回进程ID则说明加载成功
• 若仍报错，手动执行sudo launchctl bootstrap gui/$(UID) ~/Library/LaunchAgents/com.example.helper.agent.plist查看详细错误信息

额外注意事项 #

• 若主应用启用了App Sandbox，需在Entitlements中添加com.apple.security.files.user-selected.read-write权限，或配置App Group实现主应用与辅助程序的通信
• 辅助程序需进行代码签名，否则在受限环境下无法运行

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