简介：这份资源面向在 Windows 11 环境下需要编译安装 pysqlcipher3 的 Python 开发者，尤其是涉及 SQLCipher 加密数据库、数据安全存储场景的中高级使用者。pysqlcipher3 是 SQLCipher 的 Python 绑定，常用于对本地数据库做透明加密，而其在 Windows 上的编译安装往往因缺少 C 编译环境、OpenSSL 依赖与 Python 版本差异而困难重重，本资源正是为解决这一痛点而整理。压缩包共 69 个文件，约 153KB，包含 25 个 py 脚本、20 个 h 头文件、18 个 c 源码文件，以及 rst 说明、in 模板、license、cfg 与 gitignore 等配置项，覆盖 Python2 与 Python3 两套源码目录及测试用例，结构完整。目前已有 607 人学习下载。借助其中的源码与构建配置，读者可对照排查编译报错、理解模块组织方式，并完成本地环境搭建与验证。
1. Windows 11 上编译 pysqlcipher3：为什么 pip 装不上，只能自己动手
在 Windows 11 上执行pip install pysqlcipher3，十有八九会看到一堆红色报错，最后停在error: Microsoft Visual C++ 14.0 or greater is required或者找不到sqlcipher头文件。这不是你的环境有问题，而是 pysqlcipher3 这个包本身就没有为 Windows 预编译 wheel，PyPI 上只有源码包，pip 拿到源码后需要本地编译，而编译又依赖 SQLCipher 的 C 库和 OpenSSL。Windows 11 默认不带这些，所以直接装必然翻车。
pysqlcipher3 是 Python 对 SQLCipher 的绑定。SQLCipher 是在 SQLite 基础上加了透明加密的版本，数据库文件整体用 AES 加密，应用层读写方式和普通 sqlite3 几乎一样。很多人选它，是因为项目要求本地数据落盘必须加密，又不想引入完整的数据库服务。Windows 11 上做桌面端、边缘设备数据采集、离线优先的 App，这个组合很常见。这篇笔记就把 Windows 11 下从零编译安装 pysqlcipher3 的完整路径拆开，包括依赖怎么装、源码怎么改、编译参数怎么设、装完怎么验证，以及我踩过的几个坑。
2. 编译前把依赖链理清：SQLCipher、OpenSSL 和 MSVC 三件套
2.1 为什么不能直接 pip install，非要本地编译
pysqlcipher3 的源码包在 PyPI 上只提供.tar.gz，没有.whl。pip 的默认行为是：如果有匹配当前平台和 Python 版本的 wheel，直接下载解压；如果没有，就下载源码包，调用本地的编译工具链执行setup.py build。Windows 上这个编译过程需要三样东西同时到位：C 编译器（MSVC）、SQLCipher 的开发库（头文件 + lib）、OpenSSL 的开发库。缺任何一个，编译都会中断。
SQLCipher 本身又依赖 OpenSSL 或 libcrypto 来做加密算法。Windows 11 没有系统自带的 OpenSSL 开发包，SQLCipher 官方也不提供 Windows 预编译的 dev 包。所以实际路径是：先拿到 OpenSSL 的 Windows 编译产物，再拿 SQLCipher 的源码在 Windows 上编译出sqlcipher.lib和头文件，最后编译 pysqlcipher3 时链接过去。三步缺一不可。
常见做法有两种：一种是用 vcpkg 一把梭，另一种是手动下载预编译的 OpenSSL 和 SQLCipher。vcpkg 省事但编译时间长，手动方式可控但容易版本对不上。我一般推荐手动方式，因为 pysqlcipher3 对 SQLCipher 的版本比较敏感，用 vcpkg 拉最新版有时会碰到 API 变动导致编译失败。
2.2 安装 Visual Studio Build Tools 并确认 MSVC 可用
Windows 11 上编译 C 扩展，最稳的是装 Visual Studio Build Tools 2022，而不是完整版 VS。下载地址在微软官网搜 “Build Tools for Visual Studio 2022”，安装时勾选 “使用 C++ 的桌面开发” 工作负载，右侧确保勾上 “MSVC v143 - VS 2022 C++ x64/x86 生成工具” 和 “Windows 11 SDK”。
装完后不要直接开 cmd 就编译，先确认环境变量。Build Tools 不会自动把cl.exe加到 PATH，需要用 “Developer Command Prompt for VS 2022” 或者手动调用vcvars64.bat。验证命令：
# 在 Developer Command Prompt 中执行 cl如果输出Microsoft (R) C/C++ Optimizing Compiler Version 19.xx就对了。如果提示 “不是内部或外部命令”，说明你用的是普通 cmd，需要先跑：
call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"这一步是后面所有编译操作的前提。很多人编译失败不是代码问题，而是 cmd 里根本没有 MSVC 环境，setup.py调不到编译器。
2.3 准备 OpenSSL 和 SQLCipher 的 Windows 开发库
OpenSSL 的 Windows 预编译包，我一般用 Shining Light Productions 的 Win64 OpenSSL v3.x 完整安装版，安装时选择 “Copy OpenSSL DLLs to the OpenSSL binaries directory”，这样头文件在C:\Program Files\OpenSSL-Win64\include，库文件在C:\Program Files\OpenSSL-Win64\lib\VC\x64\MD。
SQLCipher 需要从 GitHub 拉源码自己编。不要用 master 分支，用带版本号的 tag，比如v4.5.5。编译 SQLCipher 的步骤：
# 在 Developer Command Prompt 中，进入 SQLCipher 源码目录 mkdir build cd build cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release ^ -DOPENSSL_ROOT_DIR="C:\Program Files\OpenSSL-Win64" ^ -DOPENSSL_USE_STATIC_LIBS=FALSE ^ -DSQLCIPHER_CRYPTO_OPENSSL=ON .. ninja编译完成后，build目录下会有sqlcipher.lib（或者libsqlcipher.lib），头文件在源码的src和build生成的sqlite3.h里。把这两个路径记下来，下一步要用。
提示：CMake 和 Ninja 需要提前装好，可以用
winget install Kitware.CMake和winget install Ninja-build.Ninja。如果不想用 Ninja，把-G "Ninja"换成-G "Visual Studio 17 2022"也行，但生成目录结构会不同。
3. 编译 pysqlcipher3：从源码到可导入模块的完整命令
3.1 拉取源码并修改 setup.py 的库搜索路径
pysqlcipher3 的源码在 GitHub 上搜pysqlcipher3就能找到，用git clone拉到本地。进入目录后，先看setup.py。默认的setup.py在 Windows 上会去找sqlcipher这个库名，但实际编译出来的可能是libsqlcipher或者路径根本不在默认搜索范围。需要手动改三个地方：include_dirs、library_dirs、libraries。
# setup.py 中修改 Extension 部分 extension = Extension( "pysqlcipher3._sqlite3", sources=[...], include_dirs=[ "src", # pysqlcipher3 自带的 sqlite3 头文件 r"C:\sqlcipher\src", # SQLCipher 源码头文件路径 r"C:\sqlcipher\build", # 生成的 sqlite3.h 路径 r"C:\Program Files\OpenSSL-Win64\include", # OpenSSL 头文件 ], library_dirs=[ r"C:\sqlcipher\build", # sqlcipher.lib 所在目录 r"C:\Program Files\OpenSSL-Win64\lib\VC\x64\MD", # OpenSSL 库目录 ], libraries=["sqlcipher", "libcrypto"], # 链接 sqlcipher 和 OpenSSL crypto ... )这里的关键是libraries里写sqlcipher还是libsqlcipher，取决于你编译出来的 lib 文件名。Windows 下 MSVC 链接时，如果文件叫sqlcipher.lib，就写sqlcipher；如果叫libsqlcipher.lib，就写libsqlcipher。写错了会报LNK1181: 无法打开输入文件。
3.2 执行编译并处理常见的链接错误
改完setup.py后，在 Developer Command Prompt 里执行：
python setup.py build_ext --inplace如果一切顺利，会在当前目录生成pysqlcipher3/_sqlite3.cp311-win_amd64.pyd（Python 版本不同，文件名中的cp311会变）。但实际第一次跑大概率会报错。最常见的两个：
第一个是LNK2019: 无法解析的外部符号 sqlite3_key。这是因为 SQLCipher 的加密接口sqlite3_key和sqlite3_rekey在编译时可能被条件编译掉了。检查 SQLCipher 编译时有没有定义SQLITE_HAS_CODEC和SQLCIPHER_CRYPTO_OPENSSL。在 CMake 命令里加上-DSQLITE_HAS_CODEC=ON重新编译 SQLCipher。
第二个是LNK2038: 检测到“RuntimeLibrary”的不匹配项。这是 OpenSSL 库和 SQLCipher 库的运行时库选项不一致，一个是/MD，一个是/MT。统一用/MD，也就是在 CMake 里设-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL，OpenSSL 也用 MD 版本的 lib。
编译成功后，不要急着python setup.py install，先用--inplace生成的文件做导入测试。确认能导入再安装，避免装到 site-packages 里出问题不好排查。
3.3 安装到 site-packages 并验证加密功能
导入测试通过后，执行安装：
python setup.py install或者用 pip 从本地目录装：
pip install .装完后写一个最小验证脚本，确认数据库真的加密了：
from pysqlcipher3 import dbapi2 as sqlite # 创建加密数据库 conn = sqlite.connect("test_encrypted.db") cursor = conn.cursor() cursor.execute("PRAGMA key='my-secret-key'") cursor.execute("CREATE TABLE t (id INTEGER PRIMARY KEY, val TEXT)") cursor.execute("INSERT INTO t (val) VALUES ('hello')") conn.commit() conn.close() # 用错误密钥打开，应该失败 try: conn2 = sqlite.connect("test_encrypted.db") conn2.execute("PRAGMA key='wrong-key'") conn2.execute("SELECT * FROM t") print("加密未生效！") except Exception as e: print("加密生效，错误密钥无法读取:", e)如果错误密钥能读出数据，说明 SQLCipher 编译时没启用加密，回去检查SQLITE_HAS_CODEC宏。如果正确密钥也读不出来，检查PRAGMA key的引号格式，SQLCipher 对 key 的引号处理比较严格，单引号内不能有多余空格。
4. 避坑与排查：Windows 11 编译 pysqlcipher3 的 5 个血泪教训
4.1 坑一：Python 版本和 MSVC 版本不匹配
现象：编译时报ValueError: Unknown MS Compiler version 1930或者distutils.errors.DistutilsPlatformError。
原因：pysqlcipher3 的setup.py里用的distutils对 MSVC 版本识别表比较旧，VS 2022 的编译器版本号是 19.3x，旧版 distutils 不认识。Python 3.12 之后 distutils 被移除，问题更明显。
解决：升级setuptools到最新版，pip install --upgrade setuptools。如果还不行，在setup.py开头加from setuptools import setup, Extension替换原来的distutils.core。Python 3.12 环境建议直接用 Python 3.11 编译，装完再在 3.12 里用。
4.2 坑二：OpenSSL 版本 3.x 和 SQLCipher 的兼容问题
现象：SQLCipher 编译时报undefined reference to EVP_CIPHER_CTX_new或者链接 OpenSSL 时大量未解析符号。
原因：OpenSSL 3.x 改了部分 API，SQLCipher 4.5.x 之前的版本没有适配。或者你下载的 OpenSSL 是 3.x，但 SQLCipher 源码里条件编译走的是 1.1.x 的路径。
解决：要么把 SQLCipher 升到 4.5.5 以上，要么换 OpenSSL 1.1.1 的预编译包。我一般用 OpenSSL 1.1.1w 配 SQLCipher 4.5.5，这个组合在 Windows 上最稳。OpenSSL 1.1.1 的库文件名是libcrypto.lib，链接时写libcrypto。
4.3 坑三：编译出来的 pyd 导入时报 DLL 找不到
现象：import pysqlcipher3._sqlite3时报ImportError: DLL load failed while importing _sqlite3: 找不到指定的模块。
原因：_sqlite3.pyd依赖sqlcipher.dll和libcrypto-1_1-x64.dll，这两个 DLL 不在 Python 的搜索路径里。编译时链接的是静态库还是动态库，决定了运行时要不要 DLL。如果 SQLCipher 编译成了动态库，就必须把 DLL 放到_sqlite3.pyd同目录或者C:\Windows\System32。
解决：把sqlcipher.dll和libcrypto-1_1-x64.dll复制到pysqlcipher3包目录下，和_sqlite3.pyd放一起。或者用os.add_dll_directory()在导入前把 DLL 目录加进去。最省事的办法是编译 SQLCipher 时用静态库，CMake 里设-DBUILD_SHARED_LIBS=OFF，这样就不需要额外 DLL。
4.4 坑四：PRAGMA key 设置后仍然能明文读取
现象：用PRAGMA key设了密钥，但用其他 sqlite 工具打开数据库文件，能看到表结构。
原因：SQLCipher 的加密是页级别的，如果数据库在设置 key 之前已经创建了表，或者 key 设置语句没有在第一次操作前执行，SQLCipher 会以明文模式写入。另外，如果编译时SQLITE_HAS_CODEC没定义，PRAGMA key会被静默忽略。
解决：确保PRAGMA key是连接后的第一条语句，在任何CREATE TABLE之前执行。验证编译时是否真的启用了 codec，可以在 Python 里执行cursor.execute("PRAGMA cipher_version")，如果有返回版本号说明 SQLCipher 生效，返回空说明没启用。
4.5 坑五：Windows 11 路径空格导致 CMake 失败
现象：CMake 配置 SQLCipher 时报The source directory ... does not exist或者Could not find OpenSSL。
原因：Windows 11 的Program Files路径带空格，CMake 参数里如果没加引号，会被截断。另外，如果源码放在C:\Users\你的名字\Desktop\这种带中文或空格的路径下，也会出问题。
解决：所有 CMake 参数里的路径都用双引号包起来，比如-DOPENSSL_ROOT_DIR="C:\Program Files\OpenSSL-Win64"。源码目录尽量放在C:\work\这种无空格无中文的路径下。Developer Command Prompt 的工作目录也切到那里。
5. 进阶：用静态链接减少 DLL 依赖，以及一个验证加密强度的技巧
编译出可用的 pysqlcipher3 只是第一步，实际部署时 DLL 依赖是个麻烦事。如果目标机器上没有装 OpenSSL，或者 SQLCipher 的 DLL 版本对不上，程序启动就会失败。我后来固定用静态链接方案：SQLCipher 编译时-DBUILD_SHARED_LIBS=OFF，OpenSSL 也用静态库版本（libcrypto.lib而不是libcrypto-1_1-x64.dll对应的导入库），pysqlcipher3 的setup.py里libraries只写sqlcipher和libcrypto，不依赖运行时 DLL。
静态链接的代价是_sqlite3.pyd文件会变大，大概从几百 KB 涨到 3-5 MB，但换来的是拷贝到任何 Windows 11 机器上都能直接 import，不用配环境变量。对于桌面端分发，这个体积完全可以接受。
验证加密强度有个简单办法：用十六进制编辑器打开加密后的.db文件，搜索明文内容。如果能看到CREATE TABLE或者插入的字符串，说明加密没生效。SQLCipher 默认用 AES-256-CBC，加密后的文件头部是随机盐值，看不到SQLite format 3这个标准头。另外可以在 Python 里执行：
cursor.execute("PRAGMA cipher_settings") for row in cursor.fetchall(): print(row)这会输出当前 SQLCipher 的加密参数，包括cipher_plaintext_header_size、kdf_iter等。默认kdf_iter是 256000，如果这个值被改小了，加密强度会下降。我一般不动这些参数，用默认值就够了。
最后一个习惯：每次编译完，把setup.py的修改、CMake 命令、环境变量路径记在一个build_notes.md里。Windows 上编译 C 扩展的环境太容易变，过三个月再回来编，没有笔记根本想不起来当时怎么配的。这个习惯帮我省了很多后悔药。希望帮到你。
本文还有配套的精品资源，点击获取
