安装开发与编译环境

本章从一台普通 Windows 10/11 开发机开始。正式服务器不需要安装完整开发工具；源码编译应在开发机完成，再由部署脚本发送构建产物。

需要的软件

软件	建议版本	用途	安装来源
Git for Windows	当前稳定版	下载源码、查看和提交修改	git-scm.com
Python	3.11 或 3.12 x64	部署、校验和 SSH	python.org
Node.js	22 LTS x64	Vue、Vite、VitePress	nodejs.org
Visual Studio Build Tools	2022	C/C++ 编译工具链	visualstudio.microsoft.com
Rust	仓库锁定工具链	GameAgent/API 编译	rustup.rs
Visual Studio Code	当前稳定版	编辑和调试源码	code.visualstudio.com

下载时只使用厂商官网。Node.js 请选择 LTS，不选择“Current”。Python 安装界面必须勾选 Add python.exe to PATH。Git 可保留默认选项。

安装 Node.js

1. 打开 Node.js 官网下载页。
2. 下载 Windows Installer 的 LTS x64 .msi。
3. 双击安装，保留 Node.js runtime、npm package manager 和 Add to PATH。
4. 安装完成后关闭所有 PowerShell 窗口，再重新打开。

# 显示 Node.js 版本；建议输出 v22.x.x。
node --version
# 显示 npm 版本；能输出版本号即正常。
npm.cmd --version
# 显示 Node.js 实际路径，排除旧版本抢占 PATH。
Get-Command node | Select-Object -ExpandProperty Source

正式服务器中的后台网关使用部署器携带的兼容 Node 运行时，不要手工把服务器全局 Node 升级成开发版。

安装 Git 和 Python

# 验证 Git 已加入 PATH。
git --version
# 验证 Python 主命令可用。
python --version
# 验证 pip 可用。
python -m pip --version
# 安装部署脚本使用的 Paramiko SSH 库。
python -m pip install --user paramiko
# 确认 Paramiko 可以导入。
python -c "import paramiko; print(paramiko.__version__)"

如果 python 打开 Microsoft Store，进入“设置 → 应用 → 应用执行别名”，关闭 Store 的 python.exe 别名，然后重新安装官网 Python。

安装 C/C++ 与 Rust

Visual Studio Build Tools 安装器中选择“使用 C++ 的桌面开发”，至少包含 MSVC、Windows SDK 和 CMake 工具。Rust 安装后重新打开 PowerShell。

# 验证 Rust 编译器。
rustc --version
# 验证 Cargo 包管理器。
cargo --version
# 显示当前 Rust 工具链。
rustup show active-toolchain

API 正式产物是 Win7 兼容 x86 程序，必须使用仓库提供的构建脚本，不能直接把本机 cargo build 的 x64 调试文件部署到服务器。

获取或更新项目

首次获取项目时由负责人提供仓库地址和访问权限。已有工作区不要重新克隆覆盖。

# 进入保存项目的父目录；首次克隆时使用。
Set-Location C:\
# 从正式 Git 仓库克隆项目；把尖括号内容替换为负责人提供的地址。
git clone <仓库地址> D2113server
# 进入项目根目录。
Set-Location C:\D2113server
# 查看当前分支和修改。
git status --short --branch
# 仅下载远端更新信息，不修改本地文件。
git fetch --all --prune

已有未提交修改时不要直接执行 git pull。先联系维护者确认是提交、暂存还是继续保留。

安装项目依赖

109 和 113 后台是独立项目，必须分别安装。npm ci 严格使用锁文件，适合部署和复现；不要在无需求时运行 npm update。

# 安装 109 后台锁定依赖。
npm.cmd --prefix .\d2109\admin-ui ci
# 安装 113 后台锁定依赖。
npm.cmd --prefix .\d2113\admin-ui ci
# 安装在线文档站锁定依赖。
npm.cmd --prefix .\docs-site ci
# 校验项目部署清单。
python .\scripts\d2ctl.py validate

VS Code 基本使用

# 从项目根目录打开 VS Code；左侧资源管理器会显示整个仓库。
code C:\D2113server

左侧“源代码管理”只用于查看差异，不要点击“放弃更改”。底部终端可通过“终端 → 新建终端”打开。文件保存后，Vue 开发服务器会自动刷新。

常见安装错误

现象	原因	处理
node 不是内部命令	PATH 未刷新	关闭并重开 PowerShell
npm.ps1 cannot be loaded	PowerShell 执行策略	使用文档中的 npm.cmd
python 找不到	安装时未加入 PATH	重新安装并勾选 PATH
paramiko 找不到	安装到了另一 Python	使用 python -m pip install --user paramiko
npm ci 报锁文件不匹配	package.json 与锁文件不同步	不要删除锁文件，交给开发人员修复
C++ 链接器缺失	未安装 Build Tools 工作负载	补装“使用 C++ 的桌面开发”