一、原理说明

二、Windows (MinGW) 配置

2.1 前置要求

• Qt（含 MinGW 工具链，如 mingw1310_64）
• CMake 3.16+（https://cmake.org/download/）
• Git

确保 MinGW 在 PATH 中，在 cmd 执行：

set PATH=C:\Qt\Tools\mingw1310_64\bin;%PATH%

⚠️ 重要：后续所有编译步骤必须在无空格路径下进行。
如果你的用户目录包含空格（如 C:\Users\Marco Nie），请在 C:\ 根目录下建立工作目录。

mkdir C:\build_libs
cd C:\build_libs

2.2 编译 zlib

cd C:\build_libs

git clone https://github.com/madler/zlib.git --branch v1.3.1 --depth 1
cd zlib

cmake -B build -G "MinGW Makefiles" ^
  -DCMAKE_BUILD_TYPE=Release ^
  -DBUILD_SHARED_LIBS=OFF ^
  -DCMAKE_INSTALL_PREFIX=C:/build_libs/third_party/zlib

cmake --build build
cmake --install build

cd ..

安装结果：

C:\build_libs\third_party\zlib\
  include\   ← zlib.h, zconf.h
  lib\       ← libzlibstatic.a

2.3 编译 libpng

cd C:\build_libs

git clone https://github.com/pnggroup/libpng.git --branch v1.6.43 --depth 1
cd libpng

cmake -B build -G "MinGW Makefiles" ^
  -DCMAKE_BUILD_TYPE=Release ^
  -DPNG_SHARED=OFF ^
  -DPNG_STATIC=ON ^
  -DPNG_TESTS=OFF ^
  -DZLIB_ROOT=C:/build_libs/third_party/zlib ^
  -DCMAKE_INSTALL_PREFIX=C:/build_libs/third_party/libpng

cmake --build build
cmake --install build

cd ..

安装结果：

C:\build_libs\third_party\libpng\
  include\   ← png.h, pngconf.h, pnglibconf.h
  lib\       ← libpng16.a

2.4 编译 libimagequant

libimagequant 2.17+ 已用 Rust 重写，MinGW 下需使用最后一个纯 C 版本 2.12.6，
该版本没有 CMakeLists.txt，直接用 gcc 手动编译。

cd C:\build_libs

git clone https://github.com/ImageOptim/libimagequant.git ^
  --branch 2.12.6 --depth 1 libimagequant_c

cd libimagequant_c

:: 编译所有源文件
gcc -c -O3 -std=c99 -ffast-math ^
  libimagequant.c blur.c kmeans.c mediancut.c mempool.c nearest.c pam.c

:: 打包静态库
ar rcs libimagequant.a ^
  libimagequant.o blur.o kmeans.o mediancut.o mempool.o nearest.o pam.o

:: 手动安装
mkdir C:\build_libs\third_party\libimagequant\include
mkdir C:\build_libs\third_party\libimagequant\lib

copy libimagequant.h C:\build_libs\third_party\libimagequant\include\
copy libimagequant.a C:\build_libs\third_party\libimagequant\lib\

cd ..

安装结果：

C:\build_libs\third_party\libimagequant\
  include\   ← libimagequant.h
  lib\       ← libimagequant.a

2.5 复制到项目目录

将编译好的库复制到你指定的目录，例如 C:\Users\Marco Nie\Library\imageprocess：

xcopy /E /I C:\build_libs\third_party\zlib ^
  "C:\Users\Marco Nie\Library\imageprocess\zlib"

xcopy /E /I C:\build_libs\third_party\libpng ^
  "C:\Users\Marco Nie\Library\imageprocess\libpng"

xcopy /E /I C:\build_libs\third_party\libimagequant ^
  "C:\Users\Marco Nie\Library\imageprocess\libimagequant"

最终目录结构：

C:\Users\Marco Nie\Library\imageprocess\
  zlib\
    include\
    lib\
  libpng\
    include\
    lib\
  libimagequant\
    include\
    lib\

2.6 配置 .pro 文件（Windows 部分）

win32 {
    IMAGEPROCESS = "C:/Users/Marco Nie/Library/imageprocess"

    INCLUDEPATH += \
        $${IMAGEPROCESS}/libimagequant/include \
        $${IMAGEPROCESS}/libpng/include \
        $${IMAGEPROCESS}/zlib/include

    LIBS += \
        -L$${IMAGEPROCESS}/libimagequant/lib -limagequant \
        -L$${IMAGEPROCESS}/libpng/lib        -lpng16 \
        -L$${IMAGEPROCESS}/zlib/lib          -lzlibstatic
}

三、macOS (Apple Silicon) 配置

3.1 前置要求

• Homebrew（https://brew.sh）
• Qt for macOS

3.2 安装依赖

brew install libpng zlib libimagequant

安装路径（Apple Silicon 固定为 /opt/homebrew/opt/）：

Intel Mac 的 Homebrew 前缀为 /usr/local/opt/，将下方路径中的 /opt/homebrew 替换为 /usr/local 即可。

3.3 配置 .pro 文件（macOS 部分）

macx {
    INCLUDEPATH += \
        /opt/homebrew/opt/libimagequant/include \
        /opt/homebrew/opt/libpng/include \
        /opt/homebrew/opt/zlib/include

    LIBS += \
        -L/opt/homebrew/opt/libimagequant/lib -limagequant \
        -L/opt/homebrew/opt/libpng/lib        -lpng \
        -L/opt/homebrew/opt/zlib/lib          -lz
}

注意：macOS 下链接名与 Windows 不同：

• libpng 是 -lpng（不带版本号）
• zlib 是 -lz（不是 -lzlibstatic）

四、完整 .pro 配置

win32 {
    IMAGEPROCESS = "C:/Users/Marco Nie/Library/imageprocess"

    INCLUDEPATH += \
        $${IMAGEPROCESS}/libimagequant/include \
        $${IMAGEPROCESS}/libpng/include \
        $${IMAGEPROCESS}/zlib/include

    LIBS += \
        -L$${IMAGEPROCESS}/libimagequant/lib -limagequant \
        -L$${IMAGEPROCESS}/libpng/lib        -lpng16 \
        -L$${IMAGEPROCESS}/zlib/lib          -lzlibstatic
}

macx {
    INCLUDEPATH += \
        /opt/homebrew/opt/libimagequant/include \
        /opt/homebrew/opt/libpng/include \
        /opt/homebrew/opt/zlib/include

    LIBS += \
        -L/opt/homebrew/opt/libimagequant/lib -limagequant \
        -L/opt/homebrew/opt/libpng/lib        -lpng \
        -L/opt/homebrew/opt/zlib/lib          -lz
}

HEADERS += src/image_compress.h
SOURCES += src/image_compress.cpp

五、常见问题