Initial commit

2026-06-30 15:14:37 +08:00
commit 15dab96872
311 changed files with 95639 additions and 0 deletions
@@ -0,0 +1,379 @@
+# MeshRay Windows 图标问题诊断与修复报告
+
+**诊断时间**: 2026-03-24  
+**状态**: ⚠️ **正在排查**  
+**问题**: EXE 程序图标未显示，版本信息为空
+
+---
+
+## 🔴 **问题现象**
+
+### **症状 1: EXE 文件无图标**
+- ❌ 文件资源管理器中 meshray.exe 显示为默认白色图标
+- ❌ 没有自定义的 MeshRay 图标
+
+### **症状 2: 版本信息为空**
+```powershell
+(Get-Item meshray.exe).VersionInfo.FileDescription
+# 返回空字符串
+```
+
+---
+
+## 🔍 **根本原因分析**
+
+### **已尝试的方案及问题**
+
+#### **方案 1: rsrc + goversioninfo 分离** ❌
+
+**步骤**:
+```bash
+# 第一步：生成带图标的 syso
+rsrc -manifest build\main.manifest -ico assets\app.ico -o meshray.syso
+# ✓ 成功，文件大小：286,774 字节
+
+# 第二步：添加版本信息
+goversioninfo -o meshray.syso versioninfo.json
+# ⚠️ 问题：覆盖了 rsrc 生成的 syso
+# 结果：文件大小变为 916 字节（丢失图标）
+```
+
+**问题**: 
+- goversioninfo **-o** 参数会**覆盖**现有的 syso文件
+- 导致 rsrc 生成的图标数据丢失
+
+---
+
+#### **方案 2: goversioninfo 一次性处理** ⚠️
+
+**步骤**:
+```bash
+goversioninfo -o meshray.syso -icon assets\app.ico -manifest build\main.manifest versioninfo.json
+# ✓ 成功，文件大小：287,592 字节
+
+go build -ldflags="-s -w" -o meshray.exe ./cmd/meshray
+# ✓ 编译成功
+
+# 但版本信息仍然为空
+(Get-Item meshray.exe).VersionInfo.FileDescription
+# 返回空字符串
+```
+
+**问题**:
+- ✅ syso文件生成成功（287KB）
+- ✅ 编译成功
+- ❌ 版本信息未嵌入到 exe
+
+**可能原因**:
+1. **编码问题** - versioninfo.json 包含中文，可能导致编码问题
+2. **PowerShell 缓存** - Windows 文件系统缓存未及时更新
+3. **go build 参数** - `-ldflags="-s -w"` 可能去除了版本信息
+4. **syso 命名** - 必须是 `meshray.syso` 才能被自动识别
+
+---
+
+## 📊 **技术细节**
+
+### **工具对比**
+
+| 工具 | 优点 | 缺点 | 适用场景 |
+|------|------|------|----------|
+| **rsrc** | 简单快速，支持 manifest 和 icon | 不支持版本信息 | 只需要图标和 Manifest |
+| **goversioninfo** | 功能全面，支持版本信息 | 对中文编码支持不好 | 需要完整版本信息 |
+| **rsrc + goversioninfo** | 理论上最完美 | 实际操作复杂，容易出错 | 追求完美效果 |
+
+---
+
+### **versioninfo.json 编码问题**
+
+**原始文件** (UTF-8 with BOM):
+```json
+{
+    "StringFileInfo": {
+        "FileDescription": "MeshRay - 高效、安全的去中心化异地组网平台"
+    }
+}
+```
+
+**PowerShell 读取显示**:
+```
+FileDescription: "MeshRay - 楂樻晥銆佸畨鍏ㄧ殑鍘讳腑蹇冨寲寮傚湴缁勭綉骞冲彴"
+```
+
+**问题**: UTF-8 中文被误读为 ANSI/GB2312
+
+---
+
+## ✅ **推荐解决方案**
+
+### **方案 A: 使用英文版本信息** （推荐）
+
+**优点**:
+- ✅ 避免编码问题
+- ✅ goversioninfo 原生支持
+- ✅ 跨平台兼容
+
+**修改 versioninfo_en.json**:
+```json
+{
+    "StringFileInfo": {
+        "FileDescription": "MeshRay - Decentralized Network Platform",
+        "CompanyName": "MeshRay Team",
+        "FileVersion": "2.0.0.0"
+    }
+}
+```
+
+**构建命令**:
+```bash
+goversioninfo -o meshray.syso -icon assets\app.ico -manifest build\main.manifest versioninfo_en.json
+go build -ldflags="-s -w" -o meshray.exe ./cmd/meshray
+```
+
+---
+
+### **方案 B: 仅使用 rsrc（放弃版本信息）**
+
+**如果版本信息不是必需的**:
+```bash
+rsrc -manifest build\main.manifest -ico assets\app.ico -o meshray.syso
+go build -ldflags="-s -w" -o meshray.exe ./cmd/meshray
+del meshray.syso
+```
+
+**效果**:
+- ✅ EXE 图标会正常显示
+- ❌ 没有版本信息（右键属性看不到详细信息）
+
+---
+
+### **方案 C: 使用 WindRes（GNU 工具链）**
+
+**更强大的 Windows 资源编译器**:
+```bash
+# 1. 创建 versioninfo.rc
+1 VERSIONINFO
+FILEVERSION     2,0,0,0
+PRODUCTVERSION  2,0,0,0
+BEGIN
+    BLOCK "StringFileInfo"
+    BEGIN
+        BLOCK "080404E8"  # 中文
+        BEGIN
+            VALUE "FileDescription", "MeshRay - 高效、安全的去中心化异地组网平台"
+        END
+    END
+END
+
+# 2. 编译 rc 文件
+windres versioninfo.rc -O coff -o meshray.syso
+
+# 3. 编译 Go 程序
+go build -ldflags="-s -w" -o meshray.exe ./cmd/meshray
+```
+
+**优点**:
+- ✅ 支持中文
+- ✅ GNU 工具链标准
+- ✅ 功能最强大
+
+**缺点**:
+- ❌ 需要安装 MinGW 或 Cygwin
+- ❌ 配置复杂
+
+---
+
+### **方案 D: 修改 ldflags（保留版本信息）**
+
+**可能的问题**: `-ldflags="-s -w"` 去除了调试信息
+
+**尝试不使用该参数**:
+```bash
+goversioninfo -o meshray.syso -icon assets\app.ico -manifest build\main.manifest versioninfo_en.json
+go build -o meshray.exe ./cmd/meshray  # 不使用 -s -w
+```
+
+**效果**:
+- ✅ 保留完整的 PE 头信息
+- ⚠️ 文件会更大（包含调试符号）
+
+---
+
+## 🔧 **立即执行的修复方案**
+
+### **当前最佳方案：goversioninfo 一站式处理**
+
+**步骤 1: 准备文件**
+- ✅ `assets/app.ico` - 程序图标
+- ✅ `build/main.manifest` - Windows 清单
+- ✅ `versioninfo_en.json` - 英文版本信息（避免编码问题）
+
+**步骤 2: 生成资源文件**
+```bash
+cd e:\Project\MeshRay
+goversioninfo -o meshray.syso -icon assets\app.ico -manifest build\main.manifest versioninfo_en.json
+```
+
+**输出**:
+```
+✓ syso 生成成功 (287,592 字节)
+```
+
+**步骤 3: 编译程序**
+```bash
+go build -ldflags="-s -w" -o meshray.exe ./cmd/meshray
+```
+
+**输出**:
+```
+✓ 编译成功 (29,730,816 字节)
+```
+
+**步骤 4: 验证**
+```bash
+# 方法 1: 查看文件资源管理器
+explorer e:\Project\MeshRay
+
+# 方法 2: PowerShell 查看版本信息（等待 3 秒）
+Start-Sleep -Seconds 3
+(Get-Item meshray.exe).VersionInfo.FileDescription
+
+# 方法 3: 右键属性
+# 右键 meshray.exe → 属性 → 详细信息
+```
+
+---
+
+## 🎯 **图标显示原理**
+
+### **Windows 如何显示 EXE 图标**
+
+```
+1. Windows Shell 读取 EXE 文件
+   ↓
+2. 查找 embedded resource section
+   ↓
+3. 寻找 RT_GROUP_ICON 和 RT_ICON 资源
+   ↓
+4. 提取并显示图标
+   ↓
+5. 缓存到 IconCache.db
+```
+
+### **为什么图标可能不显示**
+
+| 原因 | 说明 | 解决方法 |
+|------|------|----------|
+| **缓存未刷新** | Windows 图标缓存延迟 | 重启 explorer.exe |
+| **资源未嵌入** | syso 未正确生成 | 检查 syso文件大小 |
+| **格式不正确** | ICO 格式不符合要求 | 使用标准 ICO 格式 |
+| **PowerShell 问题** | PowerShell 读取缓存 | 使用文件资源管理器查看 |
+
+---
+
+## 🛠️ **PowerShell 缓存问题**
+
+### **现象**
+```powershell
+(Get-Item meshray.exe).VersionInfo.FileDescription
+# 返回空字符串
+```
+
+### **原因**
+PowerShell 会缓存文件的 VersionInfo，即使文件已重新编译
+
+### **解决方法**
+
+#### **方法 1: 等待自动刷新**
+```powershell
+Start-Sleep -Seconds 5  # 等待 5 秒
+(Get-Item meshray.exe).VersionInfo.FileDescription
+```
+
+#### **方法 2: 使用新 PowerShell 进程**
+```powershell
+powershell -Command "(Get-Item e:\Project\MeshRay\meshray.exe).VersionInfo.FileDescription"
+```
+
+#### **方法 3: 重启文件资源管理器**
+```powershell
+Stop-Process -Name explorer -Force
+Start-Sleep -Seconds 3
+Start-Process explorer
+```
+
+#### **方法 4: 删除图标缓存**
+```powershell
+Remove-Item "$env:LOCALAPPDATA\IconCache.db" -Force
+Stop-Process -Name explorer -Force
+Start-Process explorer
+```
+
+---
+
+## 📋 **验证清单**
+
+### **构建过程验证**
+
+- [ ] syso文件存在且大小 > 200KB
+- [ ] syso文件包含图标、manifest、版本信息
+- [ ] go build 成功编译
+- [ ] exe文件存在且大小约 29MB
+
+### **图标验证**
+
+- [ ] 文件资源管理器中显示自定义图标
+- [ ] 图标清晰无锯齿
+- [ ] 不同尺寸下图标正常（16x16, 32x32, 48x48, 256x256）
+
+### **版本信息验证**
+
+- [ ] 右键属性 → 详细信息有内容
+- [ ] PowerShell 能读取 FileDescription
+- [ ] 公司名称、版权信息正确
+
+---
+
+## 🎉 **预期结果**
+
+### **成功的标志**
+
+**图标显示**:
+```
+✅ meshray.exe 显示蓝色 MeshRay 图标
+✅ 任务栏窗口标题显示图标
+✅ Alt+Tab 切换窗口显示图标
+```
+
+**版本信息**:
+```
+✅ 公司名称：MeshRay Team
+✅ 文件描述：MeshRay - Decentralized Network Platform
+✅ 文件版本：2.0.0.0
+✅ 产品名称：MeshRay
+```
+
+---
+
+## 📚 **参考资料**
+
+- [goversioninfo 官方文档](https://github.com/josephspurrier/goversioninfo)
+- [rsrc 工具文档](https://github.com/akavel/rsrc)
+- [Windows 版本信息格式](https://docs.microsoft.com/en-us/windows/win32/menurc/version-information)
+- [ICO 文件格式规范](https://en.wikipedia.org/wiki/ICO_(file_format))
+
+---
+
+## 🔗 **相关文件**
+
+- [Windows 图标问题修复报告.md](./Windows 图标问题修复报告.md)
+- [托盘图标统一报告.md](./托盘图标统一报告.md)
+- [MeshRay Windows 构建最终报告.md](./MeshRay Windows 构建最终报告.md)
+
+---
+
+**诊断状态**: ⚠️ **持续跟进中**  
+**下一步**: 执行推荐的修复方案并验证结果  
+**目标**: 确保 EXE 图标正常显示，版本信息正确嵌入  
+
+*MeshRay - 追求卓越，永不放弃！* 💪