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