Rowland/EG

Fork 1

tian bc1abe0060 Trim redundant build script docs

2026-03-15 01:37:33 +08:00

9.8 KiB

Raw Permalink Blame History

元泰 EG 构建完整指南

本文档提供从零开始构建元泰 EG 安装程序的完整步骤。

📋 环境要求

必须条件

组件	版本	说明
Python	3.11.x	必须使用 3.11，其他版本不保证兼容
Windows	10/11	64位系统
磁盘空间	5GB+	构建需要大量临时文件
内存	4GB+	建议 8GB

检查 Python 版本

# 检查版本
python --version
# 必须显示: Python 3.11.x

# 使用项目提供的检查脚本
python build_scripts/check_python_version.py

如果版本不对，请参考 build_scripts/PYTHON_VERSION_REQUIREMENT.md 安装正确版本。

🚀 快速开始（5分钟）

步骤 1: 安装依赖

# 确保是 Python 3.11
python --version

# 安装最小依赖（推荐）
python -m pip install -r requirements/requirements-minimal.txt

步骤 2: 验证安装

# 测试程序能否运行
python Start_Run.py

步骤 3: 构建安装程序

# 进入 VS Dev Shell（必须有 C++ 编译器）
# 然后执行构建脚本
.\build_scripts\build_windows.ps1 -Version "1.0.0"

📌 打包原则

从 2026-03 的修复开始，项目采用“保守打包优先”的策略：

优先保证发行版可运行，不先追求安装包最小化
对 RenderPipeline、动态插件、文件路径动态导入使用显式白名单
将 RenderPipelineFile、Resources、config、demo 等目录视为运行时资源，整体复制
保留启动日志 eg_startup.log，用于定位打包后启动异常

详细背景和源码整改建议请参考：

build_scripts/PACKAGING_RISK_AUDIT.md

📦 依赖说明

最小依赖（requirements-minimal.txt）

只包含程序运行必需的依赖：

Panda3D==1.10.16          # 3D 引擎核心
panda3d-frame             # Panda3D 扩展
panda3d-imgui==1.1.0      # ImGui 集成
imgui-bundle==1.92.4      # ImGui 绑定
openvr==2.2.0             # VR 支持
Pillow==11.3.0            # 图像处理
PyYAML==5.4.1             # 配置解析
psutil==5.9.0             # 系统工具

已移除的依赖

以下依赖已从项目中移除，节省约 170MB：

依赖	节省空间	原因
PyQt5	~50 MB	未使用
PySide6	~100 MB	未使用
PyQt5-Qt5, PyQt5_sip 等	~20 MB	配套库

清理旧依赖

如果之前安装过旧依赖，建议清理：

# 卸载未使用的 Qt 库
python -m pip uninstall -y PyQt5 PyQt5-Qt5 PyQt5_sip PySide6 PySide6_Addons PySide6_Essentials shiboken6

# 清理 pip 缓存
python -m pip cache purge

🔧 详细构建步骤

第一步：环境准备

安装 Python 3.11
- 下载：https://www.python.org/downloads/release/python-3119/
- 安装时勾选 "Add Python to PATH"
安装 Visual Studio Build Tools（Windows 必需）
- 下载：https://visualstudio.microsoft.com/visual-cpp-build-tools/
- 选择 "使用 C++ 的桌面开发"
- 或安装完整 Visual Studio 2022

验证环境

# 检查 Python
python --version  # Python 3.11.x

# 检查编译器（在 VS Dev Shell 中）
cl  # 应显示版本信息

第二步：安装项目依赖

# 进入项目目录
cd C:\path\to\EG

# 安装依赖
python -m pip install -r requirements/requirements-minimal.txt

# 验证安装
python -c "import panda3d.core; import imgui_bundle; print('✓ 依赖安装成功')"

第三步：运行测试

# 测试程序能否正常启动
python Start_Run.py

第四步：打开 VS Dev Shell

什么是 VS Dev Shell？ VS Dev Shell（Visual Studio 开发人员命令提示符）是一个包含 C++ 编译器（cl.exe）的特殊命令行窗口，Nuitka 需要它来编译 Python 代码为机器码。

如何打开 VS Dev Shell：

方法 1: 通过开始菜单（推荐）

按 Win 键打开开始菜单
搜索：Developer Command Prompt
- 或中文：开发人员命令提示符
点击 "Developer Command Prompt for VS 2022"
建议右键选择 "以管理员身份运行"

方法 2: 通过 Visual Studio

打开 Visual Studio 2022
点击菜单栏的 "工具" → "命令行" → "开发者命令提示符"

方法 3: 使用 PowerShell 命令

# 如果知道 VS 安装路径
& "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Launch-VsDevShell.ps1" -Arch amd64

验证 VS Dev Shell 已正确打开：

# 在 VS Dev Shell 中执行
cl

# 应该显示类似：
# 用于 x64 的 Microsoft (R) C/C++ 优化编译器 19.xx.xxxxx 版

第五步：构建安装程序

在 VS Dev Shell 中执行：

方法 A：使用构建脚本（推荐）

# 1. 进入项目目录
cd C:\Users\Tellme\apps\EG

# 2. 切换到 PowerShell（如果当前是 cmd）
powershell

