2. 开发环境搭建：选系统、装工具、编译国密库

讲国密接口之前，先把战场铺好。环境搭不对，后面全是坑。我见过不少新手在 Windows 上折腾 GmSSL 编译，最后哭着换回了 Ubuntu。所以这一章，咱们一次性搞定。

2.1 操作系统选择：稳定的就是最好的

我个人习惯用 Ubuntu 20.04 LTS 或 22.04 LTS。为什么？其实很简单：社区活跃、依赖好装、GmSSL 和 OpenSSL-GM 的官方文档主要针对 Linux 写的。

Windows 行不行？行，但你要有心理准备。我曾在 Windows 上用 MSYS2 编译 GmSSL，光是解决 pthread 兼容问题就花了一下午。你说值不值？如果你只是快速验证接口，用 WSL2 也行。

macOS 用户可以用 Homebrew 装依赖，但要注意 Apple Silicon 芯片的坑——有些国密库的汇编优化没适配 ARM64，编译会报错。我踩过一次，最后老老实实切到 x86_64 的 Docker 容器里编译的。

我的推荐：Ubuntu 22.04 LTS。稳定、包新、教程最多。如果你用服务器，CentOS 7/ Rocky Linux 9 也 OK，但编译时记得装 EPEL 源。

2.2 开发工具：VS Code 还是 PyCharm？

其实两个都行。区别在于你的主力语言。

  • VS Code：轻量、插件多、支持 C/C++/Python/Go 混编。我写 GmSSL 的 C 封装和测试用例都用 VS Code，Remote-SSH 连到服务器上改代码，很方便。
  • PyCharm：如果你主要用 Python 调国密 API，PyCharm 的调试器和虚拟环境管理更顺手。我团队里有同事用 PyCharm 写国密接口的单元测试，覆盖率一目了然。

嗯，这里要注意：不管用哪个，必须装上 C/C++ 扩展或插件，因为你要编译 GmSSL。

工具 适用语言 推荐场景 我的建议
VS Code C / C++ / Python / Go 编译、调试国密库底层 插件少而精，Remote 开发首选
PyCharm Python 为主 快速调 API、写测试脚本 专业版支持数据库和科学计算
其实没必要纠结。两个都装上，VS Code 写底层，PyCharm 写应用层。又不费什么硬盘。

2.3 国密库选型：GmSSL 与 OpenSSL-GM

目前主流的国密库就两个：GmSSL（北京大学开源）和 OpenSSL-GM（基于 OpenSSL 的国密补丁版）。

  • GmSSL：纯国密实现，不依赖 OpenSSL，API 风格简洁。我项目里用 GmSSL 做 SM2/SM3/SM4 的签名验签和加解密，稳定运行两年了。
  • OpenSSL-GM：在 OpenSSL 基础上加国密算法，支持国密 TLS 握手。如果你已有 OpenSSL 代码，改造成本低。

怎么选？你想想看：如果是新项目，我建议直接上 GmSSL，避免 OpenSSL 许可证和版本冲突的麻烦。如果是老项目改造，用 OpenSSL-GM 无缝替换原有的 RSA/AES 调用。

避坑指南：我曾经因为依赖了某个第三方库的旧版 OpenSSL，跟 OpenSSL-GM 的符号冲突，导致链接时崩溃。解决方案是静态链接 OpenSSL-GM 并隐藏符号，或者用 GmSSL 彻底隔离。

2.4 编译与安装 GmSSL（以 Ubuntu 22.04 为例）

下面是我测试过的最新版本 GmSSL v3.2.2 的编译步骤。其他 Linux 发行版同理。

  1. 安装依赖
sudo apt update
sudo apt install -y build-essential cmake git libssl-dev

注意：libssl-dev 不是必须的，但装了可以避免一些编译时的检测警告。

  1. 克隆源码
git clone https://github.com/guanzhi/GmSSL.git
cd GmSSL
  1. 创建构建目录并配置
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local

