Meshray-Manager/README-Windows-GUI.md

MeshRay Windows 无控制台窗口版本 - 快速指南

更新时间: 2026-03-24
编译参数: -ldflags "-s -w -H=windowsgui"

---

🚀 快速编译

方法一：一键编译（推荐）

在项目根目录执行：

go build -o meshray.exe -ldflags "-s -w -H=windowsgui" ./cmd/meshray

效果:

• ✅ 不显示控制台窗口
• ✅ 系统托盘图标正常
• ✅ 文件体积优化（约 31 MB）

---

方法二：使用批处理脚本

双击运行 build.bat，自动完成编译。

注意: 如果遇到编码问题，请使用方法一手动编译。

---

✅ 验证结果

1. 检查文件大小

ls meshray.exe
# 应该约 31 MB

---

2. 运行测试

双击运行 meshray.exe：

预期效果:

• ✅ 没有黑色控制台窗口弹出
• ✅ 系统托盘出现 MeshRay 图标
• ✅ 可以通过托盘菜单操作

❌ 如果看到控制台窗口:

• 可能忘记添加 -H=windowsgui 参数
• 可能运行了旧版本程序

---

🔧 参数说明

参数	作用	效果
-s	去除符号表	减小文件大小
-w	去除 DWARF 调试信息	减小文件大小
-H=windowsgui	关键 - 设置为 Windows GUI 子系统	隐藏控制台窗口

---

📊 对比

编译方式	文件大小	控制台窗口	适用场景
无参数	~38 MB	❌ 显示	开发调试
-s -w	~32 MB	❌ 显示	开发调试
-s -w -H=windowsgui	~31 MB	✅ 隐藏	正式发布 ✨

---

💡 常见问题

Q: 隐藏控制台后如何查看日志？

A: 有三种方式：

1. 查看日志文件:

   Get-Content logs\meshray.log -Tail 50
   

2. 通过系统托盘:

   • 右键点击托盘图标
   • 选择 "打开日志"

3. 实时监控:

   tail -f logs\meshray.log
   

---

Q: 程序崩溃了怎么办？

A:

1. 重新编译为 Debug 模式:

   go build -o meshray-debug.exe ./cmd/meshray
   

2. 查看日志文件:

   Get-Content logs\meshray.log -Tail 100
   

---

📝 完整构建流程

# Step 1: 编译前端
cd web
npm run build
cd ..

# Step 2: 清理缓存
go clean -cache

# Step 3: 编译（带 windowsgui）
go build -o meshray.exe -ldflags "-s -w -H=windowsgui" ./cmd/meshray

# Step 4: 嵌入图标（可选但推荐）
go-winres patch --in build\winres.json meshray.exe

# Step 5: 验证
(Get-Item meshray.exe).VersionInfo | Format-List

---

🎯 最佳实践

开发环境

# 保留控制台输出，方便看日志
go build -o meshray.exe ./cmd/meshray

生产环境

# 隐藏控制台，优化体积
go build -o meshray.exe -ldflags "-s -w -H=windowsgui" ./cmd/meshray

---

📚 相关文档

• [Windows GUI 程序编译配置指南.md](./Windows%20GUI 程序编译配置指南.md) - 详细说明
• 路由注册顺序检查清单.md - 防止路由顺序错误

---

状态: ✅ 已配置
编译命令: go build -o meshray.exe -ldflags "-s -w -H=windowsgui" ./cmd/meshray

MeshRay - 注重用户体验，从细节开始！ ✨🪟