shanshanzhong
b86d645acf
添加 Enigma Virtual Box 和 7-Zip 备选方案，用于将 Flutter Windows 应用打包为单文件 EXE 包含自动化脚本和文档说明，优化构建产物分发
140 lines
3.6 KiB
Markdown
140 lines
3.6 KiB
Markdown
# Windows 构建项目说明文档
|
||
|
||
## 🎯 项目概述
|
||
|
||
本项目是一个 Flutter Windows 应用程序，已成功配置完整的 Windows 构建流程。
|
||
|
||
## ✅ 构建状态
|
||
|
||
**当前状态**: ✅ **构建成功**
|
||
|
||
- **Debug 构建**: ✓ 成功 (282.5s)
|
||
- **Release 构建**: ✓ 成功 (27s)
|
||
- **构建环境**: Windows Server + Visual Studio 2022 Enterprise
|
||
|
||
## 🏗️ 构建流程
|
||
|
||
### 1. 环境准备
|
||
- ✅ Flutter 3.24.5 已安装
|
||
- ✅ Visual Studio 2022 Enterprise 已配置
|
||
- ✅ NuGet 6.14.0 已安装（通过 Chocolatey）
|
||
- ✅ Windows 长路径支持已启用
|
||
|
||
### 2. 构建步骤
|
||
1. **代码检出** - 从 Gitea 仓库获取代码
|
||
2. **依赖安装** - 安装 Flutter 依赖包
|
||
3. **代码生成** - 运行 build_runner 生成代码
|
||
4. **Windows 构建** - 构建 Debug 和 Release 版本
|
||
5. **产物上传** - 上传构建产物到 Gitea Actions
|
||
|
||
### 3. 构建输出
|
||
```
|
||
Debug: build/windows/x64/runner/Debug/hostexecutor.exe
|
||
Release: build/windows/x64/runner/Release/hostexecutor.exe
|
||
```
|
||
|
||
## 🔧 关键修复记录
|
||
|
||
### 1. NuGet 安装问题
|
||
**问题**: SSL/TLS 安全通道错误
|
||
**解决方案**:
|
||
- 使用 Chocolatey 安装 NuGet
|
||
- 命令: `choco install nuget.commandline -y`
|
||
|
||
### 2. Flutter 路径配置
|
||
**问题**: Flutter 命令未找到
|
||
**解决方案**:
|
||
- 添加 Flutter 到 PATH: `C:\flutter\bin`
|
||
- 在每个构建步骤中显式设置 PATH
|
||
|
||
### 3. 长路径问题
|
||
**问题**: Windows 路径长度限制
|
||
**解决方案**:
|
||
- 启用 Windows 长路径支持
|
||
- 注册表设置: `LongPathsEnabled = 1`
|
||
|
||
### 4. 构建产物路径
|
||
**问题**: 上传路径配置错误
|
||
**解决方案**:
|
||
- 修正路径: `build/windows/x64/runner/Debug/`
|
||
- 原错误路径: `build/windows/runner/Debug/`
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
/Users/Apple/vpn/hi-client/
|
||
├── .gitea/workflows/ # Gitea Actions 工作流配置
|
||
├── lib/ # Flutter 源代码
|
||
│ ├── app/ # 应用程序代码
|
||
│ ├── core/ # 核心功能
|
||
│ └── singbox/ # SingBox 相关
|
||
├── windows/ # Windows 平台配置
|
||
├── libcore/ # 核心库（子模块）
|
||
└── build/ # 构建输出（运行时生成）
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 本地构建
|
||
```bash
|
||
# 安装 Flutter 依赖
|
||
flutter pub get
|
||
|
||
# 生成代码
|
||
dart run build_runner build --delete-conflicting-outputs
|
||
|
||
# 构建 Windows Debug
|
||
flutter build windows
|
||
|
||
# 构建 Windows Release
|
||
flutter build windows --release
|
||
```
|
||
|
||
### 使用脚本
|
||
```bash
|
||
# 运行 Windows 构建修复脚本
|
||
./fix_windows_build.ps1
|
||
|
||
# 安装 NuGet（如果需要）
|
||
./install_nuget_simple.bat
|
||
```
|
||
|
||
## 📋 注意事项
|
||
|
||
### 1. 构建环境要求
|
||
- Windows 10/11 或 Windows Server
|
||
- Visual Studio 2022（包含 C++ 开发工具）
|
||
- Flutter 3.24.5+
|
||
- NuGet CLI
|
||
|
||
### 2. 常见问题
|
||
- **CMake 警告**: 可忽略，不影响构建
|
||
- **WebView2 警告**: 类型转换警告，不影响功能
|
||
- **路径问题**: 确保使用正确的 x64 路径
|
||
|
||
### 3. 性能优化
|
||
- Debug 构建约 4.7 分钟
|
||
- Release 构建约 27 秒
|
||
- 建议使用 Release 版本进行分发
|
||
|
||
## 🔍 调试工具
|
||
|
||
### 构建日志分析
|
||
查看 `构建日志分析.md` 文件获取详细的构建日志分析和故障排除指南。
|
||
|
||
### 连接状态调试
|
||
使用 `debug_connection_status.dart` 工具检查应用连接状态。
|
||
|
||
## 📞 支持
|
||
|
||
如遇到构建问题，请检查：
|
||
1. 环境配置是否正确
|
||
2. 依赖是否完整安装
|
||
3. 查看构建日志获取具体错误信息
|
||
4. 参考本说明文档的修复记录
|
||
|
||
---
|
||
|
||
**最后更新**: $(date)
|
||
**构建状态**: ✅ 成功
|
||
**文档版本**: 1.0 |