项目源码编译指南（Windows）

Node.js + VS2022 + CMake 环境下，从解压源码到 npm run dev 的通用编译流程与常见问题。

一、环境准备

| 工具 | 要求 | |------|------| | Node.js | ≥ 18（建议 LTS 20） | | Visual Studio 2022 | 勾选「使用 C++ 的桌面开发」 | | CMake | ≥ 3.22，加入系统 PATH |

也可通过下载 vmos_window10_env.rar 虚拟机（已预装上述环境）。

源码包已含 prebuilt/，不需要安装 vcpkg，也不需要设置 VCPKG_ROOT。

二、解压与检查

# 解压到任意目录，例如 D:\work\
tar -xzf 01_TCPTool_20260601.tar.gz
cd D:\work\01_TCPTool

确认以下目录存在（缺任一则无法编译）：

prebuilt/x64-windows/              # SDTech SDK（含 bin/、lib/、include/）
prebuilt/x64-windows/bin/          # sdtech_*.dll、sqlite3.dll
prebuilt/x64-windows/lib/cmake/SDTech/SDTechConfig.cmake

三、编译步骤

cd Frontend

# 1. 安装前端依赖
npm install

# 2. 编译 Backend 并拷贝 DLL 到 dll/
npm run backend

# 3. 开发模式（自动编译 native 模块并启动）
npm run dev

npm run backend 成功后，Frontend/dll/ 应包含：

backend.dll
sdtech_json.dll、sdtech_logger.dll、sdtech_net.dll、sdtech_sqlite3.dll、sdtech_utils.dll
sqlite3.dll

四、常用命令

| 命令 | 说明 | |------|------| | npm run dev | 开发调试（含 Backend + 前端热更新） | | npm run build | 打生产安装包（electron-builder） | | npm run backend:debug | Debug 版 Backend | | npm run backend -- --clean | 清缓存后重编 Backend | | npm run pack-source | 维护方：打源码分发包 |

五、常见问题

1. 提示「未找到 vcpkg」或 toolchain 报错

说明使用了旧版源码包（未启用 standalone）。请向维护方索取最新 01_TCPTool_*.tar.gz，或确认包内存在 Frontend/packaging.config.json 且含 "standaloneNoVcpkg": true。

2. `prebuilt lib 目录不存在` 或缺少 sdtech_*.dll

包内 prebuilt/x64-windows/bin/ 不完整。请联系维护方重新打包（打包前需在本机成功执行 npm run backend）。

3. CMake / MSVC 报错

确认 VS 2022 已安装 C++ 工作负载
可在「x64 Native Tools Command Prompt」或普通 PowerShell 中执行
尝试：npm run backend -- --clean

4. node-gyp / native 模块失败

先执行 npm install，再 npm run dev（会自动编译 native 模块）。

六、架构说明

Frontend (koffi) → backend.dll（Backend/Dll 编译产物）
                      ↓
                  SDTech SDK（prebuilt 提供，sdtech_*.dll）

| 范围 | 说明 | |------|------| | 可修改 | Frontend/、Backend/Dll/（TCP/UDP/组播等业务逻辑） | | 预编译依赖 | prebuilt/x64-windows/（SDTech Logger/Json/Net/Utils/Sqlite3） |

七、快速流程

安装 Node + VS2022 + CMake
    → 解压源码包
    → cd Frontend && npm install
    → npm run backend
    → npm run dev