Initial commit

docs/MeshRay Windows 构建使用指南.md

@@ -0,0 +1,490 @@
+# MeshRay Windows 构建使用指南
+
+**更新时间**: 2026-03-24  
+**状态**: ✅ **已验证可用**  
+**工具**: go-winres
+
+---
+
+## 🎯 **快速开始**
+
+### **方法一：一键构建（推荐）**
+
+```bash
+.\build.bat
+```
+
+**说明**: 
+- ✅ 自动检查并安装工具
+- ✅ 自动生成资源文件
+- ✅ 自动编译程序
+- ✅ 显示版本信息
+
+**预计耗时**: 约 30 秒
+
+---
+
+### **方法二：手动分步构建**
+
+如果你想了解每个步骤或遇到问题需要调试：
+
+#### **步骤 1: 生成 Windows 资源文件**
+
+```bash
+cd e:\Project\MeshRay
+go-winres make --in build\winres.json --arch amd64
+```
+
+**输出**:
+```
+✓ rsrc_windows_amd64.syso (288,160 字节)
+```
+
+**说明**: 
+- 包含程序图标（assets/app.ico）
+- 包含 Manifest 清单
+- 包含版本信息
+
+---
+
+#### **步骤 2: 复制 syso 到正确位置**
+
+```bash
+Copy-Item rsrc_windows_amd64.syso cmd\meshray\meshray.syso -Force
+```
+
+**关键点**:
+- ⚠️ **必须**放在 `cmd/meshray/` 目录
+- ✅ Go 编译器只会在包目录下查找 syso
+
+---
+
+#### **步骤 3: 编译程序**
+
+```bash
+go build -ldflags="-s -w" -o meshray.exe ./cmd/meshray
+```
+
+**输出**:
+```
+✓ meshray.exe (~30MB)
+```
+
+**参数说明**:
+- `-ldflags="-s -w"`: 去除调试信息，减小文件体积
+
+---
+
+#### **步骤 4: 验证结果**
+
+```powershell
+# 查看版本信息
+(Get-Item meshray.exe).VersionInfo | Select-Object CompanyName, FileDescription, FileVersion, ProductName
+
+# 或在资源管理器中查看图标
+explorer .
+```
+
+**期望输出**:
+```
+CompanyName     : MeshRay Team
+FileDescription : MeshRay - Decentralized Network Platform
+FileVersion     : 2.0.0.0
+ProductName     : MeshRay
+```
+
+---
+
+## 📋 **完整的 build.bat 流程**
+
+### **脚本内容解析**
+
+```batch
+@echo off
+REM MeshRay Windows 完整构建脚本（go-winres）
+
+REM [1/7] 检查 go-winres 工具
+where go-winres >nul 2>&1
+if %ERRORLEVEL% NEQ 0 (
+    go install github.com/tc-hib/go-winres@latest
+)
+
+REM [2/7] 检查配置文件
+if not exist build\winres.json (
+    echo [错误] 配置文件不存在
+    exit /b 1
+)
+
+REM [3/7] 生成资源文件
+go-winres make --in build\winres.json --arch amd64
+
+REM [4/7] 复制 syso 到 cmd/meshray
+copy rsrc_windows_amd64.syso cmd\meshray\meshray.syso
+
+REM [5/7] 编译程序
+go build -ldflags="-s -w" -o meshray.exe ./cmd/meshray
+
+REM [6/7] 清理临时文件
+del rsrc_*.syso
+del cmd\meshray\meshray.syso
+
+REM [7/7] 验证并显示版本信息
+powershell -Command "(Get-Item meshray.exe).VersionInfo.FileDescription"
+```
+
+---
+
+## 🔧 **常见问题与解决方案**
+
+### **问题 1: go-winres 未找到**
+
+**错误信息**:
+```
+'go-winres' is not recognized as an internal or external command
+```
+
+**解决方案**:
+```bash
+go install github.com/tc-hib/go-winres@latest
+```
+
+**验证安装**:
+```bash
+where go-winres
+# 应该显示：C:\Users\你的用户名\go\bin\go-winres.exe
+```
+
+**如果还是找不到**:
+1. 确保 `%GOPATH%\bin` 在 PATH 环境变量中
+2. 重启 PowerShell 或终端
+
+---
+
+### **问题 2: 配置文件不存在**
+
+**错误信息**:
+```
+[错误] 配置文件不存在：build\winres.json
+```
+
+**解决方案**:
+```bash
+# 检查文件是否存在
+dir build\winres.json
+
+# 如果不存在，从备份恢复或重新创建
+```
+
+**winres.json 位置**:
+```
+build/winres.json  ← 源配置文件
+```
+
+---
+
+### **问题 3: 资源文件生成失败**
+
+**可能原因**:
+1. ❌ 图标文件路径不对
+2. ❌ winres.json 格式错误
+3. ❌ 权限问题
+
+**解决方案**:
+```bash
+# 1. 检查图标文件
+dir assets\app.ico
+
+# 2. 验证 JSON 格式
+go run -c "import json; json.load(open('build/winres.json'))"
+
+# 3. 以管理员身份运行终端
+```
+
+---
+
+### **问题 4: 编译后没有图标**
+
+**原因**: syso文件位置不对
+
+**解决方案**:
+确保 syso在 `cmd/meshray/`目录：
+```
+cmd/meshray/meshray.syso  ← 必须在这里
+```
+
+**验证命令**:
+```bash
+dir cmd\meshray\*.syso
+```
+
+---
+
+### **问题 5: 版本信息为空**
+
+**现象**:
+```powershell
+(Get-Item meshray.exe).VersionInfo.FileDescription
+# 返回空字符串
+```
+
+**原因**: PowerShell 缓存问题
+
+**解决方案**:
+1. **等待几秒**:
+   ```bash
+   Start-Sleep -Seconds 3
+   (Get-Item meshray.exe).VersionInfo.FileDescription
+   ```
+
+2. **使用新进程**:
+   ```bash
+   powershell -Command "(Get-Item meshray.exe).VersionInfo.FileDescription"
+   ```
+
+3. **重启资源管理器**:
+   ```bash
+   Stop-Process -Name explorer -Force
+   Start-Sleep -Seconds 3
+   Start-Process explorer
+   ```
+
+4. **右键属性查看**（不受缓存影响）:
+   - 右键 meshray.exe
+   - 属性 → 详细信息
+
+---
+
+## 📊 **构建产物说明**
+
+### **生成的文件**
+
+| 文件 | 大小 | 用途 | 是否保留 |
+|------|------|------|----------|
+| **rsrc_windows_amd64.syso** | ~288KB | Windows 资源文件 | ❌ 临时，编译后删除 |
+| **meshray.exe** | ~30MB | 最终可执行文件 | ✅ 保留使用 |
+| **cmd/meshray/meshray.syso** | ~288KB | 编译时的资源 | ❌ 临时，编译后删除 |
+
+---
+
+### **项目结构**
+
+```
+e:\Project\MeshRay\
+├── build/
+│   ├── main.manifest        # Windows 清单文件
+│   ├── winres.json          # Windows 资源配置（JSON 格式）
+│   └── resource.rc          # RC 资源脚本（备用）
+├── assets/
+│   ├── app.ico              # 程序主图标 (278KB)
+│   └── tray_icon.ico        # 托盘图标 (4KB)
+├── cmd/
+│   └── meshray/
+│       ├── main.go          # 主程序入口
+│       └── meshray.syso     # 编译时的资源文件
+├── docs/                    # 文档目录
+├── internal/                # 内部代码
+├── web/                     # 前端代码
+├── build.bat                # Windows 构建脚本
+├── build.sh                 # 跨平台构建脚本
+└── meshray.exe              # 最终产物 ✅
+```
+
+---
+
+## 🛠️ **高级用法**
+
+### **自定义版本号**
+
+编辑 `build/winres.json`:
+```json
+{
+    "RT_VERSION": {
+        "DLL": {
+            "0409": {
+                "fixed": {
+                    "file_version": "2.0.1.0",  // 修改这里
+                    "product_version": "2.0.1.0" // 和这里
+                }
+            }
+        }
+    }
+}
+```
+
+然后重新构建：
+```bash
+.\build.bat
+```
+
+---
+
+### **添加中文版本信息**
+
+修改 `build/winres.json`，添加中文语言块：
+```json
+{
+    "RT_VERSION": {
+        "DLL": {
+            "080404E8": {  // 中文（中国）
+                "fixed": {
+                    "file_version": "2.0.0.0"
+                },
+                "info": {
+                    "080404E8": {
+                        "FileDescription": "MeshRay - 高效、安全的去中心化异地组网平台",
+                        "CompanyName": "MeshRay Team",
+                        "LegalCopyright": "Copyright (c) 2026 MeshRay Team"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+**注意**: 中文可能需要处理编码问题（UTF-8 with BOM）
+
+---
+
+### **多架构构建**
+
+**构建 32 位版本**:
+```bash
+go-winres make --in build\winres.json --arch 386
+go build -ldflags="-s -w" -o meshray-386.exe ./cmd/meshray
+```
+
+**同时构建 64 位和 32 位**:
+```bash
+go-winres make --in build\winres.json --arch amd64,386
+```
+
+---
+
+## 📝 **最佳实践**
+
+### **1. 首次使用前**
+
+```bash
+# 安装 go-winres 工具
+go install github.com/tc-hib/go-winres@latest
+
+# 验证安装
+go-winres --version
+
+# 检查配置文件
+dir build\winres.json
+
+# 检查图标文件
+dir assets\app.ico
+```
+
+---
+
+### **2. 日常构建**
+
+```bash
+# 最简单的方式
+.\build.bat
+
+# 或者使用 PowerShell 设置 UTF-8 编码
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+.\build.bat
+```
+
+---
+
+### **3. 清理构建环境**
+
+```bash
+# 删除所有临时文件
+Remove-Item rsrc_*.syso -ErrorAction SilentlyContinue
+Remove-Item cmd\meshray\*.syso -ErrorAction SilentlyContinue
+Remove-Item meshray.exe -ErrorAction SilentlyContinue
+
+# 清理Go缓存
+go clean -cache
+```
+
+---
+
+### **4. 验证构建结果**
+
+```bash
+# 1. 检查文件大小
+dir meshray.exe
+
+# 2. 查看版本信息
+(Get-Item meshray.exe).VersionInfo | Format-List
+
+# 3. 在资源管理器中查看图标
+explorer .
+```
+
+---
+
+## 🎯 **故障排查流程图**
+
+```
+开始
+  ↓
+检查 go-winres 是否安装？
+  ├─ 否 → go install github.com/tc-hib/go-winres@latest
+  └─ 是 ↓
+检查 build/winres.json 是否存在？
+  ├─ 否 → 创建或恢复配置文件
+  └─ 是 ↓
+检查 assets/app.ico 是否存在？
+  ├─ 否 → 准备 ICO 格式图标文件
+  └─ 是 ↓
+执行 go-winres make
+  ├─ 失败 → 检查错误信息，修复配置
+  └─ 成功 ↓
+复制 syso 到 cmd/meshray/
+  ↓
+执行 go build
+  ├─ 失败 → 检查 syso 位置
+  └─ 成功 ↓
+验证版本信息
+  ├─ 为空 → 等待缓存刷新或重启 PowerShell
+  └─ 正常 → ✅ 构建完成
+```
+
+---
+
+## 📚 **相关文档**
+
+- [MeshRay Windows 图标与版本信息完美解决方案.md](./MeshRay Windows 图标与版本信息完美解决方案.md)
+- [优化构建脚本 - 移除 winres 目录.md](./优化构建脚本 - 移除 winres 目录.md)
+- [MeshRay 构建脚本已更新.md](./MeshRay 构建脚本已更新.md)
+
+---
+
+## ✅ **总结**
+
+### **推荐方案**
+
+| 场景 | 推荐方法 | 说明 |
+|------|----------|------|
+| **日常构建** | `.\build.bat` | 一键完成，最简单 |
+| **学习理解** | 手动分步执行 | 了解每个步骤 |
+| **问题调试** | 手动分步 + 详细日志 | 定位问题所在 |
+| **CI/CD** | 参考 build.bat 编写脚本 | 自动化流程 |
+
+---
+
+### **核心要点**
+
+1. ✅ **工具准备**: 安装 go-winres
+2. ✅ **配置文件**: build/winres.json
+3. ✅ **关键步骤**: syso 必须放在 cmd/meshray/
+4. ✅ **版本信息**: 通过 winres.json 统一管理
+5. ✅ **构建脚本**: 使用 build.bat 一键完成
+
+---
+
+**使用状态**: ✅ **已验证可用，无卡住问题**  
+**推荐方式**: ✅ **使用 build.bat 一键构建**  
+**注意事项**: ✅ **syso文件位置是关键**  
+
+*MeshRay - 简单、高效、专业的构建体验！* ✨