JiGuang 算法接入与打包命令说明

本文档说明 entry.cp311-win_amd64.pyd 与 Electron 项目的开发、打包、发布命令。

目录结构

JiGuang-program/
├── entry.cp311-win_amd64.pyd   # 算法核心（算法方提供，可替换）
├── license.lic                 # 授权文件
├── public_key.pem              # 公钥
├── runner.py                   # Python 桥接脚本
├── runner.dist/                # Nuitka 编译产物（含 api_runner.exe）
├── runner.build/               # 编译缓存（可删除，不影响运行）
├── build_runner.bat            # 首次/依赖变更时编译 api_runner.exe
├── sync_entry.bat              # 同步 entry.pyd 到 runner.dist（秒级）
└── requirements.txt            # Python 依赖清单

一、本地开发调试

在项目根目录执行（不要用 npm run dev 单独开浏览器）：

cd C:\Users\milo\Desktop\激光\jg
npm install
npm run electron:dev

开发环境调用链：

Vue → Electron → python runner.py → entry.cp311-win_amd64.pyd

开发环境前置条件

已安装 Python 3.11
已安装依赖：

cd serves\JiGuang-program
python -m pip install -r requirements.txt

仅替换 entry.pyd 后开发

# 1. 覆盖 JiGuang-program\entry.cp311-win_amd64.pyd
# 2. 重启应用
cd C:\Users\milo\Desktop\激光\jg
npm run electron:dev

不需要重新执行 build_runner.bat。

二、首次生成 api_runner.exe（只需一次）

用于在没有 Python 的电脑上离线运行。耗时 1~3 小时。

cd C:\Users\milo\Desktop\激光\jg\serves\JiGuang-program
.\build_runner.bat

编译成功后确认：

dir runner.dist\api_runner.exe
dir runner.dist\entry.cp311-win_amd64.pyd

可选：删除编译缓存减小体积

rmdir /s /q runner.build

三、更新 entry.pyd 后发布（常用，无需重编 api_runner）

算法方提供新的 entry.cp311-win_amd64.pyd 时：

# 1. 覆盖 JiGuang-program 根目录下的 entry.cp311-win_amd64.pyd

# 2. 同步到 runner.dist（几秒钟）
cd C:\Users\milo\Desktop\激光\jg\serves\JiGuang-program
.\sync_entry.bat

# 3. 重新打 Electron 安装包
cd C:\Users\milo\Desktop\激光\jg
npm run electron:build

npm run electron:build 会自动先执行 sync:entry。

安装包输出路径：

dist_electron\激光测距仪-0.0.1-setup.exe

四、命令速查表

命令	位置	用途	耗时
`npm run electron:dev`	项目根目录	本地开发调试	秒级
`python -m pip install -r requirements.txt`	JiGuang-program	安装 Python 依赖	分钟级
`.\build_runner.bat`	JiGuang-program	首次编译 api_runner.exe	1~3 小时
`.\sync_entry.bat`	JiGuang-program	同步 entry.pyd 到 runner.dist	秒级
`npm run sync:entry`	项目根目录	同上（npm 快捷方式）	秒级
`npm run electron:build`	项目根目录	打 Windows 安装包	10~30 分钟
`npm run electron:build:full`	项目根目录	完整重编 api_runner + 打安装包	1~3 小时+

五、什么时候需要 build_runner.bat？

场景	是否需要 build_runner.bat
更换新的 entry.pyd	❌ 不需要，用 sync_entry.bat
更换 license.lic	❌ 不需要，用 sync_entry.bat
修改 runner.py	❌ 开发直接用 python；发布前 sync_entry
首次搭建生产环境	✅ 需要
升级 pandas/numpy/scipy 等依赖	✅ 需要
更换 Python 3.11 版本	✅ 需要

六、生产环境运行方式

安装包在用户电脑上的调用链：

激光测距仪.exe → runner.dist\api_runner.exe → entry.cp311-win_amd64.pyd

用户电脑不需要安装 Python，可离线运行。

七、常见问题

1. PowerShell 无法运行 bat/ps1

# bat 必须加 .\
.\build_runner.bat
.\sync_entry.bat

# ps1 需要绕过执行策略
powershell -ExecutionPolicy Bypass -File .\build_runner.ps1

2. 路径中的 ADMINI~1 是乱码吗？

不是。这是 Windows 8.3 短路径，属于正常现象。

3. 本机能跑，别的电脑报错

确认已用 build_runner.bat 生成 runner.dist\api_runner.exe
确认发布前执行了 sync_entry.bat
确认安装包是最新 npm run electron:build 产物

4. build_runner 编译内存不足

脚本已使用 --jobs=1 降低内存占用。若仍失败，开发阶段可：

rmdir /s /q runner.dist
npm run electron:dev

八、Vue 侧 API 调用（无需修改）

// 加载测量数据
await window.electronAPI.callPythonAPI("loaddata", [
  定位文件,
  测量文件,
  锥角,
  倾角,
  阈值,
]);

// 获取历史数据 CSV 路径
await window.electronAPI.callPythonAPI("getpath");

// 查看历史详情
await window.electronAPI.callPythonAPI("historydata", [时间, 场站, 风机编号]);

// 删除历史数据
await window.electronAPI.callPythonAPI("deletedata", [时间, 场站, 风机编号]);

九、推荐发布流程（总结）

# 首次（或依赖升级时）才执行
cd serves\JiGuang-program
.\build_runner.bat

# 每次发版
# 1. 更新 entry.pyd / license.lic（如有）
# 2. 同步 + 打包
cd C:\Users\milo\Desktop\激光\jg
npm run electron:build

# 3. 分发
# dist_electron\激光测距仪-0.0.1-setup.exe

部署说明.md 6.1 KB Geschiedenis Ruwe