常见问题
构建
Q: 首次构建很慢？
A: 正常。两件事最耗时：
- OpenSSL 从源码编译（约 5–10 分钟）。若本机没有可用的 Perl，会回退到项目自带的
.lib，那就快得多。 - 编译 19 个原生模块（
engine、nbt、packets、game_state… 都是 pybind11 实现，全部编进Program.exe，第一次要完整编一遍）。
OpenSSL 的产物缓存在 build/_deps/，原生模块的对象文件留在 build/ 里， 之后的 configure / 增量构建会跳过已经编好的部分。
Q: configure 报找不到 Python3 的开发组件？
A: 配置阶段走的是 find_package(Python3 3.12 COMPONENTS Development REQUIRED) （见 application/CMakeLists.txt），所以本机必须存在一个装了 Development 组件 （Python.h 头文件 + python312.lib 导入库）的 Python 3.12：
- 装官方 Python 3.12 时把 Development / 头文件与库 勾上（默认勾选，不要取消）；
- 版本必须正好是 3.12（嵌入的解释器是 3.12.2）—— 只有 3.11 / 3.13 同样会失败； 用
py -0或py -3.12 -c "import sys; print(sys.prefix, sys.version)"确认； - 机器上有多个版本时，可以显式指定：
-DPython3_ROOT_DIR=<Python312 安装目录>。
另外，用 Visual Studio 生成器时 MSBuild.exe 必须在查找链里可见 （CMAKE_VS_MSBUILD_COMMAND → vswhere.exe → PATH）—— 从 「x64 Native Tools 命令提示符」里 configure 最省事。
Q: 编译时报一堆莫名其妙的语法错误（C2143 / C2059 / missing ';'）？
A: 先看编码。源码是 UTF-8，而 MSVC 默认按本地代码页（简中环境是 GBK）解析源文件， 中文注释和字符串会被拆成非法字节序列，编译器于是在后面某处报语法错 —— 报错行号 往往和真正出问题的那一行隔着几十行，看起来完全不知所云。
工程已经在 application/CMakeLists.txt 里给目标加上了 /utf-8，所以：
- 正常走工程构建不会踩到；自己新增 target、或单独
cl.exe编某个源文件时要记得带/utf-8； - 不要把源文件另存成 GBK / ANSI —— 全仓库统一 UTF-8（带不带 BOM 都可以）。
Q: 改完 header 重新构建，但运行还是旧行为？
A: MSBuild 增量编译不会重编依赖该 header 的 .cpp。用 touch <依赖的.cpp> 强制重编，或直接 rm -rf build 全量重建。
Q: 链接时报 LNK2005 重复符号 / LNK2001 无法解析的外部符号？
A: 少见，但先分清是哪一半出的错：
- 如果缺的是
Py_*这类 CPython API 符号，说明Python3::Python没链上 —— 检查application/CMakeLists.txt里的target_link_libraries(Program PRIVATE Python3::Python)，以及Py_ENABLE_SHARED（CMake 与application/application.cpp顶部）是否一致。 - 如果是第三方库（OpenSSL、zlib、jsoncpp …）的符号重复，多半是同一个库被引入了两遍 （既随依赖链入 exe、又被别的依赖再带进来一份）—— 只保留一处即可。
版本控制
Q: 推送代码到 GitHub 时报 RPC failed; curl 65 ... Connection was reset？
A: 仓库历史较大（含 57 MB 的 libcrypto_static.lib），需要增大 HTTP 缓冲区：
git config http.postBuffer 524288000Q: 提示 libcrypto_static.lib 超过 50 MB 推荐上限？
A: 仅警告，不影响。GitHub 单文件上限 100 MB。如需精简仓库，可改用 Git LFS 或重写历史。
其他平台
Q: Linux / Android 上 Python.h 找不到？
A: 非 Windows 构建目前尚未回归验证。Windows 侧已经是动态嵌入： application/CMakeLists.txt 用 find_package(Python3 3.12 COMPONENTS Development REQUIRED) 链接 Python3::Python，运行期由 python312.dll + python312/ 目录提供解释器与标准库； 其它平台还缺对应的运行目录打包与验证流程。 历史命令见构建 · 其他平台。
历史 Py2 构建时该问题常由损坏的 build/_deps/ 导致，删除后重新 configure 即可。
运行
Q: 启动时报「找不到 MSVCP140.dll」或找不到 VCRUNTIME140_1.dll？
A: Program.exe 按 /MD 链接（cmake/Platform.cmake 里的 CMAKE_MSVC_RUNTIME_LIBRARY = MultiThreadedDLL），因此需要 VC++ 2015-2022 x64 运行时：
| 缺失的 DLL | 作用 |
|---|---|
vcruntime140.dll | C 运行时 |
vcruntime140_1.dll | 异常处理 / 栈展开（2019+ 编译器的产物） |
msvcp140.dll | C++ 标准库 |
正式发布包已经把这三个 DLL app-local 放在 exe 旁边，用户端不需要额外安装。 报这个错基本就是运行目录里少文件：从完整发布包里补齐这三个 DLL 即可；或者安装 Microsoft Visual C++ 2015-2022 Redistributable (x64)。
Q: PlayStatus value: 3 是错误吗？
A: 不是。3 = PlayerSpawn，即正常进服。0 = 登录成功；1/2/4/5/6 才是失败。
Q: 被服务器以「因违规游戏行为，您的账号被禁止进入游戏」踢出？
A: 这是反作弊校验失败，通常是 MCP 校验链（rotor + umsgpack + RC4）出了问题。 排查见 RPC 与反作弊校验。
Q: 控制台输出中文乱码，或者插件 print() 的日志半天不刷新？
A: 网络数据是 UTF-8，Python 3 的 str 是 Unicode，插件内部直接使用即可， 不影响实际收发。Windows 控制台默认 GBK，print 才可能显示乱码。
运行时初始化时已经处理过这两件事：设置了 PYTHONUNBUFFERED 与 PYTHONIOENCODING=utf-8，并把 sys.stdout / sys.stderr 重新配置成 UTF-8 行缓冲 —— 所以插件 print() 的内容不会攒在缓冲区里迟迟不输出， 终端界面的日志区也会及时显示。
如果你自己替换过 stdout / stderr，或者碰到的是系统控制台的显示问题， 可以再显式指定一次：
import sys
sys.stdout.reconfigure(encoding='utf-8') # 或 'gbk'