hi-client/说明文档.md

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/                       # 构建输出（运行时生成）

🚀 快速开始

本地构建

# 安装 Flutter 依赖
flutter pub get

# 生成代码
dart run build_runner build --delete-conflicting-outputs

# 构建 Windows Debug
flutter build windows

# 构建 Windows Release
flutter build windows --release

使用脚本

# 运行 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