macOS 用 launchd 创建可靠的定时任务

macOS 推荐用 launchd 管理后台和定时任务。每个任务由属性列表（Property List，plist）描述。用户登录后运行的任务放在 ~/Library/LaunchAgents；系统级守护任务放在 /Library/LaunchDaemons，需要管理员权限。

一、准备脚本

创建 ~/Scripts/disk-report.sh：

#!/bin/zsh
/bin/date
/bin/df -h /

chmod 700 ~/Scripts/disk-report.sh
mkdir -p ~/Library/Logs ~/Library/LaunchAgents

launchd 环境变量很少，脚本中应使用 /bin/date 这类绝对路径，不能假设交互终端中的 PATH、Homebrew 和别名都存在。

二、编写 LaunchAgent

保存为 ~/Library/LaunchAgents/site.cnsz.disk-report.plist：

<?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>site.cnsz.disk-report</string>
  <key>ProgramArguments</key><array>
    <string>/Users/你的用户名/Scripts/disk-report.sh</string>
  </array>
  <key>StartCalendarInterval</key><dict>
    <key>Hour</key><integer>9</integer>
    <key>Minute</key><integer>0</integer>
  </dict>
  <key>StandardOutPath</key><string>/Users/你的用户名/Library/Logs/disk-report.log</string>
  <key>StandardErrorPath</key><string>/Users/你的用户名/Library/Logs/disk-report.err</string>
</dict></plist>

必须把路径改成实际绝对路径。每天 9:00 运行一次；Mac 睡眠错过基于日历的任务时，唤醒后的行为与关机错过不同，关键任务应实际测试。

三、校验、加载和触发

plutil -lint ~/Library/LaunchAgents/site.cnsz.disk-report.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/site.cnsz.disk-report.plist
launchctl kickstart -k gui/$(id -u)/site.cnsz.disk-report
launchctl print gui/$(id -u)/site.cnsz.disk-report

修改 plist 前先卸载：

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/site.cnsz.disk-report.plist

四、排障

先看 StandardOutPath、StandardErrorPath，再检查脚本是否可执行、路径是否存在、任务运行用户是否有目录权限。访问桌面、文稿等隐私目录还可能受到 macOS 隐私控制，需要为实际执行程序授予权限。

不要把密码或令牌直接写入 plist，因为普通用户可能读取文件。需要凭据时使用钥匙串（Keychain）或权限受控的配置。定时任务必须具备幂等性：重复执行不应重复删除或覆盖重要数据。

本文为中文学习整理。资料来源：Apple Developer：Scheduling timed jobs。