Windows下使用CMake静态链接GTK4库找不到库问题解决

问题根因 #

报错核心来自两个配置错误：

• MSYS2默认安装的GTK4包仅提供动态链接所需的.dll.a导入库，不包含静态链接需要的.a静态归档文件
• CMake配置未正确触发pkg-config的静态链接查询模式，也没有传递静态库搜索路径，开启-static标志后链接器仅查找.a文件，自然无法定位到对应库

修复步骤 #

1. 安装GTK4静态库及对应依赖 #

打开MSYS2 Clang64终端，执行命令安装静态编译所需的包：

pacman -S mingw-w64-clang-x86_64-gtk4-static mingw-w64-clang-x86_64-graphene-static

安装完成后可以到D:/Programs/msys64/clang64/lib目录校验，存在libgtk-4.a、libgraphene-1.0.a文件即说明静态库安装到位。

MSYS2包规则说明：不带-static后缀的包仅提供动态链接文件，需要静态链接时必须安装同名带-static后缀的包。如果后续链接阶段提示其他依赖库缺失，按这个规则搜索安装对应静态包即可。

2. 修正CMakeLists.txt配置 #

原配置存在多处逻辑错误，替换为以下配置即可：

cmake_minimum_required (VERSION 3.14.0)

# 注意：编译器、生成器禁止在CMakeLists内硬编码，首次执行cmake时通过参数传入即可
# 调用参考：
# cmake -G Ninja -DCMAKE_C_COMPILER=D:/Programs/msys64/clang64/bin/clang.exe -DCMAKE_CXX_COMPILER=D:/Programs/msys64/clang64/bin/clang++.exe -DCMAKE_BUILD_TYPE=Release ..

project(LianLianKanSolver C)

# 静态链接基础配置
set(BUILD_SHARED_LIBS OFF)
set(CMAKE_FIND_LIBRARY_SUFFIXES ".a")
set(CMAKE_EXE_LINKER_FLAGS "-static -static-libgcc -s")
# -s参数用于裁剪Release版本的调试符号，大幅缩小最终exe体积

find_package(PkgConfig REQUIRED)
# 关键：添加STATIC参数，让pkg-config返回静态链接所需的完整依赖链、库路径
pkg_check_modules(GTK REQUIRED STATIC GTK4)

file(GLOB_RECURSE GAME_SOURCE_FILES RELATIVE ${CMAKE_SOURCE_DIR} "src/game/*.c")
file(GLOB_RECURSE GUI_SOURCE_FILES RELATIVE ${CMAKE_SOURCE_DIR} "src/ui/*.c")

add_executable(gui
    ${GAME_SOURCE_FILES}
    ${GUI_SOURCE_FILES}
)

target_include_directories(gui PRIVATE ${CMAKE_SOURCE_DIR}/src)
target_include_directories(gui PRIVATE ${GTK_INCLUDE_DIRS})
# 补全静态库搜索路径、编译参数传递
target_link_directories(gui PRIVATE ${GTK_LIBRARY_DIRS})
target_compile_options(gui PRIVATE ${GTK_CFLAGS_OTHER})
target_link_libraries(gui PRIVATE ${GTK_LIBRARIES})

关键修正点说明 #

• 原配置set(BUILD_SHARED_LIBS ON)逻辑错误，静态链接需设为OFF，之前日志里出现libgui.dll.a就是这个配置错误导致构建目标被识别为动态库。
• pkg_check_modules必须添加STATIC参数，否则pkg-config只会返回动态链接所需的最小库列表，不会带上静态链接必须的间接依赖，也不会正确返回静态库搜索路径。
• 原配置缺失target_link_directories，仅传递了库名没有传递库所在目录，开启-static后链接器不会自动检索动态库路径，必须手动传入静态库所在目录。
• 不要在CMakeLists中硬编码本地编译器路径、生成器类型，这类环境相关配置在cmake生成构建目录时通过命令参数传入，避免项目迁移到其他环境时直接配置失败。

额外注意 #

• 静态链接GTK4生成的可执行文件体积较大，Release模式加-s参数裁剪后一般在10MB左右，未裁剪的Debug版本可能超过100MB。
• 配置、构建过程必须在MSYS2 Clang64终端中执行，不要直接使用原生cmd/powershell，否则pkg-config无法定位GTK4的.pc描述文件，依然会报找不到库的错误。
• 如果后续链接时提示其他依赖缺失（比如intl、iconv等），直接在MSYS2中搜索对应带-static后缀的包安装即可。

内容的提问来源于stack exchange，提问作者elio_zhou