修复macOS 11.6上Electron的“dyld: Library not loaded: QuickLookUI.framework”错误

引言

最近部署的一个Electron 38项目，同事没法正常启动，抛出了以下错误：

dyld: Library not loaded: /System/Library/Frameworks/QuickLookUI.framework/Versions/A/QuickLookUI 
Referenced from: /Users/hfy/coco.bid-builder.app/web/desktop/node_modules/.pnpm/electron38.1.2/node modules/electron/dist/Electron.app/Contents/Frameworks/Electron Framework.framework/Versions/A/Electron Framework
Reason:image not found

如果你只关心解决方案，可以直接跳到文末的解决方案部分。

环境信息

• 系统版本：macOS Big Sur 11.6
• Electron 版本：38.1.2
• Node 版本：22.17.1
• 包管理器：pnpm

排查过程

步骤 1：确认系统框架是否存在

根据错误我理解应该是动态链接器（dyld）在运行时加载系统框架失败导致，首先应该检查系统 QuickLookUI.framework 是否真实存在：

ls -l /System/Library/Frameworks/QuickLookUI.framework/Versions/A/QuickLookUI

结果: 在 macOS 11.6 环境下不存在QuickLookUI，说明是动态链接器找不到系统框架，这和 Electron 38 对系统版本/SDK的要求应该有关，在 macOS 11.6 上可能缺失或版本不兼容。

步骤 2：验证官方支持

检索查阅 Electron 38 发布日志，确认一下是不是对系统版本有要求：
真是太幸运了，一搜就命中了关键信息！官方说明入口

Removed: macOS 11 support
macOS 11 (Big Sur) is no longer supported by Chromium.

Older versions of Electron will continue to run on Big Sur, but macOS 12 (Monterey) or later will be required to run Electron v38.0.0 and higher.

解读：自 v38 起最低支持版本提升至 macOS 12，Big Sur 被移除支持；与实际现象（在 11.6 上运行失败）完全吻合。

排查结论

• 直接原因：Electron 38 运行时需要的系统框架在 macOS 11.6 上不可用/不兼容，触发 dyld “image not found”。
• 根本原因：Electron 38 已不再支持 macOS 11（Big Sur）。
• 有效路径：升级系统至 macOS ≥ 12，或将 Electron 降级至 37.x。

解决方案

方案一：升级系统版本（推荐）

最直接有效的方案是升级到 macOS 12或更高版本。这样可以：

• 彻底解决框架依赖问题
• 获得更好的系统性能和安全性
• 避免未来遇到更多兼容性问题

方案二：降级 Electron 版本

如果确实无法升级系统，可以尝试降级到 Electron 的早期版本。

根据测试，Electron 37.x.x 及更早版本在 macOS 11.6 上运行良好：

pnpm install electron@37

实际项目中，我选择了降级 Electron 版本，因为团队成员使用黑苹果，升级系统不便。

注意事项：

• 降级可能导致无法使用 Electron 38 的新特性
• 需要测试应用的所有功能是否正常
• 长期来看不建议停留在旧版本

参考资料

• Electron 官方文档的 Breaking Changes