# 3. 执行构建
.\build_scripts\build_windows.ps1 -Version "1.0.0"

该脚本已包含以下关键修复：

修正 RenderPipeline 在打包后可能找错 config/pipeline.yaml 的问题
显式包含 rpcore、rplibs、rpplugins
自动探测并尽量纳入 plugins、gltf、playwright、PyQt5 等可选包
自动复制运行时资源目录

方法 B：手动构建

# 在 VS Dev Shell 中
cd C:\path\to\EG

python -m nuitka `
    --standalone `
    --include-package=panda3d `
    --include-package=direct `
    --include-package=imgui_bundle `
    --include-package=p3dimgui `
    --include-package=openvr `
    --include-package=RenderPipelineFile `
    --include-package=rpcore `
    --include-package=rplibs `
    --include-package=rpplugins `
    --follow-import-to=rpcore `
    --follow-import-to=rpplugins `
    --include-data-files="$env:APPDATA\Python\Python311\site-packages\imgui_bundle\glfw3.dll=imgui_bundle\glfw3.dll" `
    --windows-icon-from-ico=icons/app.ico `
    --windows-disable-console `
    --output-dir=build/nuitka `
    --jobs=4 `
    Start_Run.py

说明：

当前更推荐 standalone + 资源目录复制 的方式，而不是 onefile
RenderPipeline、动态插件和外部资源目录在 onefile 下更容易出现路径问题

第五步：打包资源

构建完成后，手动复制资源文件：

# 创建输出目录
$Version = "1.0.0"
New-Item -ItemType Directory -Force -Path "dist\EG_$Version" | Out-Null

# 复制可执行文件
Copy-Item "build\nuitka\Start_Run.exe" "dist\EG_$Version\元泰.exe" -Force

# 复制资源目录
$dirs = @("config", "icons", "Resources", "tex", "templates",
         "core", "gui", "project", "scene", "scripts",
         "ssbo_component", "tools", "TransformGizmo", "ui",
         "RenderPipelineFile", "vr_actions", "new")

foreach ($dir in $dirs) {
    Copy-Item $dir "dist\EG_$Version\$dir" -Recurse -Force
}

Write-Host "✓ 打包完成: dist\EG_$Version"

如果使用 build_windows.ps1，通常不需要再手动执行这一段，因为脚本已经自动复制资源。

Linux 构建说明

Linux 构建脚本：

./build_scripts/build_linux.sh "1.0.0"

Linux 脚本已按与 Windows 相同的思路补强：

使用保守白名单显式包含核心包
自动探测并尽量纳入可选依赖
整体复制运行时资源目录
在 AppRun 中设置 EG_PROJECT_ROOT
让 AppImage 内的程序从真实资源根目录启动

📁 构建输出

构建完成后，输出目录结构：

dist/EG_1.0.0/
├── 元泰.exe              # 主程序 (~120MB)
├── config/               # 配置文件
├── icons/                # 图标资源
├── Resources/            # 模型、材质等资源
├── RenderPipelineFile/   # 渲染管线
├── ...                   # 其他数据目录
└── (无 .py 源代码)       # 已编译为机器码

🐛 常见问题

Q1: Python 版本错误

错误：必须使用 Python 3.11，当前版本是 3.13.5

解决：

# 安装 Python 3.11
# 参考 build_scripts/PYTHON_VERSION_REQUIREMENT.md

Q2: 找不到 C++ 编译器

错误：未找到 Visual C++ 编译器

解决：

安装 Visual Studio Build Tools
在 VS Dev Shell 中运行构建

Q3: 缺少 DLL

错误：Cannot find glfw3.dll

解决：确保 --include-data-files 参数正确指向 DLL 路径：

# 注意 Python 版本路径
# Python 3.11: ...\Python311\...
# Python 3.13: ...\Python313\...

Q4: ModuleNotFoundError: rpcore

错误：No module named 'rpcore'

解决：确保使用 --follow-import-to=rpcore

Q5: 找不到 pipeline.yaml / rpplugins.*

错误示例：

Failed to load YAML file: File not found
No such file or directory: /$$rpconfig/pipeline.yaml
ModuleNotFoundError: No module named 'rpplugins.ao'

原因：

RenderPipeline 在打包后可能把基路径识别错
插件通过配置文件动态加载，打包器不会稳定自动发现

解决：

使用仓库中的最新 build_windows.ps1 / build_linux.sh
确保 RenderPipelineFile 被整体复制
确保 rpcore、rplibs、rpplugins 被显式纳入打包

Q6: 双击后闪退，没有控制台输出

解决：

查看发行目录中的 eg_startup.log
该文件会记录启动阶段 traceback
遇到打包问题时，优先保留这个日志进行排查

📚 相关文档

文档	用途
`build_scripts/README.md`	build_scripts 目录说明
`build_scripts/ICON_GUIDE.md`	图标准备
`build_scripts/PACKAGING_RISK_AUDIT.md`	打包风险与整改建议
`build_scripts/PYTHON_VERSION_REQUIREMENT.md`	Python 版本要求
`build_scripts/PACKAGING_CHECKLIST.md`	打包检查清单

最后更新: 2024年

9.8 KiB Raw Permalink Blame History Unescape Escape