# 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 - 简单、高效、专业的构建体验！* ✨