构建

从源码构建 Vector 客户端（Program.exe）的完整指南。当前形态：Python 3.12.2 动态嵌入（已从 Python 2.7 迁移，运行时随包提供 python312.dll）。

项目参数

项目	值
语言标准	C++17
构建系统	CMake（最低 3.20，兼容 CMake 4.x）
目标平台	Windows (MSVC) 为主；Linux x86_64 / Android ARM64 为历史支持
构建目标	`Program`（Windows 下为 `Program.exe`），约 9 MB
Python 运行时	3.12.2，动态链接：构建时链 `python312.lib`（导入库），运行时用同目录的 `python312.dll`
依赖策略	第三方依赖随仓库提供，无需包管理器、无需联网下载

环境要求

组件	要求
Visual Studio	VS 2026（MSVC v145 工具集）+ Windows SDK
CMake	≥ 3.20
Python 3.12	必须安装，且勾选 Development 组件（提供 `Python.h` 与 `python312.lib`）
Perl（可选）	只有想从源码编译 OpenSSL 时才需要，否则回退到仓库自带的预编译静态库

最容易卡住的一步

配置阶段执行 find_package(Python3 3.12 COMPONENTS Development REQUIRED)。 必须存在 3.12 的开发文件（头文件 + python312.lib）：

bash

# 安装包勾选 "Development" / 或独立安装 python-3.12-amd64.exe 时保留 Include/Lib
# 若 CMake 找不到，可显式指定：
cmake -B build -G "Visual Studio 18 2026" -A x64 -DPython3_ROOT_DIR=C:/Python312

版本必须正好是 3.12（cp312 ABI）；装 3.11 / 3.13 都会找不到。

获取源码

bash

git clone https://github.com/lurete-cn/NTvector.git
cd NTvector

仓库包含全部第三方 C/C++ 依赖源码（OpenSSL、jsoncpp、libdatachannel、libwebsockets、 SLikeNet、zlib），无需单独下载。

仓库较大

历史里含 libcrypto_static.lib（57 MB）与 libssl_static.lib（12 MB）。推送代码时如遇 RPC failed; curl 65 ... Connection was reset，先加大 HTTP 缓冲区：

bash

git config http.postBuffer 524288000

一键构建（推荐）

仓库自带 build_release.ps1：它会配置 + 编译 Release x64，并把产物和运行库整理进 dist\，得到一个可以直接运行的目录。

powershell

.\build_release.ps1                  # 构建 + 补齐 dist（已存在的运行库不重复拷贝）
.\build_release.ps1 -RefreshRuntime  # 额外用参考部署刷新全部运行库

产物：

text

dist\
├── Program.exe            ← 新编译的主程序
├── python312.dll          ⎫
├── python3.dll            ⎪
├── vcruntime140.dll       ⎬ 运行库（缺了用户就跑不起来）
├── vcruntime140_1.dll     ⎪
├── msvcp140.dll           ⎭
├── vanilla.mcp            ← MCP 脚本包
├── skin_data.json
└── python312\             ← 标准库 + DLLs + site-packages

为什么脚本要带上那三个 VC 运行时 DLL

Program.exe 按 /MD 链接（cmake/Platform.cmake 的 CMAKE_MSVC_RUNTIME_LIBRARY = MultiThreadedDLL），因此依赖 msvcp140.dll / vcruntime140.dll / vcruntime140_1.dll。把它们放在 exe 旁边（app-local）后，用户机器上不需要装 VC++ 可再发行组件。

脚本从 Visual Studio 的 VC\Redist\MSVC\*\x64\Microsoft.VC*.CRT\ 取这三个文件，保证版本与编译 exe 的工具集一致 —— 版本不匹配可能出现符号缺失。

手动 CMake 构建

bash

cmake -S . -B build -G "Visual Studio 18 2026" -A x64 -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel

生成器：Visual Studio 18 2026
架构：x64
产物：build/application/Release/Program.exe

构建完成后需要自己把 python312.dll / python312\ / VC 运行时 DLL 拷到 exe 旁边（或者直接跑 build_release.ps1）。

也可以在 Visual Studio 中直接打开仓库根目录，使用 CMake 列表（Configure → Build）。

构建坑（必读）

四个常见问题

必须带 /utf-8。源码是 UTF-8，MSVC 默认按系统 ANSI 代码页（中文系统是 GBK）解析，会把 UTF-8 的中文注释/字符串切成乱码，进而在几百个文件里报出莫名其妙的 C2059 / C2143 / missing ';'。工程已在 application/CMakeLists.txt 里加了 target_compile_options(Program PRIVATE /utf-8 …)，自建 target 或新增源文件目录时记得同样加上。
改 header 后 MSBuild 增量编译不会重编依赖它的 .cpp（如 engine_wrapper.h），需 touch 该 .cpp 强制重编，否则部署的是旧代码。
构建行为异常时优先删掉 build\ 重新 configure —— 不要复用损坏的 CMake 构建目录。
含中文注释的新增源码建议存成 UTF-8 带 BOM，比只靠 /utf-8 更保险（可避免 C4819）。

