 macOS Launch Agent 定时任务实践指南

这份指南将帮助你在 macOS 上通过 launchctl 正式配置并管理自动化任务。

1. 准备脚本

在配置定时任务之前，确保你的脚本可以独立运行且路径固定。

创建脚本 ：例如 ~/Scripts/backup.sh。
使用绝对路径 ：脚本内部涉及的路径（如 cd 或文件路径）请务必使用绝对路径，不要使用相对路径。
赋予执行权限：

bash 复制代码

chmod +x ~/Scripts/backup.sh

2. 创建 .plist 配置文件

Launch Agent 的配置文件存储在 ~/Library/LaunchAgents/ 目录下，文件名为 Label 名加 .plist 后缀。

文件位置 ：~/Library/LaunchAgents/com.user.myscript.plist

模板内容：

xml 复制代码

<?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.user.myscript</string> <key>ProgramArguments</key>
    <array>
        <string>/Users/你的用户名/Scripts/backup.sh</string> </array>

    -- 每天12点
    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>12</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
    -- 每隔3600s执行一次
    -- <key>StartInterval</key>
    -- <integer>3600</integer>

    <key>StandardOutPath</key>
    <string>/Users/你的用户名/Scripts/logs/backup.log</string> <key>StandardErrorPath</key>
    <string>/Users/你的用户名/Scripts/logs/backup_err.log</string> <key>RunAtLoad</key>
    <true/> </dict>
</plist>

3. 加载并启动任务

配置文件准备好后，需要手动告知系统加载它。

加载任务（让系统识别并按计划执行）：

bash 复制代码

launchctl load ~/Library/LaunchAgents/com.user.myscript.plist

验证状态：

bash 复制代码

launchctl list | grep com.user.myscript

如果第一列显示数字（PID），说明任务正在运行；如果第二列为 0，说明上次运行成功。

4. 常见配置选项说明

Key (键名)	说明	示例
Label	任务的唯一名称。	`com.apple.itunes`
ProgramArguments	程序的路径及参数数组。	`<array><string>/path/to/script</string></array>`
StartInterval	每隔多少秒触发一次任务。	`300` (每5分钟)
StartCalendarInterval	指定具体的日期/时间触发。	可以包含 `Minute`, `Hour`, `Day`, `Weekday`, `Month`
RunAtLoad	布尔值。加载 plist 或用户登录时是否立即运行一次。	`<true/>`
StandardOutPath	指定标准输出重定向的文件。	`/tmp/my.log`
WorkingDirectory	设置脚本执行时的初始工作目录。	`/Users/username/project`

5. launchctl 常用命令汇总

加载任务 ：launchctl load <path_to_plist>
卸载任务 ：launchctl unload <path_to_plist> (停止并移除计划)
立即触发一次 ：launchctl start <label_name> (用于测试，不论时间是否到达)
强制停止当前任务 ：launchctl stop <label_name>

6. 注意事项 ⚠️

路径权限：

LaunchAgents (在用户目录下)：以当前登录用户身份运行，适合个人任务。
LaunchDaemons (在系统目录下)：以 root 身份运行，适合系统级任务。

绝对路径 ：在 .plist 中，所有路径（包括脚本内调用的 python, node, git）最好都写成绝对路径（如 /usr/local/bin/python3），因为 launchctl 的环境变量与终端不同。
完全磁盘访问权限 (TCC)：

如果脚本需要访问照片、文稿、下载文件夹，必须在 系统设置 -> 隐私与安全性 -> 完全磁盘访问权限 中将 终端 或 /bin/sh 添加进去。

休眠问题：如果电脑在定时时间处于关机状态，任务会在下次开机后尽快补运行；如果是休眠状态，通常会在唤醒后运行。