# 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