macos-softwareupdate-failed

macOS 软件更新检查、下载或安装失败时的定位与修复

现象

“系统设置 > 通用 > 软件更新”一直转圈，提示“无法检查更新”“下载时发生错误”“准备更新时出错”或“安装失败”；终端执行 softwareupdate --list 报无法连接服务器、网络不可用或证书错误。也有更新已经下载却反复提示重启，或重启后仍在旧版本。受 MDM 管理的设备可能显示“更新已被推迟”“需要管理员批准”，甚至根本看不到新版本。

更新链路包含检查目录、下载、校验、准备快照、安装和重启几个阶段，不同阶段失败原因不同。先确认失败发生在哪一步，再分别排查空间、网络、配置描述文件和系统状态，避免反复点“重试”。

快速定位

先看系统版本、可用更新和安装历史：

sw_vers
softwareupdate --list --verbose
softwareupdate --history
system_profiler SPSoftwareDataType SPInstallHistoryDataType

--list 负责扫描目录，--history 只显示通过 softwareupdate 安装的记录；system_profiler SPInstallHistoryDataType 还能看到系统更新、安全响应和 XProtect 等记录。再检查空间和更新卷：

df -h /
df -h /System/Volumes/Update
diskutil apfs list
diskutil info /
tmutil listlocalsnapshots /

大型更新需要下载、解包、创建快照和准备安装环境，数 GB 到数十 GB 的空间都可能被占用。/System/Volumes/Update 容量不足时安装会在准备阶段失败；diskutil apfs list 和 tmutil listlocalsnapshots 用来看容器余量和可回收快照。

检查网络和更新服务：

scutil --dns
curl -sS -o /dev/null -w '%{http_code}\n' --max-time 10 https://swscan.apple.com
curl -sS -o /dev/null -w '%{http_code}\n' --max-time 10 https://swdist.apple.com
curl -sS -o /dev/null -w '%{http_code}\n' --max-time 10 https://gdmf.apple.com/v2/pmv

如果域名解析失败、返回代理错误或 TLS 证书错误，先按 DNS 和代理问题排查；根路径返回 404 不代表链路失败，重点看解析、超时和 TLS 错误。企业网络常见拦截 Apple 更新域名、强制代理或 TLS 检查；VPN、内容过滤器和安全软件也可能造成同样现象。

最后读更新相关日志和受管设置：

/usr/bin/log show --last 1h --style compact \
  --predicate 'process == "softwareupdated" OR process == "installd"'
tail -n 100 /var/log/install.log
grep -i -E 'error|fail|denied|space' /var/log/install.log | tail -50
defaults read /Library/Preferences/com.apple.SoftwareUpdate
sudo defaults read "/Library/Managed Preferences/com.apple.SoftwareUpdate"
sudo profiles show -type configuration

/var/log/install.log 记录下载、校验和安装阶段的具体错误；/usr/bin/log 可以避免与 zsh 的同名内建命令冲突。/Library/Managed Preferences 和配置描述文件用于判断是否有 MDM 下发的更新限制；声明式设备管理下发的设置可能不在 profiles show 中，需要在 MDM 控制台确认。

常见根因

1. 可用空间不足，尤其是下载完成后在准备、快照或安装阶段失败。
2. DNS、代理、防火墙、VPN 或内容过滤器拦截 Apple 更新域名，或 TLS 检查导致证书校验失败。
3. 系统时间明显不准，证书和签名校验失败。
4. MDM 或配置描述文件设置了更新推迟、强制期限、允许类型或管理员批准。
5. 设备加入了 Beta 更新通道，或残留的测试配置导致正式版不可见。
6. 更新缓存或暂存目录损坏，反复使用同一个损坏的下载包。
7. softwareupdated、installd 等进程卡住，或上一次安装留下未完成状态。
8. 电池电量不足或未接电源时，系统会推迟大型更新；部分机型要求连接电源才能安装。
9. 磁盘或 APFS 文件系统异常，无法创建快照或写入更新卷。
10. 标准用户权限不足，或 Apple 芯片机型要求设备所有者认证。
11. 第三方安全软件、旧内核扩展或启动安全策略阻止安装器。
12. 更新已从目录撤回，或该机型不支持此版本。

修复

空间不足时先释放空间，再重新检查更新。目标不是刚好够下载，而是给解包、快照和安装留出余量；清理方法见站内的磁盘满页面。可以先用 tmutil thinlocalsnapshots 回收本地快照，再确认 /System/Volumes/Update 所在容器有余量。更新过程中不要手动删除 /System/Volumes/Update 或正在使用的快照。

网络问题按层排查：先确认 scutil --dns 和普通网页正常，再测试上面三个 Apple 域名；企业网络需要放行更新域名，代理环境要确保系统代理正确。临时断开 VPN 或内容过滤器复测，但不要长期关闭安全软件。系统时间用“系统设置 > 通用 > 日期与时间”校准，或执行：

sudo systemsetup -setusingnetworktime on
sudo sntp -S time.apple.com

配置描述文件或 MDM 限制不能靠反复重试绕过。先确认限制内容，再联系管理员调整推迟天数、强制期限或允许的更新类型；不要自行删除管理描述文件，它可能在下次检查时被重新下发。受管设备可以查看：

sudo profiles show -type configuration | grep -i -A 8 -E 'softwareupdate|defer|enforce'

如果更新进程卡住，先尝试重启系统；确认没有正在进行的安装后，可以重启更新守护进程，再重新扫描：

sudo launchctl kickstart -k system/com.apple.softwareupdated
softwareupdate --list --verbose

只有确认没有正在进行的安装时，才考虑清理 /Library/Updates 的残留下载，并先记录当前版本。不要删除 /System/Volumes/Update，也不要在安装过程中强制关机。

下载成功但安装失败时，改用分步方式获取详细输出：

sudo softwareupdate --download --all --verbose
sudo softwareupdate --install --all --verbose

--install --all --restart 会在需要时自动重启，执行前保存工作并确认没有其他安装任务。若错误指向签名或证书，先校准时间、排除 TLS 拦截，再重新下载；不要关闭 SIP 或降低安全策略来绕过校验。

反复失败且日志无明确结论时，可用安全模式排除第三方软件；仍失败再考虑恢复模式重装，重装前必须完成备份。最后用 sw_vers 和 softwareupdate --history 确认版本与安装记录，并完整走一次更新流程。

相关命令

• softwareupdate — 检查、下载和安装更新
• sw_vers — 确认当前系统版本
• system_profiler — 安装历史与硬件信息
• diskutil — 容器空间与文件系统状态
• defaults — 读取软件更新偏好
• launchctl — 重启更新守护进程
• curl — 验证更新服务连通性
• tmutil — 回收本地快照释放空间
• macOS 心智模型 — 系统更新与受管配置
• 磁盘已满 — 更新前的空间清理
• 磁盘只读 — 文件系统异常导致的安装失败

参考链接

• Apple 支持：更新 Mac 上的 macOS
• Apple 部署指南：为 Apple 设备安装和强制执行软件更新
• Apple 支持：使用 MDM 管理 macOS 更新

读完自测

合上页面，先回答，再展开对照。

1. softwareupdate --list 报无法连接服务器，应该先查什么？
2. 空间充足但更新反复失败，应该看哪些日志和状态？
3. MDM 设备看不到更新或无法安装，如何判断是限制导致的？