在 macOS 上，如果你想让某个脚本、同步程序、命令行工具或小型服务在“用户登录后自动启动”，最稳妥的做法通常是使用 LaunchAgents。它由系统的 launchd 负责调度，能做到开机后登录即运行、崩溃自动拉起、按条件触发等。
简单区分：LaunchAgents 运行在当前用户会话（GUI）下；LaunchDaemons 运行在系统级（通常需要管理员权限）。本文聚焦 LaunchAgents，风险更低、权限更清晰，也更适合日常提效。
最常用目录是：~/Library/LaunchAgents/。每个任务是一个 .plist 文件，文件名一般用反向域名风格，例如 com.example.autostart.demo.plist，方便管理和检索。
建议你先建立一个“自启任务清单”，把每个任务对应的：用途、入口命令、日志路径、启停命令写在同一个文档里，后续排错效率会高很多。
下面给出一个尽量通用的模板，你可以把其中的路径替换成自己的。注意：命令路径尽量写绝对路径，避免因为开机环境变量不同导致找不到程序。
<? 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.autostart.demo</string> <key>ProgramArguments</key> <array> <string>/bin/zsh</string> <string>-lc</string> <string>echo "Hello" >> "$HOME/Library/Logs/autostart-demo.log"</string> </array> <key>RunAtLoad</key> <true/> <key>StandardOutPath</key> <string>/Users/yourname/Library/Logs/autostart-demo.out.log</string> <key>StandardErrorPath</key> <string>/Users/yourname/Library/Logs/autostart-demo.err.log</string> </dict> </plist>
这里用 /bin/zsh -lc 的原因是：让命令在更接近交互式 shell 的环境里执行，但依然建议把关键路径写死，别完全依赖 shell 配置。
推荐用新版语义（bootstrap/bootout），并明确目标域是当前用户 GUI 会话。常用命令如下（把 Label 和 plist 路径替换成你的）：
mkdir -p ~/Library/LaunchAgents
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.autostart.demo.plist
launchctl kickstart -k gui/$(id -u)/com.example.autostart.demo
launchctl print gui/$(id -u)/com.example.autostart.demo
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.example.autostart.demo.plist
如果你更习惯列表查询：launchctl list | grep com.example.autostart 也能快速确认是否加载成功。
很多任务需要等网络、挂载盘、登录完成后再启动。最简单的方式是在命令里先 sleep，但更推荐两种更可控的方案：
1) 在 ProgramArguments 中包装一层脚本：先检测网络/目录存在，再启动主程序；如果条件未满足就退出，让 launchd 之后再按需拉起。
2) 对于需要定时触发的任务，用 StartInterval 或 StartCalendarInterval 做“周期性检查”，避免一次失败就永远错过。
示例思路（伪代码）：while ! ping -c1 1.1.1.1; do sleep 5; done; start_your_app。注意：这里是为了说明思路，不建议无限循环卡住；更好的方式是失败退出并让系统重新调度。
遇到自启失败，按这个顺序排查通常最快：
1) 路径是否绝对：GUI 登录后的环境变量可能没有你在终端里那套 PATH。把可执行文件写成绝对路径，或用 /bin/zsh -lc 明确调用。
2) 权限与沙盒：某些应用需要“辅助功能/完全磁盘访问/后台项目”权限。先在系统设置里确认相关权限是否已允许。
3) 日志：优先看 StandardOutPath/StandardErrorPath 指向的文件；其次用 Console.app 过滤你的 Label 或进程名。
4) 状态打印：执行 launchctl print gui/$(id -u)/你的Label，看 LastExitStatus、最近一次启动时间与错误信息。
5) plist 格式： 不合法会直接加载失败。任何引号、尖括号都要小心；必要时用在线 plist 校验器检查结构。
launchctl 手册：https://www.manpagez.com/man/1/launchctl/
launchd.plist 关键字段说明：https://www.manpagez.com/man/5/launchd.plist/
Apple 官方：后台项目与登录项相关说明（随系统版本可能变化）：https://support.apple.com/zh-cn/guide/mac-help/mh15189/mac
最后建议你把每个 LaunchAgent 的 plist、入口脚本、日志路径统一放在一个目录（或用 Git 管理），并在文件头部写清用途与回滚方式。自启不是“写一次就结束”，而是长期运维资产：可观察、可停用、可迁移，才算真正稳定。
