简介：libmemcached-win32 是一份面向 Windows 平台 C/C++ 开发者的 memcache 客户端源码包，专为需要在 VC2008 环境下编译 libmemcached 的读者准备。作者在寻找可用于 ASP 的 memcache 客户端时，发现纯 win32 方案性能一般，最终整理出这份可顺利编译的 libmemcached 源码，适合具备一定 C 语言基础、需要自行编译并集成缓存客户端的开发者参考。压缩包为 7z 格式，共 74 个文件，约 47KB，其中 37 个 .c 源文件与 28 个 .h 头文件构成核心实现，另含 vcproj 工程文件、def 导出定义、w32 平台 Makefile 及 ver 版本文件等，覆盖哈希、连接、存储、协议解析等模块。目前已有 233 人学习下载。读者可据此在 VC2008 中直接打开工程编译，获得一套结构完整的 libmemcached 源码，便于研究其接口组织与跨平台适配思路，并在此基础上开展后续功能测试与二次开发。
1. 为什么今天还有人折腾 libmemcached-win32
如果你在 Windows 上写 C/C++ 服务，想接 Memcached 做一层缓存，大概率会先搜到libmemcached，然后发现官方那套构建体系基本是给 Linux 准备的：autotools、pkg-config、一堆 POSIX 头文件，在 MSVC 下直接编译会炸出一屏错误。libmemcached-win32这个方向要解决的就是这件事——把 libmemcached 这套客户端库在 Windows 上跑通，让 MSVC 或 MinGW 能链接、能调、能稳定收发。
它适合三类人：一是维护老 C++ 服务、缓存层已经用 Memcached 的团队；二是做 Windows 桌面或服务端工具，需要轻量 key-value 缓存的开发者；三是想给跨平台项目统一缓存客户端、不想在 Windows 分支里另写一套 socket 逻辑的人。核心难点不在 API，而在构建系统、依赖库和网络层的 Windows 适配。下面按「先立住原理、再动手复现、最后讲坑」的顺序拆开讲。
2. libmemcached 在 Windows 上的构建路径怎么选
2.1 先搞清楚 libmemcached 的依赖结构
libmemcached 不是一个纯头文件库，它内部依赖几块东西：网络层（socket、非阻塞 IO）、哈希与一致性哈希、压缩（可选 zlib）、以及 SASL 认证（可选）。在 Linux 上这些靠系统库和 autotools 探测，在 Windows 上就得手动补齐。
常见做法是分两条路：一条是用 MSYS2/MinGW-w64 走类 Unix 构建链，另一条是用 CMake 或手写 vcxproj 走 MSVC 原生链。前者省事但产物依赖 MinGW 运行时；后者干净但配置量大。我一般会先判断项目最终交付形态——如果只是内部工具，MinGW 够用；如果要发给别人用或集成进 MSVC 工程，就老老实实走 MSVC。
需要提前准备的依赖：
| 依赖 | 作用 | Windows 获取方式 |
|---|---|---|
| Winsock2 | TCP 通信 | 系统自带，链接 ws2_32 |
| zlib | 值压缩 | 自行编译或 vcpkg |
| SASL | 认证 | 可选，不用可关 |
| pthread | 线程同步 | MinGW 自带，MSVC 需替代 |
2.2 用 MSYS2 跑通最小构建
先装 MSYS2，然后在 MinGW64 shell 里补齐工具链。下面这套命令是我在干净环境里验证过的顺序：
# 更新包数据库并安装编译工具 pacman -Syu pacman -S --needed base-devel mingw-w64-x86_64-toolchain pacman -S --needed mingw-w64-x86_64-cmake mingw-w64-x86_64-zlib # 进入源码目录，生成构建文件 cd /d/libmemcached-src mkdir build && cd build cmake .. -G "MSYS Makefiles" \ -DCMAKE_INSTALL_PREFIX=/mingw64 \ -DENABLE_SASL=OFF \ -DENABLE_ZLIB=ON \ -DBUILD_SHARED_LIBS=ON # 编译并安装 make -j8 make install逻辑说明：-G "MSYS Makefiles"让 CMake 用 MSYS 的 make 而不是 Visual Studio 生成器；-DENABLE_SASL=OFF关掉 SASL，因为它在 Windows 上最容易缺头文件；-DBUILD_SHARED_LIBS=ON生成 dll，方便后续替换。参数上，CMAKE_INSTALL_PREFIX指向 MinGW 的安装前缀，这样头文件和库会自动进到编译器默认搜索路径。
编译完成后，用一个小程序验证链接是否正常：
// test_memcached.c #include <libmemcached/memcached.h> #include <stdio.h> int main(void) { memcached_st *memc = memcached_create(NULL); memcached_return_t rc; // 指向本机 Memcached 默认端口 memcached_server_st *servers = memcached_server_list_append(NULL, "127.0.0.1", 11211, &rc); memcached_server_push(memc, servers); memcached_server_list_free(servers); const char *key = "win32_test"; const char *val = "hello"; rc = memcached_set(memc, key, strlen(key), val, strlen(val), 0, 0); if (rc != MEMCACHED_SUCCESS) { printf("set failed: %s\n", memcached_strerror(memc, rc)); return 1; } printf("set ok\n"); memcached_free(memc); return 0; }编译命令：
gcc test_memcached.c -o test_memcached.exe -lmemcached -lws2_32这里-lws2_32必须加，否则会报WSAStartup未定义。运行前确保本机 Memcached 已启动，默认监听 11211。
2.3 MSVC 路线要改哪些地方
如果必须用 MSVC，MinGW 那套直接搬会失败。核心改动点有三个：一是把unistd.h、sys/socket.h这类头文件替换成winsock2.h和windows.h；二是把close换成closesocket，read/write换成recv/send；三是处理ssize_t未定义的问题，通常用typedef SSIZE_T ssize_t;兜住。
常见做法是用 CMake 的if(WIN32)分支做条件编译，而不是去改源码里的每个文件。下面是一个最小 CMake 片段：
if(WIN32) target_compile_definitions(memcached PRIVATE WIN32_LEAN_AND_MEAN) target_link_libraries(memcached PRIVATE ws2_32) # 关闭 MSVC 对不安全函数的告警 target_compile_options(memcached PRIVATE /wd4996) endif()参数说明：WIN32_LEAN_AND_MEAN减少 windows.h 引入的冗余头；/wd4996屏蔽strcpy一类告警，否则编译输出会被淹没。这一步不做，后面排错会很痛苦。
3. 把连接、超时和重试参数调到能用
3.1 连接池与超时设置
libmemcached 默认行为在 Windows 上有个坑：DNS 解析和连接超时用的是系统默认值，网络抖动时可能卡很久。必须显式设置超时和重试。
memcached_st *memc = memcached_create(NULL); memcached_behavior_set(memc, MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT, 2000); // 连接超时 2s memcached_behavior_set(memc, MEMCACHED_BEHAVIOR_RCV_TIMEOUT, 1000); // 接收超时 1s memcached_behavior_set(memc, MEMCACHED_BEHAVIOR_SND_TIMEOUT, 1000); // 发送超时 1s memcached_behavior_set(memc, MEMCACHED_BEHAVIOR_POLL_TIMEOUT, 1000); // poll 超时 memcached_behavior_set(memc, MEMCACHED_BEHAVIOR_RETRY_TIMEOUT, 500); // 重试间隔 memcached_behavior_set(memc, MEMCACHED_BEHAVIOR_SERVER_FAILURE_LIMIT, 3); // 失败 3 次踢出这些值单位是毫秒。SERVER_FAILURE_LIMIT很关键，它决定一个节点连续失败几次后被暂时摘除，避免每次请求都去撞一个已经挂掉的节点。生产环境里我一般把连接超时设 1~2 秒，接收超时设 500ms~1s，具体看你的 P99 延迟。
3.2 一致性哈希与节点权重
多节点场景下，默认哈希在节点增减时会导致大量 key 重新映射。libmemcached 支持一致性哈希：
memcached_behavior_set(memc, MEMCACHED_BEHAVIOR_DISTRIBUTION, MEMCACHED_DISTRIBUTION_CONSISTENT); memcached_behavior_set(memc, MEMCACHED_BEHAVIOR_HASH, MEMCACHED_HASH_MD5);MEMCACHED_DISTRIBUTION_CONSISTENT开启一致性哈希，MEMCACHED_HASH_MD5指定哈希算法。如果节点性能不均，可以用memcached_server_list_append_with_weight给节点加权重，权重高的节点分到更多 key。
3.3 二进制协议还是文本协议
libmemcached 默认走文本协议，但在 Windows 上如果值里包含二进制数据（比如序列化后的结构体），文本协议会因为\r\n截断出问题。这时要开二进制协议：
memcached_behavior_set(memc, MEMCACHED_BEHAVIOR_BINARY_PROTOCOL, 1);开了之后，memcached_set和memcached_get对二进制值更安全。注意：二进制协议下部分老版本服务端可能不支持，上线前先确认服务端版本。
4. 避坑：Windows 上最容易翻车的五个点
4.1 链接报错unresolved external symbol __imp__WSAStartup
现象：MSVC 链接阶段报 Winsock 相关符号找不到。原因：没有链接ws2_32.lib，或者链接顺序不对。解决：在项目属性里把ws2_32.lib加到附加依赖项，并确保它在 libmemcached 之后。MinGW 下就是编译命令末尾加-lws2_32。
4.2 程序启动就崩，提示WSAStartup未调用
现象：调用memcached_create后第一次网络操作直接异常。原因：Windows 下任何 socket 操作前必须调WSAStartup，而 libmemcached 在某些构建配置里不会自动帮你调。解决：在程序入口手动初始化：
WSADATA wsaData; if (WSAStartup(MAKEWORD(2, 2), &wsaData) != 0) { fprintf(stderr, "WSAStartup failed\n"); return 1; } // ... 使用 libmemcached ... WSACleanup();4.3 中文或二进制值取出来被截断
现象：memcached_set存进去的值，memcached_get取出来长度不对或内容缺失。原因：文本协议把\0当结束符，或者值里含\r\n。解决：改用二进制协议，或者存之前做一次 base64 编码。我一般直接开二进制协议，省事。
4.4 多线程下偶发崩溃
现象：单线程正常，多线程并发调用同一个memcached_st时随机崩溃。原因：memcached_st不是线程安全的，多个线程共用一个实例会踩内存。解决：每个线程创建自己的memcached_st，或者用线程局部存储。如果一定要共享，外面加锁，但性能会掉。
4.5 编译通过但运行时报MEMCACHED_PROTOCOL_ERROR
现象：连接成功，但 set/get 返回协议错误。原因：客户端和服务端协议不匹配，比如客户端开了二进制协议但服务端只支持文本。解决：先用telnet 127.0.0.1 11211发stats看服务端版本，再决定客户端协议配置。或者临时关掉二进制协议验证。
5. 进阶：把 libmemcached-win32 集成进真实工程
5.1 用 vcpkg 管理依赖，减少手工配置
手工编译 zlib 和 libmemcached 很费时间，而且换台机器就要重来。vcpkg 能把依赖和构建配置固化下来：
vcpkg install libmemcached:x64-windows装完后，在 CMake 里这样接：
find_package(libmemcached CONFIG REQUIRED) target_link_libraries(your_app PRIVATE libmemcached::libmemcached)这样头文件路径、库路径、Winsock 链接都由 vcpkg 的配置处理，跨机器复现成本低很多。注意 vcpkg 的 triplet 要和你的目标平台一致，x64-windows 和 x86-windows 不能混用。
5.2 封装一层薄适配层，隔离平台差异
直接在业务代码里调 libmemcached API，后面换客户端或加监控会很痛苦。我一般会封一层：
typedef struct { memcached_st *memc; int timeout_ms; } cache_client_t; int cache_init(cache_client_t *cli, const char *host, int port, int timeout_ms) { cli->memc = memcached_create(NULL); cli->timeout_ms = timeout_ms; memcached_behavior_set(cli->memc, MEMCACHED_BEHAVIOR_CONNECT_TIMEOUT, timeout_ms); memcached_behavior_set(cli->memc, MEMCACHED_BEHAVIOR_RCV_TIMEOUT, timeout_ms); memcached_behavior_set(cli->memc, MEMCACHED_BEHAVIOR_SND_TIMEOUT, timeout_ms); memcached_return_t rc; memcached_server_st *servers = memcached_server_list_append(NULL, host, port, &rc); if (rc != MEMCACHED_SUCCESS) { memcached_free(cli->memc); return -1; } memcached_server_push(cli->memc, servers); memcached_server_list_free(servers); return 0; }这层封装的好处是：超时、重试、协议开关都集中在一处，业务代码只关心 get/set。后面要加统计、加日志、换连接池，都改这一层。
5.3 验证清单：上线前必须跑的几项
| 检查项 | 方法 | 通过标准 |
|---|---|---|
| 连接建立 | 启动后立即 set/get | 返回 SUCCESS |
| 超时生效 | 停掉 Memcached 再请求 | 在设定超时内返回错误 |
| 二进制值 | 存 1KB 随机字节再取 | 长度和内容一致 |
| 多线程 | 4 线程并发 1000 次 | 无崩溃、无数据错乱 |
| 节点摘除 | 挂掉一个节点 | 请求自动切到存活节点 |
这套清单跑完，基本能覆盖 Windows 上最常见的翻车场景。我自己踩过最深的坑是第 4.2 条——WSAStartup没调，程序在开发机上跑得好好的，换台机器就崩，查了半天才定位到。后来养成习惯：只要在 Windows 上碰 socket，第一件事就是确认WSAStartup调了没有。希望帮到你。
本文还有配套的精品资源，点击获取
