第02章 - 环境准备与编译构建

上一章我们从宏观上认识了 robotgo-flow。本章将带你一步步搭建开发与运行环境，并完成从源码到可执行文件的编译构建。由于 robotgo-flow 底层依赖 robotgo，而 robotgo 又包含 C 代码（通过 Cgo 桥接），因此编译环境的搭建是入门的第一道门槛，需要格外细心。

2.1 环境需求总览

在开始之前，先明确 robotgo-flow 对环境的完整要求：

其中，Go 与 GCC 是编译 Go CLI 的必备条件；.NET 只有在你需要 WPF 托盘应用时才需要安装。本章先聚焦于 CLI 的构建，WPF 部分会在第 15 章详细展开。

2.2 安装 Go

前往 Go 官方下载页面 下载 1.26 或更高版本的 Windows 安装包（.msi），按向导安装即可。安装完成后，打开 PowerShell 验证：

go version

若输出类似 go version go1.26.0 windows/amd64，说明 Go 已正确安装。Go 安装程序会自动配置 PATH，一般无需手动干预。

为什么需要 Go 1.26+？ robotgo-flow 的 go.mod 声明了较新的 Go 版本，并且使用了较新版本的语言特性与依赖库。使用过旧的 Go 版本可能导致编译失败。

2.3 安装 GCC（MinGW-w64）

robotgo 底层包含大量与操作系统交互的 C 代码（例如 GLFW、libpng 相关部分），编译时需要 GCC 工具链。robotgo-flow 官方推荐通过 MSYS2 来安装 MinGW-w64 版本的 GCC。

2.3.1 通过 winget 安装 MSYS2

在 PowerShell 中执行：

winget install MSYS2.MSYS2

若你的系统没有 winget，也可以从 MSYS2 官网 下载安装包手动安装。

2.3.2 安装编译工具链

安装完成后，打开 MSYS2 终端（从开始菜单启动），执行以下命令安装 GCC 与 zlib：

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-zlib

pacman 是 MSYS2 的包管理器。这条命令会安装 x86_64 版本的 MinGW-w64 GCC 编译器以及 zlib 压缩库（图像处理相关依赖需要）。

2.3.3 配置系统 PATH

安装好之后，需要把 MinGW-w64 的 bin 目录加入系统 PATH，这样 Go 在编译时才能找到 gcc：

C:\msys64\mingw64\bin

在「系统属性 → 环境变量 → 系统变量 → Path」中新增上述路径，然后重新打开 PowerShell（让新的 PATH 生效），验证：

gcc --version

若能输出 GCC 的版本信息（且是 x86_64 目标），说明工具链已就绪。

注意：一定要确保使用的是 mingw64 目录下的 GCC（x86_64 目标），而不是 MSYS2 的其他环境（如 ucrt64、clang64）。robotgo-flow 的构建脚本会校验 GCC 是否为 x86_64 MinGW-w64 目标。

2.4 获取源码

从 GitHub 获取 robotgo-flow 源码（假设你已配置好 git）：

git clone https://github.com/znlgis/robotgo-flow.git
cd robotgo-flow

项目的目录结构大致如下（简化版）：

robotgo-flow/
├── src/
│   ├── go/                 # Go 源码（CLI 与引擎）
│   │   ├── cmd/robotgo-flow/main.go
│   │   ├── internal/       # 各功能子包
│   │   ├── go.mod
│   │   └── go.sum
│   └── csharp/             # C# 源码（WPF 托盘应用）
│       ├── RobotgoFlow.Core/
│       ├── RobotgoFlow.Tray/
│       └── RobotgoFlow.Wpf.sln
└── scripts/
    └── build.ps1           # Go 构建脚本

2.5 编译 Go CLI

robotgo-flow 提供了 PowerShell 构建脚本 scripts/build.ps1，封装了编译细节。在仓库根目录执行：

# 优化输出（strip 掉调试信息，体积更小）
.\scripts\build.ps1

# 调试版本（保留符号，便于调试）
.\scripts\build.ps1 -NoStrip

2.5.1 首次编译耗时

重要提示：首次编译耗时约 4 分钟，因为需要编译 GLFW 的 C 源码。这是正常现象，请耐心等待。得益于 Go 的编译缓存，后续增量编译通常只需约 1 秒。

2.5.2 构建脚本做了什么

build.ps1 的核心流程大致分为三步：

1. 环境检查：验证 Go 版本 ≥ 1.26，验证 GCC 是 x86_64 MinGW-w64 目标；

2. 编译：默认执行类似下面的命令，生成静态链接的可执行文件：

   go build -v -ldflags="-s -w -extldflags '-static'" -o robotgo-flow.exe ./cmd/robotgo-flow/
   

   其中 -s -w 去除符号表与调试信息以减小体积，-extldflags '-static' 进行静态链接，让最终产物不依赖外部 DLL；

3. 静态链接校验与收尾：使用 objdump 检查产物是否残留 libgcc、libstdc++、libwinpthread、libpng 等动态依赖，最后报告产物体积与构建耗时。

构建脚本还支持若干参数：

2.5.3 版本号注入

main.go 中定义了 var Version = "dev"，可以在编译时通过 -ldflags "-X main.Version=1.2.3" 注入具体版本号。构建后可以用 robotgo-flow.exe version（或 -v / --version）查看版本。

2.6 编译 Go DLL（供 WPF 调用）

如果你打算让 WPF 托盘应用通过 DLL 模式直接调用 Go 引擎，需要额外构建 c-shared DLL：

# 构建 c-shared DLL
.\scripts\build.ps1 -Dll

# 调试版 DLL
.\scripts\build.ps1 -Dll -NoStrip

DLL 模式会编译 ./internal/ffi/ 包（其中定义了导出给 C 的函数，如 RobotgoInit、RobotgoExecute 等），产物为 robotgo-flow.dll。这部分内容会在第 15 章 WPF 集成时进一步说明。

2.7 编译 WPF 托盘应用（可选）

如果需要图形界面，先确保安装了 .NET 10 SDK（前往 .NET 下载页 获取），然后：

# 构建整个 C# 解决方案
cd src\csharp
dotnet build RobotgoFlow.Wpf.sln -c Release

# 或单独构建托盘项目
dotnet build RobotgoFlow.Tray/RobotgoFlow.Tray.csproj -c Release

编译输出中包含 robotgo-flow-tray.exe，即可直接运行的 WPF 桌面应用。

2.8 验证安装

完成 CLI 构建后，运行一个最简单的命令确认框架可用：

# 不带参数会显示帮助信息
.\robotgo-flow.exe

# 查看版本
.\robotgo-flow.exe version

若能正确显示帮助与版本，说明你的开发环境已经搭建完毕，可以进入下一章编写第一个工作流了。

2.9 常见编译问题

2.10 小结

本章我们完成了 robotgo-flow 的环境搭建与编译构建：安装 Go 1.26+、通过 MSYS2 安装 MinGW-w64 GCC 并配置 PATH、获取源码、使用 build.ps1 构建 CLI（以及可选的 DLL 与 WPF）。我们理解了首次编译耗时较长是编译 GLFW C 源码所致，也梳理了构建脚本的参数与常见编译问题的排查方法。下一章，我们将编写并运行第一个真正的自动化工作流。