4. 环境搭建（二）：Windows系统下的编译（MSYS2、Visual Studio）与常见问题归纳总结

Windows 上编译 llama.cpp 的 GGUF 相关工具，其实就两条路：MSYS2 或者 Visual Studio。

可能有人觉得「在 Windows 上编译 C++ 项目很麻烦」，嗯，早期确实是这样。但现在的工具链已经很成熟了。我自己最开始也在这上面耗了不少时间，后来摸清了套路，其实也就那么几步。

4.1 路径一：MSYS2 编译

MSYS2 本质上是一个在 Windows 上提供 Linux 式环境的工具集。你装好它之后，就可以用 pacman 装各种库，然后用 make 编译。我个人习惯用这个方式，因为它最接近 Linux 下的体验，想移植或者测试一些脚本也方便。

安装 MSYS2

  1. 去官网下载 MSYS2 安装包，一路 Next 就行。
  2. 装好后打开 MSYS2 MSYS 终端（别开错了，有三个入口）。
  3. 先跑一遍 pacman -Syu 更新核心包。根据提示关闭终端再打开，再跑一次 pacman -Syu。
注意：更新后如果遇到error: GPGME error，通常是签名问题。执行 pacman -S archlinux-keyring 再重试就行。我之前有一次升级到一半断网，结果整个环境崩了……后来重装才解决。所以建议更新时保持网络稳定。

安装构建依赖

pacman -S --needed base-devel mingw-w64-x86_64-toolchain cmake git

这里 mingw-w64-x86_64-toolchain 会装好 gcc、g++ 和 Make。虽然 llama.cpp 推荐用 CMake，但 MSYS2 下用 make 也完全 OK，因为项目自带了 Makefile。

编译 llama.cpp

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
make -j$(nproc)

正常情况下，几分钟后就能在根目录看到 main.exe、quantize.exe 这些可执行文件。

小技巧：如果编译过程中报 undefined reference 之类的链接错误，大概率是少了某个依赖。比如缺 openblas，可以 pacman -S mingw-w64-x86_64-openblas 补上。别慌，看看报错行，缺啥补啥。

4.2 路径二：Visual Studio 编译

如果你已经装了 Visual Studio 2022（或者至少 Build Tools），那走这个路径更原生。VS 的编译器优化在 Windows 上通常比 MinGW 好一点，尤其是有 AVX2/AVX512 指令集的时候。

安装 VS Build Tools

在 Visual Studio 官网 下载 Build Tools for Visual Studio 2022。安装时勾选「使用 C++ 的桌面开发」和「Windows 10/11 SDK」就够了。

注意：安装完后需要打开 x64 Native Tools Command Prompt for VS 2022（开始菜单里找），不要用普通的 cmd 或 PowerShell，否则找不到 cl.exe 和 nmake。

CMake 生成与编译

推荐用 CMake 生成项目，然后用 msbuild 或 nmake 编译。我建议用 cmake --build 一条命令搞定：

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
mkdir build
cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release

等编译完成，可执行文件在 build\bin\Release 下。

踩坑记录：我曾经在 VS 编译时遇到 error LNK2019: unresolved external symbol，查了半天发现是 CMake 没有正确找到 CUDA 的路径。如果你需要 GPU 加速，记得在 CMake 命令行加上 -DGGML_CUDA=ON，并且确保已安装 CUDA Toolkit。

4.3 两条路径怎么选？

对比维度MSYS2Visual Studio
安装体积较小（~1GB）较大（~5GB 含 SDK）
编译速度中等较快（VS 的 cl.exe 优化好）
与 Linux 一致性高低（脚本需改路径）
GPU 加速支持较麻烦（需手动配 CUDA）原生支持 CUDA/DirectML
排错难度依赖包名可能记错各种 SDK 版本冲突

我个人建议：如果你只是偶尔跑一下 quantize 或者转换脚本，用 MSYS2 最快。如果你需要长期开发或调优高性能推理，选 VS。

4.4 常见问题归纳

  • Q: 编译后找不到 gguf 相关命令行？
    A: 你需要编译的是 quantize 和 convert 脚本（Python 版）。C++ 部分编译完只有 main.exe。GGUF 转换靠 convert.py，这个不需要编译。
  • Q: MSYS2 下 make 报错 Permission denied？
    A: 可能是杀毒软件锁了临时文件。关掉 Windows Defender 实时保护或者把项目目录加入排除项。
  • Q: VS 编译时 cl.exe 报 c1xx: fatal error C1034？
    A: 通常是头文件路径问题。确认你在「x64 Native Tools Command Prompt」下运行 CMake，并且 Windows SDK 版本正确。
  • Q: 两种方式编译出来的 quantize.exe 大小差很多？
    A: 正常。VS Release 版默认会 strip 符号表，MSYS2 的 minGW 默认不 strip。你可以手动 strip quantize.exe 缩小体积。
终极建议：不管选哪条路，第一次编译时先把网络断开（减少杀毒软件干扰），关掉其他 IDE，给编译环境一个干净的资源。我当年第一次在 Win 上编译 llama.cpp 时开着 Chrome 和微信，结果内存爆炸，编译到一半蓝屏……后来再也不敢了。
Windows 编译 llama.cpp 可选路径 开始：克隆 llama.cpp 你更习惯哪种环境？ MSYS2 安装 MSYS2 + pacman 依赖 make -j$(nproc) Visual Studio 安装 VS Build Tools cmake --build . --config Release 得到 quantize.exe 等工具 两种方式二选一，不用都装

上面这张图把两条路径梳理清楚了。说实话，你只要照着其中一条走到「得到 quantize.exe」，就算环境搭建成功了。后面 GGUF 转换的步骤，其实只需要 Python 环境和那个 convert.py 脚本，跟 C++ 编译没太大关系。不过提前把编译环境搭好，以后想试新功能也顺手。

← 上一章 📖 返回目录 下一章 →