部署

目录布局

Program.exe 必须和 Python 运行时放在同一个目录里。下面以 Vector/ 代指该目录（实际路径随你的部署位置而定，本文其余部分同样用相对路径描述）：

text

Vector/
├── Program.exe            ← 本体；只链 python312.lib（导入库）
├── python312.dll          ← CPython 3.12.2 解释器（必须有）
├── python3.dll            ← 稳定 ABI 转发层
├── vcruntime140.dll       ⎫
├── vcruntime140_1.dll     ⎬ VC++ 2015-2022 运行时，随包提供
├── msvcp140.dll           ⎭
├── vanilla.mcp            ← MCP 模式下的脚本包
├── python312/             ← PYTHONHOME 指向这里
│   ├── Lib/
│   │   ├── os.py …          ← Python 标准库
│   │   └── site-packages/   ← 第三方包装这里
│   └── DLLs/              ← 官方扩展模块（_ssl.pyd、_socket.pyd、libssl-3.dll …）
├── scripts/               ← 插件（每个插件一个目录）
├── mc.cfg                 ← 启动配置（房间 / 账号 / 皮肤）
├── client_cfg.json        ← 客户端配置（no_launch_mcp 等）
├── skin_data.json / skin.png / skins/
└── songs/ / model.json / whitelist.txt

不能缺的三类文件

python312.dll、python3.dll —— 解释器本体，缺了直接启动失败
python312/ 整个目录 —— 标准库与扩展模块，缺了所有 import 都会失败
vcruntime140.dll / vcruntime140_1.dll / msvcp140.dll —— 缺了会报「找不到 MSVCP140.dll」。这三个 DLL 已经放在发布包里，别单独把它们删掉

为什么标准库在 python312/Lib

PythonRuntime.cpp 的 SetPythonHome() 把 PYTHONHOME 指向 <exe 所在目录>\python312， CPython 的 getpath 就在这个 prefix 下找 Lib\os.py。所以整个目录搬到任何位置都能直接跑，不依赖系统里装没装 Python。

请勿删改 python312/，那是运行环境（标准库 + 官方扩展）；插件放插件目录。

升级到新版本

本体是单文件的，可以直接替换：

关掉正在运行的客户端
用新的 Program.exe 覆盖旧的
如果新版本还改了运行库，一并把 python312.dll / python312/ / VC 运行时 DLL 覆盖过去

自带的在线更新

如果用的是 VQ 启动器，它会检查官网版本号（Update/program/banb.txt）并在启动时自动下载替换 Program.exe，不需要手工操作。注意版本号必须比客户端记录的高才会触发更新 （记录在 config.json 的 ProgramVersion）。

装第三方库

python312.dll 是标准 CPython，所以官方平台 wheel 可以直接用：

bash

# 用系统里同版本 Python 3.12 的 pip 装进运行目录
pip install numpy --target "Vector\python312\Lib\site-packages"
pip install Pillow requests --target "Vector\python312\Lib\site-packages"

纯 Python 包（wheel 名形如 py3-none-any）同样照此安装，或者直接把目录复制进 python312\Lib\site-packages\。插件里直接 import 即可。

版本要对齐

wheel 文件名里的 cp312 必须是 3.12，和嵌入的解释器一致；装 3.11 / 3.13 的 wheel 会 import 失败。

运行库依赖

Program.exe 按 /MD 动态链接 C 运行时（见 cmake/Platform.cmake 的 CMAKE_MSVC_RUNTIME_LIBRARY = MultiThreadedDLL），因此需要：

DLL	作用	发布包是否自带
`vcruntime140.dll`	C 运行时	✅
`vcruntime140_1.dll`	异常处理 / 栈展开	✅
`msvcp140.dll`	C++ 标准库	✅

三个都在发布包里，用户不需要安装任何东西。

如果遇到「找不到 MSVCP140.dll」「找不到 VCRUNTIME140_1.dll」：

从完整发布包里把这三个 DLL 拷到 exe 旁边（最常见的原因就是只拿了 exe 没拿 DLL）
或者让用户安装 Microsoft Visual C++ 2015-2022 Redistributable (x64)

其余系统 DLL（KERNEL32、WS2_32、CRYPT32、bcrypt、IPHLPAPI、 api-ms-win-crt-*）Windows 自带；Windows 7 / 8.1 需要先装 KB2999226（UCRT）。

启动参数

bash

Program.exe --config mc.cfg --logger
Program.exe --start_nethernet --UserID xxx --DisplayName xxx --MD5Token xxx

常用参数：

参数	说明
`--config <file>`	启动配置，默认 `mc.cfg`
`--logger`	程序自身日志也输出到终端日志区
`--no-ui`	关闭终端界面，使用普通输出
`--mouse-scroll`	捕获鼠标以支持滚轮翻日志（会牺牲原生拖拽选中，`F7` 可切换）
`--PluginDir <dir>`	插件目录，默认 `./scripts`
`--protocol <n>`	协议版本，默认 860
`--pause`	退出前暂停

完整参数表见项目概览 · 命令行参数；界面相关见终端界面。

上线检查项

已实测通过

PlayStatus value: 3 = PlayerSpawn（正常进服）；0 = 登录成功；1/2/4/5/6 才是失败
没有被「因违规游戏行为，您的账号被禁止进入游戏」踢出 —— 这一条是判据：只有 MCP 反作弊校验链（rotor + umsgpack + RC4）完好才不会被踢

换机器、或改动 PythonRuntime.cpp 的初始化顺序后，需要重新走一遍这两条。

一个容易踩的坑

两种模式的 sys.path 处理不一样：

模式	行为
MCP 模式	先整个清空 `sys.path`，再追加 `vanilla.mcp` 及其 `minecraft/ framework/ lib/ lobby/ mod/ sunshine/` 子目录与插件目录
source 模式（默认）	不清空（清空会连标准库路径一起清掉，所有 stdlib import 都会失败），只追加 `./source`、插件目录、`./python312/Lib/site-packages`

所以往 sys.path 里加东西时，要注意自己处于哪个模式。

日志

文件	内容
`log.txt`	完整日志
`dis.log`	断开 / 封禁相关

排查 Python 问题时，日志里 [PythonRuntime] 前缀的行会显示初始化各阶段（SetPythonHome → Py_Initialize → initModules → import init）。带 --logger 时这些行也会进终端日志区。

部署 ​

目录布局 ​

升级到新版本 ​

装第三方库 ​

运行库依赖 ​

启动参数 ​

上线检查项 ​

一个容易踩的坑 ​

日志 ​

下一步 ​

部署