# CMake 错误：找不到 GLFW3（缺少：GLFW3_DIR）

- **ID:** `cmake/glfw3-not-found-missing-config`
- **领域:** cmake
- **类别:** config_error
- **验证级别:** ai_generated
- **修复率:** 85%

## 根因

CMake 的 find_package(GLFW3) 无法找到 GLFW3Config.cmake 或 glfw3-config.cmake 文件，通常是因为 GLFW3 未安装或安装前缀不在 CMake 搜索路径中。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| GLFW 3.3 | active | — | — |
| GLFW 3.4 | active | — | — |
| CMake 3.16 | active | — | — |
| CMake 3.20 | active | — | — |

## 解决方案

1. ```
   安装开发包：在 Ubuntu/Debian 上：sudo apt-get install libglfw3-dev。在 Fedora 上：sudo dnf install glfw-devel。在 macOS 上：brew install glfw。
   ```
2. ```
   如果从源码构建 GLFW3，运行 cmake 时加上 -DGLFW_BUILD_DOCS=OFF -DGLFW_INSTALL=ON，然后 sudo make install。然后将 GLFW3_DIR 设置为安装前缀（例如 /usr/local/lib/cmake/glfw3）。
   ```
3. ```
   在命令行手动提供 GLFW3_DIR：cmake .. -DGLFW3_DIR=/path/to/glfw3/lib/cmake/glfw3
   ```

## 无效尝试

- **** — Some system packages (e.g., libglfw3 on Ubuntu) install only the shared library and headers, not the CMake config file. The config file is in a separate -dev package. (70% 失败率)
- **** — GLFW3_DIR must point to the directory containing GLFW3Config.cmake, typically the build or install directory, not the source root. (85% 失败率)
- **** — Without REQUIRED, CMake continues but variables like GLFW3_FOUND are FALSE, leading to undefined symbols at link time. (60% 失败率)