macOS下launchctl加载plist服务初始化失败报错如何解决

你遇到的报错对应多个配置错误，按报错信息逐一对应：

• 报错UserName is not supported for non-System services：用户级的launchd服务（存放在~/Library/LaunchAgents/目录下）默认以当前登录用户身份运行，不需要额外配置UserName字段，该字段仅对系统级服务有效。
• 错误码78/初始化失败0x1：通常是launchd无法执行你指定的脚本，常见原因有两个：一是s3-sync.sh没有可执行权限，二是你配置的日志文件路径不存在/无读写权限。
• 错误码127：属于shell执行错误，代表命令找不到，对应两个错误：一是你脚本里dot_clean的目标路径少了根路径前缀/，写为了Users/jacksonbockus/fvtt而非正确的/Users/jacksonbockus/fvtt；二是launchd运行时没有当前用户的PATH环境变量，你脚本里写的fswatch、aws的绝对路径可能和本机实际安装路径不一致（比如M1系列Mac的homebrew命令默认路径为/opt/homebrew/bin/，而非Intel芯片的/usr/local/bin/）。
• 服务效率低警告：是因为你配置了KeepAlive=true让脚本常驻后台运行，launchd本身自带目录变更监听能力，不需要手动跑fswatch做循环监听。

1. 修正shell脚本并赋权 #

先修改s3-sync.sh，修正路径错误，同时确认命令绝对路径和本机一致：

#!/bin/zsh
# 可先在终端执行 which fswatch、which aws 确认路径和下方一致
/usr/local/bin/fswatch /Users/jacksonbockus/fvtt | (while read; do 
    /usr/sbin/dot_clean /Users/jacksonbockus/fvtt;
    /usr/local/bin/aws s3 sync /Users/jacksonbockus/fvtt s3://jbockus-fvtt/ --delete --acl public-read;
done;)

给脚本添加可执行权限：
chmod +x /Users/jacksonbockus/Documents/Dev/aws/s3-sync.sh

提前创建日志文件并赋权，避免写入失败：

touch /Users/jacksonbockus/Documents/Dev/aws/s3-out.txt /Users/jacksonbockus/Documents/Dev/aws/s3-err.txt
chmod 644 /Users/jacksonbockus/Documents/Dev/aws/s3-out.txt /Users/jacksonbockus/Documents/Dev/aws/s3-err.txt

2. 修正plist配置 #

删除UserName字段，保留日志输出配置方便排查，修改后内容如下：

<?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.jacksonbockus.dnd.sync</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/jacksonbockus/Documents/Dev/aws/s3-sync.sh</string>
    </array>
    <key>KeepAlive</key>
    <true/>
    <key>RunAtLoad</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/jacksonbockus/Documents/Dev/aws/s3-out.txt</string>
    <key>StandardErrorPath</key>
    <string>/Users/jacksonbockus/Documents/Dev/aws/s3-err.txt</string>
</dict>
</plist>

3. 重新加载服务 #

先卸载之前加载的错误服务：
launchctl unload -w ~/Library/LaunchAgents/com.jacksonbockus.dnd.sync.plist
将修改后的plist放到用户级服务目录：
cp 你存放plist的路径/s3-sync.plist ~/Library/LaunchAgents/com.jacksonbockus.dnd.sync.plist
重新加载服务：
launchctl load -w ~/Library/LaunchAgents/com.jacksonbockus.dnd.sync.plist

4. 错误排查 #

如果仍有异常，直接查看日志文件即可定位具体问题：
cat /Users/jacksonbockus/Documents/Dev/aws/s3-err.txt

不需要手动跑fswatch做常驻监听，直接用launchd自带的目录变更触发能力，资源占用更低、稳定性更高：

1. 简化s3-sync.sh，仅保留同步逻辑：

#!/bin/zsh
/usr/sbin/dot_clean /Users/jacksonbockus/fvtt;
/usr/local/bin/aws s3 sync /Users/jacksonbockus/fvtt s3://jbockus-fvtt/ --delete --acl public-read;

2. 修改plist配置，去掉KeepAlive，增加WatchPaths和触发间隔配置：

<?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.jacksonbockus.dnd.sync</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/jacksonbockus/Documents/Dev/aws/s3-sync.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>WatchPaths</key>
    <array>
        <string>/Users/jacksonbockus/fvtt</string>
    </array>
    <key>ThrottleInterval</key>
    <integer>5</integer>
    <key>StandardOutPath</key>
    <string>/Users/jacksonbockus/Documents/Dev/aws/s3-out.txt</string>
    <key>StandardErrorPath</key>
    <string>/Users/jacksonbockus/Documents/Dev/aws/s3-err.txt</string>
</dict>
</plist>

其中ThrottleInterval为触发间隔（单位秒），避免短时间多次变更频繁触发同步，可自行调整。

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