依赖是怎么来的

第三方库全部随仓库提供，由 cmake/FindPrebuiltDeps.cmake 统一管理（BUILD_SHARED_LIBS=OFF，一律静态链接）：

依赖	来源	产物形态
OpenSSL 3.5.1	`third_party/openssl` + `cmake/BuildOpenSSL.cmake`	静态 `.lib`
jsoncpp	`third_party/jsoncpp`	静态
libdatachannel / libjuice / usrsctp / srtp2	`third_party/libdatachannel`	静态
libwebsockets	`third_party/libwebsockets`	静态
SLikeNet	`application/include/SLikeNet-master`	静态
zlib	`application/include/zlib-1.3.1`	静态

因为都是静态链接，发布包不需要任何第三方 DLL。

OpenSSL 的两种来源

cmake/BuildOpenSSL.cmake 会在 configure 期尝试从源码构建 OpenSSL，产物缓存在 build/_deps/。这条路需要本机有 Perl；没有 Perl 时自动回退到仓库自带的预编译静态库（application/libcrypto_static.lib / libssl_static.lib）。

所以：

想完全从源码构建 → 装 Strawberry Perl
不想装 → 什么都不用做，用仓库自带的库即可

注意：仓库自带的预编译 OpenSSL 是 /MT（静态 CRT） 编译的，与 exe 的 /MD 不一致，链接时会给出 LNK4098 警告。功能上通常可行（OpenSSL 自己管理自己的内存），但想要一套干净的运行时，建议装 Perl 走源码构建。

CMake 选项

变量	默认	说明
`ENABLE_NTUNISDK`	`OFF`	启用 NtUniSdk 集成（Windows，可选）
`Python3_ROOT_DIR`	自动探测	Python 3.12 安装位置，找不到开发组件时手动指定

发布包要带什么

给用户的分发包就是 dist\ 的内容。必须包含：

文件	少了会怎样
`Program.exe`	——
`python312.dll`、`python3.dll`	启动直接失败（找不到 python312.dll）
`python312\` 整个目录	所有 `import` 失败（找不到标准库）
`vcruntime140.dll`、`vcruntime140_1.dll`、`msvcp140.dll`	报「找不到 MSVCP140.dll」
`vanilla.mcp`	MCP 模式无法加载脚本
`mc.cfg`、`client_cfg.json`、`skin_data.json` 等	配置缺失，按业务需要

详见部署。

其他平台

历史构建方式，目前未回归验证

当前实现是动态嵌入，非 Windows 平台直接用 find_package(Python3 3.12 COMPONENTS Development REQUIRED) 链接系统 Python，需要目标平台有对应的 Python 3.12 开发包。

Linux x86_64 原生编译（历史命令）

bash

cmake -B build -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
cmake --build build -j$(nproc)

Android / Termux 原生编译（历史命令）

bash

pkg install clang cmake make perl pkg-config
cmake -B build
cmake --build build -j$(nproc)

平台检测由 cmake/Platform.cmake 自动完成（检测到 Bionic libc 即进入 PLATFORM_ANDROID 分支），也可手动指定 -DPLATFORM_ANDROID=ON。

交叉编译（Windows → Linux，历史）

bash

cmake -B build-linux-x64 \
  -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/linux-clang-x86_64.cmake \
  -DCMAKE_SYSROOT=/path/to/x86_64-linux-gnu-sysroot
cmake --build build-linux-x64

工具链文件默认 -target x86_64-linux-gnu、链接器用 lld； CMAKE_SYSROOT 需包含目标平台的 GNU 工具链头文件与库。

构建 ​

项目参数 ​

环境要求 ​

获取源码 ​

一键构建（推荐） ​

手动 CMake 构建 ​

构建坑（必读） ​

依赖是怎么来的 ​

CMake 选项 ​

发布包要带什么 ​

其他平台 ​

Linux x86_64 原生编译（历史命令） ​

Android / Termux 原生编译（历史命令） ​

交叉编译（Windows → Linux，历史） ​

下一步 ​

构建

项目参数

环境要求

获取源码

一键构建（推荐）

手动 CMake 构建

构建坑（必读）

依赖是怎么来的

CMake 选项

发布包要带什么

其他平台

Linux x86_64 原生编译（历史命令）

Android / Termux 原生编译（历史命令）

交叉编译（Windows → Linux，历史）

下一步