单单必成1. 问题背景与现象分析
最近在MacOS 26系统上编译Qt项目时，不少开发者遇到了一个棘手的报错：ld: framework 'AGL' not found。这个错误看似简单，却让很多Qt开发者头疼不已。作为一个长期在MacOS平台进行Qt开发的工程师，我也被这个问题困扰过，经过一番探索终于找到了解决方案。
AGL（Apple Graphics Library）是苹果早期提供的图形接口库，主要用于OpenGL相关功能的支持。随着MacOS系统的迭代更新，苹果逐渐弃用了一些老旧的技术框架，AGL就是其中之一。在MacOS 26中，这个框架被彻底移除，导致依赖它的Qt项目无法正常编译。
这个问题的典型表现是：
- 使用cmake构建的Qt项目会报
framework 'AGL' not found错误 - 使用qmake构建的项目同样会报类似错误
- 错误发生在链接阶段，提示找不到AGL框架
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 问题根源探究
要彻底解决这个问题，我们需要先理解它的根源。Qt作为一个跨平台框架，在不同系统上会使用不同的底层图形接口。在MacOS平台上，Qt历史版本中默认会链接AGL框架来处理OpenGL相关功能。
随着苹果对图形系统的更新：
- AGL已被标记为废弃API多年
- MacOS 26彻底移除了这个框架
- Qt的新版本已经逐步移除了对AGL的依赖
- 但部分旧项目或特定配置仍会尝试链接AGL
问题的核心在于Qt的构建系统配置文件中仍然包含了对AGL框架的引用，而MacOS 26已不再提供这个框架，导致链接失败。
3. CMake项目的解决方案
对于使用CMake构建的Qt项目，解决方法相对明确。我们需要修改Qt安装目录下的FindWrapOpenGL.cmake文件。
3.1 定位配置文件
这个文件的位置取决于你的Qt安装方式：
-
官方安装包：
/Users/{用户名}/Qt/{版本号}/macos/lib/cmake/Qt6/FindWrapOpenGL.cmake -
Homebrew安装：
/opt/homebrew/Cellar/qt/{版本号}/lib/cmake/Qt6/FindWrapOpenGL.cmake
3.2 修改配置文件内容
用文本编辑器打开这个文件