# 元泰 EG 构建完整指南

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

---

## 📋 环境要求

### 必须条件

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

### 检查 Python 版本

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

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

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

---

## 🚀 快速开始（5分钟）

### 步骤 1: 安装依赖

```powershell
# 确保是 Python 3.11
python --version

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

### 步骤 2: 验证安装

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

### 步骤 3: 构建安装程序

```powershell
# 进入 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 | 配套库 |

### 清理旧依赖

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

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

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

---

## 🔧 详细构建步骤

### 第一步：环境准备

1. **安装 Python 3.11**
   - 下载：https://www.python.org/downloads/release/python-3119/
   - 安装时勾选 "Add Python to PATH"

2. **安装 Visual Studio Build Tools**（Windows 必需）
   - 下载：https://visualstudio.microsoft.com/visual-cpp-build-tools/
   - 选择 "使用 C++ 的桌面开发"
   - 或安装完整 Visual Studio 2022

3. **验证环境**
   ```powershell
   # 检查 Python
   python --version  # Python 3.11.x
   
   # 检查编译器（在 VS Dev Shell 中）
   cl  # 应显示版本信息
   ```

### 第二步：安装项目依赖

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

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

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

### 第三步：运行测试

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

### 第四步：打开 VS Dev Shell

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

**如何打开 VS Dev Shell：**

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

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

#### 方法 2: 通过 Visual Studio

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

#### 方法 3: 使用 PowerShell 命令

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

**验证 VS Dev Shell 已正确打开：**

```powershell
# 在 VS Dev Shell 中执行
cl

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

### 第五步：构建安装程序

在 **VS Dev Shell** 中执行：

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

```powershell
# 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：手动构建

```powershell
# 在 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` 下更容易出现路径问题

### 第五步：打包资源

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

```powershell
# 创建输出目录
$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 构建脚本：

```bash
./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`

**解决**：
```powershell
# 安装 Python 3.11
# 参考 build_scripts/PYTHON_VERSION_REQUIREMENT.md
```

### Q2: 找不到 C++ 编译器

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

**解决**：
1. 安装 Visual Studio Build Tools
2. 在 **VS Dev Shell** 中运行构建

### Q3: 缺少 DLL

**错误**：`Cannot find glfw3.dll`

**解决**：确保 `--include-data-files` 参数正确指向 DLL 路径：
```powershell
# 注意 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年
