macOS 定时任务排错：退出码、错误消息、旧结论，三个都不承载事实

一、结论先行

环境：macOS 26 Tahoe（26.6.2）。今天我要把自己过去关于 launchctl 的排查笔记整理成文，为了不写二手结论，逐条复现了一遍。结果是三条最硬的结论里，两条今天不成立。

先给结论表，后面逐条给证据：

#	你通常会用的判据	可信度	今天的实测证据
1	命令的退出码	❌ 不可信	成功时是 0，报错时也是 0
2	命令的 stderr 措辞	❌ 不可信	`Load failed: 5: Input/output error` 实为「重复加载」
3	旧笔记里的结论	⚠️ 会过期	「`list` 恒 0 行」「`bootstrap` 恒 EIO」今天均不成立
4	`launchctl print` 的状态输出	✅ 可信	唯一一个「读的是事实本身」的接口

二、陷阱 1：退出码只说明"命令跑完了"

最小可复现的材料是一个探针任务文件。注意它只有三行有效内容：

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.example.probe</string>
  <key>ProgramArguments</key><array><string>/bin/echo</string><string>probe</string></array>
  <key>RunAtLoad</key><false/>
</dict></plist>

加载它，第一次：

bash 复制代码

$ launchctl load -w /tmp/probe.plist ; echo "exit=$?"
（无输出）
exit=0

任务确实注册上了。同一条命令再跑一次：

bash 复制代码

$ launchctl load -w /tmp/probe.plist ; echo "exit=$?"
Load failed: 5: Input/output error
Try running `launchctl bootstrap` as root for richer errors.
exit=0

报了一大段错，退出码还是 0。

把三次操作放一起看：

操作	stdout/stderr	退出码	实际结果
加载任务（首次）	（空）	0	成功
加载任务（重复）	`Load failed: 5: Input/output error`	0	无需操作（已在）
查询不存在的任务	`Could not find service`	非 0	确实不存在

结论：这个命令的退出码在「成功」和「报错」两种情形下都是 0。 它表达的是"我执行完了"，不是"我做成了"。

最危险的是这种写法------它把"命令有没有说话"当成了"事情成没成"：

bash 复制代码

launchctl load -w /tmp/probe.plist 2>&1 && echo "  ✅ 加载成功" || echo "  ❌ 加载失败"

实测输出：

lua 复制代码

Load failed: 5: Input/output error
  ✅ 加载成功

屏幕上写着 Load failed，脚本判定"成功"。

三、陷阱 2：错误消息的措辞 ≠ 严重程度

Input/output error 看起来像磁盘故障。我一开始就是这么理解的，为此查过文件格式、权限、扩展属性、路径，全部正常。

真相：它只是表示「这个任务已经在加载状态了」。

对照实验（同一台机器、同一个文件、同一条命令，唯一变量是"第几次"）：

	输出	含义
第 1 次加载全新任务	（静默）	真正加载成功
第 2 次加载同一任务	`Load failed: 5: Input/output error`	重复操作，无害

反过来，真正的失败 （任务根本没能注册）给出的是一条语气平淡的 Could not find service。

措辞的严重程度和事实的严重程度不相关。 按"消息看起来多吓人"分配注意力，会把时间花在不存在的故障上。

四、陷阱 3：旧笔记里的"必然"，只是"当时"

我笔记里的两条（都是当时实测多次的）：

launchctl list 在本机返回 0 行，是假信号，不可信；
本机 GUI domain 的写入通道被锁，bootstrap 新任务必然 Input/output error。

今天重跑：

bash 复制代码

$ launchctl list | wc -l
     565

$ launchctl bootstrap gui/$(id -u) /tmp/probe.plist ; echo "exit=$?"
（无输出）
exit=0

565 行，一次成功。 我什么都没改；变的是环境（系统升级、机器重启）。

笔记里的结论	观测于	今天实测
`launchctl list` 恒返回 0 行	9 月中旬	565 行
`bootstrap` 恒报 EIO	9 月中旬	exit 0，成功注册
`load` 报错但退出码 0	9 月中旬	✅ 仍成立

这是最隐蔽的一个陷阱：它不报错。 你带着一条过期结论去排查，会非常自信地在错误的前提上耗一整天。

处置纪律：任何「必然／永远／一定」式结论必须带观测时间与环境；超过一段时间未复验，只当线索，不当事实。

五、判据设计：一个信号 + 三层验证

把三个陷阱归拢，判据应该收敛到只读事实本身的那个接口：

bash 复制代码

launchctl print gui/$(id -u)/<label>

它输出结构化字段（state / pid / program / path），不是给人读的措辞，所以不会被措辞骗。

围着它，落到一个 35 行的检查脚本 launchd-check.sh：

bash 复制代码

#!/bin/bash
# launchd-check.sh --- 判断一个 LaunchAgent 到底活没活
# 用法: bash launchd-check.sh <label> [期望端口]
# 设计原则：只信 launchctl print，不信退出码、不信 stderr 文案。
set -u
label="${1:-}"
port="${2:-}"
if [ -z "$label" ]; then echo "用法: bash launchd-check.sh <label> [port]"; exit 2; fi