这里我把安装路径设成 /usr/local，方便系统找到动态库。你也可以改成自己的目录。

  1. 编译
make -j$(nproc)

-j$(nproc) 用全部 CPU 核心并行编译，大概两三分钟就好。

  1. 安装
sudo make install

装完后验证一下：

gmssl version
# 输出类似：GmSSL 3.2.2 - OpenSSL 1.1.1t  7 Feb 2023
我习惯的做法：编译时加上 -DBUILD_SHARED_LIBS=ON，这样生成动态库，后续 Python 调用直接 cdll.LoadLibrary 就能加载。

2.5 编译与安装 OpenSSL-GM

OpenSSL-GM 没有独立官网，一般用 GmSSL-OpenSSL 这个分支。这里以 OpenSSL 1.1.1 打国密补丁为例。

  1. 下载 OpenSSL 1.1.1 源码
wget https://www.openssl.org/source/openssl-1.1.1t.tar.gz
tar -xzf openssl-1.1.1t.tar.gz
cd openssl-1.1.1t
  1. 打国密补丁

补丁文件网上可找到，比如 openssl-1.1.1-gm.patch。打补丁命令：

patch -p1 < ../openssl-1.1.1-gm.patch
  1. 配置编译选项
./config --prefix=/usr/local/gmssl --openssldir=/etc/gmssl shared

注意 --prefix 要设成独立目录，别和系统 OpenSSL 冲突。

  1. 编译安装
make -j$(nproc)
sudo make install
  1. 设置环境变量
export PATH=/usr/local/gmssl/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/gmssl/lib:$LD_LIBRARY_PATH

测试国密功能：

openssl version -a | grep SM
# 如果输出包含 SM2/SM3/SM4 字样，说明打补丁成功。
我曾经遇到：系统 OpenSSL 版本和 OpenSSL-GM 冲突，导致 curl、wget 等工具无法正常使用。解决办法是在编译 Git 等工具时用 --with-openssl=系统路径，或者用 Docker 容器隔离。

2.6 一张图看懂环境搭建全流程

下面这张 SVG 把操作系统的选择、开发工具的取舍、国密库的选型与编译串起来了。

开发环境搭建知识体系 操作系统选择 Ubuntu 22.04 / WSL2 / macOS 开发工具 VS Code / PyCharm 国密库 GmSSL / OpenSSL-GM GmSSL 编译安装流程 ① sudo apt install build-essential cmake git ② git clone + mkdir build && cd build ③ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local ④ make -j$(nproc) && sudo make install ⑤ gmssl version 验证成功 OpenSSL-GM 编译安装流程 ① 下载 OpenSSL 1.1.1 源码 ② 打国密补丁 patch -p1 ③ ./config --prefix=独立目录 shared ④ make -j$(nproc) && sudo make install ⑤ 设置 PATH / LD_LIBRARY_PATH 环境变量 验证与集成：写测试代码 / 调 API

2.7 验证环境的小例子

装好了库，写个简单的 C 程序测试 SM3 哈希，确保动态库能正常加载。

// test_sm3.c
#include <stdio.h>
#include <string.h>
#include <gmssl/sm3.h>

int main() {
    unsigned char dgst[32];
    sm3((unsigned char*)"hello gmssl", 11, dgst);
    for(int i = 0; i < 32; i++) printf("%02x", dgst[i]);
    printf("\n");
    return 0;
}

编译命令：

gcc -o test_sm3 test_sm3.c -lgmssl
./test_sm3

如果输出一个 64 位十六进制字符串，恭喜你，环境搭建成功。

我常用的验证办法：Python 里用 ctypes 加载 libgmssl.so，直接调 sm3 函数。这样可以跳过 C 编译，快速确认库是否工作。

好了，环境稳了，后面就可以放心写国密接口了。记住，折腾环境是正常的，我第一次编译 GmSSL 时也报错过几次“找不到头文件”之类的问题，基本都是路径没写对。仔细看 cmake 输出，哪个库没找到就去装哪个。

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