Qt 解决 ld: framework ‘AGL‘ not found

现象

硬件环境

• 非最新 macOS Tahoe 26 系统
• XCode 已经更新到 26 版本

$ xcodebuild -version
Xcode 26.0.1
Build version 17A400

• Qt 5.15.2

执行 qmake 时出现以下链接错误

ld: framework 'AGL' not found
clang++: error: linker command failed with exit code 1 (use -v to see invocation)
ninja: build stopped: subcommand failed.

问题原因

在 XCode 26 版本中彻底弃用了 AGL。所以导致之前发布的Qt版本都无法链接到AGL

Apple 相关 release note：Here

[!NOTE]

macOS SDK 中不再提供 AGL。AGL 之前用于在 Carbon 应用中呈现 OpenGL 内容，而 Carbon 已不再存在于 SDK 中。AGL 符号现在在 64 位系统（包括 Intel x86_64 和 Apple Silicon Macs）上不起作用。可以安全地移除所有 AGL 的使用并停止链接 AGL。OpenGL 仍然保留在 SDK 中。(153913819)

这个问题目前已经被修复，参考如下：没有修改源码，仅仅修改了 cmake 和 qmake文件

[!IMPORTANT]
issue: QTBUG-137687

解决方案

• Qt5 版本的一个便捷方案：

  # Qt 5.15 apps with Xcode version 26 by adding this to a .pro file:
  QMAKE_LIBS_OPENGL = -framework OpenGL 
  

• Qt6 版本的解决方案

  # 手动修改 cmake, 删除AGL相关的脚本就可以 亲测可行
  /Users/{username}/Qt/{version}/macos/lib/cmake/Qt6/FindWrapOpenGL.cmake
  # qmake的参照mac.conf修改就行