domain="gui/$(id -u)"
out=$(launchctl print "$domain/$label" 2>/dev/null)
if [ -z "$out" ]; then
  echo "FAIL  ${label}  未注册（print 无输出）"
  exit 1
fi

state=$(printf '%s\n' "$out" | awk -F'= ' '/^[[:space:]]*state =/{print $2; exit}')
pid=$(printf '%s\n' "$out"   | awk -F'= ' '/^[[:space:]]*pid =/{print $2; exit}')
prog=$(printf '%s\n' "$out"  | awk -F'= ' '/^[[:space:]]*program =/{print $2; exit}')

echo "OK    ${label}"
echo "      state = ${state:-?}"
echo "      pid   = ${pid:-（无）}"
echo "      prog  = ${prog:-?}"

rc=0
if [ -n "$port" ]; then
  if lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then
    echo "      port  = ${port} 正在监听"
  else
    echo "      port  = ${port} 无监听  <-- state 是 not running 时属正常"
    rc=3
  fi
fi
exit $rc

三层验证，缺一层都会漏：

层	查什么	回答的问题
L1	`launchctl print` 有输出、`state` 字段	配置有没有生效（调度器认不认这个任务）
L2	进程号 `pid` / 端口是否 `LISTEN`	服务有没有真的起来
L3	该任务应当产出的文件／记录	它有没有真的干活（见第六节）

实测三组：

场景	命令	输出	退出码
已注册的任务	`bash launchd-check.sh com.example.digest`	`OK state = not running`	0
不存在的任务	`bash launchd-check.sh com.example.nope`	`FAIL 未注册（print 无输出）`	1
已注册 + 端口	`bash launchd-check.sh com.example.digest 14013`	`OK state = not running` + `port 14013 正在监听`	0

第三组值得单独看：任务的 state 是 not running，但它负责的端口正在监听。 这不矛盾------state = not running 指的是"这个任务当前没有正在执行的进程"（它是一个定点触发的任务，没到点就该 idle），而端口在听说明它之前拉起的服务还活着。

所以 L1 和 L2 都要看：L1 判断"我有没有配错"，L2 判断"它有没有真起来"。

六、第四层：产出检查------"退出码 0"的另一个骗法

同一个坑还有第二种形态：任务每天都跑、每天都退出码 0、从来不报错，但什么也没干。

我机器上两个每天定时任务的对照：

任务 A（每天 08:30，生成知识库更新摘要）------日志逐日可查，有真实产出：

csharp 复制代码

[2026-10-04 08:30:01] 已生成 ...（181 篇更新，50299 字符）
[2026-10-08 08:30:02] 已生成 ...（24 篇更新，4333 字符）
[2026-10-09 08:30:01] 已生成 ...（2 篇更新，778 字符）

任务 B（每天 22:00，同步知识库）------日志每天也有，退出码也正常，但产出恒为空：

sql 复制代码

日期 2026-10-03 | 会话 0 个 | 摘要文件 无 | 回流 skip
日期 2026-10-04 | 会话 0 个 | 摘要文件 无 | 回流 skip
...（连续六天，全是同一行）

两个任务的退出码完全一样 。只看"有没有报错"，两个都健康；看产出，一个在干活，一个连续六天空转。

所以第四层判据是：监控必须落到"它应该产出的那个东西"上 ------文件、记录、端口都行，但必须是能被独立查看的结果，而不是程序自己的一句"我完成了"。

七、复现清单

本文所有命令均为写作当日在 macOS 26.6.2 实测所得，未引用旧笔记。

文件	行数	说明
`launchd-check.sh`	35	只信 `launchctl print` 的定时任务健康检查脚本；支持可选的端口校验

复现步骤：

bash 复制代码

# 1. 造一个无副作用的探针任务（RunAtLoad=false，不会常驻）
#    见第二节 plist，存为 /tmp/probe.plist

# 2. 陷阱 1：观察退出码在「成功」与「重复」两种情形下都是 0
launchctl load -w /tmp/probe.plist ; echo "exit=$?"   # 首次：静默，0
launchctl load -w /tmp/probe.plist ; echo "exit=$?"   # 重复：报 EIO，仍是 0

# 3. 陷阱 2：确认那条 EIO 只是「重复加载」
launchctl print gui/$(id -u)/com.example.probe        # 已注册 = 第一次其实成功了

# 4. 陷阱 3：用状态查询而不是 list/退出码判活
launchctl list | wc -l                                # 行数随环境变化，不可作判据
launchctl print gui/$(id -u)/<label>                  # 唯一可信的读接口

# 5. L1+L2：跑检查脚本
bash launchd-check.sh <label> [port]

八、一句话总结

退出码回答"命令跑完了没有"，错误消息回答"程序员当时想说什么"，旧笔记回答"那天发生了什么"------只有状态查询回答"现在是什么"。

写给自动化做判据的时候，先把这三样从判据里剔出去。