RobotGo 跨平台桌面自动化完全指南：环境依赖、无 Cgo 纯 Go 构建与实战示例

RobotGo 跨平台桌面自动化完全指南环境依赖、无 Cgo 纯 Go 构建与实战示例【免费下载链接】robotgoRobotGo, Go Native cross-platform RPA, GUI automation, Auto test and Computer use vcaesar项目地址: https://gitcode.com/gh_mirrors/ro/robotgo本文以仓库 lang/README.de.md 为主线结合 robotgo.go、go.mod 及win、darwin、x11、wayland、libei各后端目录源码系统讲解 RobotGo 作为 Go 原生跨平台 RPA / GUI 自动化库的核心能力、各平台编译依赖、无 Cgo 纯 Go 构建方案以及鼠标、键盘、屏幕、位图、OpenCV、事件监听与窗口控制七大实战示例。读完本文你将能独立完成 RobotGo 在三平台的依赖安装、选择正确的构建标签并写出可运行的自动化脚本。一、RobotGo 是什么RobotGo项目名robotgo是一个Go 原生的跨平台系统自动化RPA库官方定位覆盖三大应用场景桌面自动化Desktop Automation程序化控制鼠标、键盘、读取屏幕内容自动化测试Auto Test驱动 GUI 应用完成回归与冒烟测试AI 计算机使用Computer Use作为 Agent 操作桌面环境的基础能力层。其核心能力包括鼠标控制与键盘模拟输入屏幕捕获、像素颜色读取、位图Bitmap查找进程管理与窗口句柄Window Handle操作全局事件监听鼠标/键盘 Hook图像识别集成 OpenCV 模板匹配与 SIFT 特征匹配。从平台支持看RobotGo 覆盖macOS、Windows、Linux三大桌面系统同时支持arm64 与 x86-amd64两种架构。从源码结构看默认路径通过 Cgo 调用系统原生 API见 robotgo.go 中的 C 指令darwin 链接 Cocoa/IOKit 框架linux 链接-lX11 -lXtstwindows 链接-lgdi32 -luser32而从 v0.42 起项目新增了纯 Go无 Cgo后端可做到零系统依赖编译详见第五节。二、环境准备各平台依赖清单RobotGo 默认构建路径依赖 Cgo因此安装前必须确保Golang 与 GCC均已正确安装。下面按平台拆分依赖清单内容直接来自 lang/README.de.md 的 Requirements 章节。2.1 所有平台ALLGolang GCC2.2 macOS安装 Go 与 Xcode 命令行工具brew install goxcode-select --install注意使用默认 Cgo/Quartz 后端时Xcode Command Line Tools 是必需的。macOS 的隐私权限是另一个关键前提。使用屏幕捕获与辅助功能前需要在系统设置中添加授权Systemeinstellungen Datenschutz Sicherheit Bedienungshilfen, Bildschirm- Systemaudioaufnahme系统设置 隐私与安全性 辅助功能、屏幕录制与系统音频录制只有勾选屏幕录制权限CaptureScreen系列接口才能读到画面只有授予辅助功能权限鼠标键盘注入才会生效。2.3 Windows通过 winget 安装 Gowinget install Golang.goCgo 编译需要 GCC 工具链二选一llvm-mingw推荐UCRT 运行时winget install MartinStorsjo.LLVM-MinGW.UCRTMingw-w64 / WinLibswinget install BrechtSanders.WinLibs.POSIX.UCRT也可以手动下载 Mingw-w64然后将C:\mingw64\bin加入系统环境变量Path使 GCC 可从命令行直接调用。提示若使用 Mingw-w64 之外的其他 GCC如基于 MSVCRT 的发行版在配合 vcaesar/bitmap 做位图处理时可能需要自行编译libpng。2.4 LinuxX11 通用除 GCC 外X11 后端还需要以下系统库GCC X11 与 XTest 扩展Xtst 库 剪贴板: xsel xclip 位图: libpng仅 bitmap 使用 事件/gohook: xcb, xkb, libxkbcommon仅 hook 使用Ubuntu / Debian# sudo apt install golang sudo snap install go --classic # gcc sudo apt install gcc libc6-dev # x11 sudo apt install libx11-dev xorg-dev libxtst-dev # Clipboard sudo apt install xsel xclip # Bitmap sudo apt install libpng-dev # GoHook sudo apt install xcb libxcb-xkb-dev x11-xkb-utils libx11-xcb-dev libxkbcommon-x11-dev libxkbcommon-devFedora# x11 sudo dnf install libXtst-devel # Clipboard sudo dnf install xsel xclip # Bitmap sudo dnf install libpng-devel # GoHook sudo dnf install libxkbcommon-devel libxkbcommon-x11-devel xkbcomp-devel xorg-x11-xkb-utils-devel ( Fedora 34)2.5 Waylandwlroots 合成器Wayland 后端是纯 Go 实现无 Cgo因此不需要任何系统 C 库。但它要求运行在支持以下协议的wlroots 系合成器上如 Sway、Hyprland、Wayfire 等zwlr_virtual_pointer_v1 鼠标控制 zwp_virtual_keyboard_v1 键盘控制 zwlr_screencopy_v1 屏幕捕获 zwlr_foreign_toplevel_management_v1 窗口管理GNOME 与 KDE 原生不支持上述协议这正是 libei 后端存在的意义。仓库中对应实现位于 wayland/ 目录其版本串v0.1.0-wayland与Point/Size等纯 Go 数据结构见 wayland/robotgo.go。2.6 libeiGNOME / KDE 桌面libei 后端同样是纯 Go 实现无 Cgo。它通过 freedesktop 的xdg-desktop-portal的RemoteDesktop 接口注入输入因此能在 GNOME / KDE 上工作这正是 wlroots Wayland 后端做不到的。需要安装xdg-desktop-portal Portal D-Bus 服务 xdg-desktop-portal-gnome / -kde 当前桌面的 Portal 后端限制libei 后端只处理鼠标与键盘输入屏幕捕获与窗口管理接口会返回ErrNotSupported。三、安装与更新3.1 安装在 Go 1.11已启用 Go Modules的项目中直接导入即可import github.com/go-vgo/robotgo不使用模块管理时用go get安装go get github.com/go-vgo/robotgo若遇到png.h: No such file or directory编译错误说明系统中缺少 libpng 头文件Linux 场景回到第二节安装libpng-dev/libpng-dev即可解决。3.2 更新go get -u github.com/go-vgo/robotgo历史坑点提醒Go 1.10.x 时代曾存在 C 文件编译缓存问题以及go mod vendor相关的已知缺陷升级 Go 到较新版本即可规避。当前仓库 go.mod 要求go 1.25.0并依赖ebitengine/puregomac 后端纯 Go 加载 Quartz 用、jezek/xgbX11 纯 Go 协议、vcaesar/go-waylandWayland 协议、vcaesar/keycode键码映射等模块从依赖侧印证了纯 Go 后端的实现路径。四、无 Cgo 纯 Go 构建Cgo-free Builds这是本文档最核心、也最值得开发者关注的能力RobotGo 为Windows、macOS、X11、Wayland、libei提供了实验性的纯 Go 后端。它们暴露完全相同的robotgoAPI——你的业务代码一行都不用改只需切换一个构建标签build tag并且可以在CGO_ENABLED0下交叉编译无需 GCC、MinGW、Xcode 或 X11 头文件。4.1 后端与构建标签对照表后端Build-TagGo 包Windows无 Cgowingithub.com/go-vgo/robotgo/winmacOSQuartz 经 purego 动态加载macgithub.com/go-vgo/robotgo/darwinX11Linux纯 Go X 协议x11github.com/go-vgo/robotgo/x11WaylandLinuxwlrootswaylandgithub.com/go-vgo/robotgo/waylandlibeiLinuxGNOME/KDE Portallibeigithub.com/go-vgo/robotgo/libei纯 Go 标准后端全平台purego自动选择上述mac/win/wayland4.2 构建命令速查# 纯 Go 标准后端一个标签覆盖所有目标平台 # macOS - mac, Windows - win, Linux - wayland可用 x11/libei 组合覆盖默认选择 go build -tags purego ./... CGO_ENABLED0 GOOSlinux GOARCHamd64 go build -tags purego,x11 ./... # Windows无 Cgo / 无 MinGW CGO_ENABLED0 GOOSwindows GOARCHamd64 go build -tags win ./... # macOS运行时经 purego 动态加载 Quartz/CoreGraphics无需 Xcode CGO_ENABLED0 GOOSdarwin GOARCHarm64 go build -tags mac ./... # X11纯 Go X 协议XTEST——无需 X11 头文件 CGO_ENABLED0 GOOSlinux GOARCHamd64 go build -tags x11 ./... # Waylandwlroots 合成器Sway、Hyprland、Wayfire ... CGO_ENABLED0 GOOSlinux GOARCHamd64 go build -tags wayland ./... # libeiGNOME/KDE 经 xdg-desktop-portal RemoteDesktop CGO_ENABLED0 GOOSlinux GOARCHamd64 go build -tags libei ./...4.3 标签语义详解win排除默认的 Cgo/Win32 后端调用转发到纯 Go 包 win/mac排除默认的 Cgo/Quartz 后端调用转发到纯 Go 包 darwin/窗口管理返回ErrNotSupportedx11排除 Cgo/X11 后端调用转发到纯 Go 包 x11/wayland排除 Cgo/X11 后端调用转发到纯 Go 包 wayland/libei同时排除 Cgo/X11 与 wlroots Wayland 后端调用转发到纯 Go 包 libei/purego跨平台缩写标签。在所有平台排除 Cgo 后端并选择目标系统的纯 Go 标准后端——macOS 选mac、Windows 选win、Linux 选wayland在 Linux 上可组合x11或libei如-tags purego,libei来切换到其他纯 Go 后端。4.4 源码级佐证这套标签机制在源码中有直接体现。默认 Cgo 后端源文件如 robotgo.go首行即声明//go:build !wayland !win !libei !mac !x11 !purego即只有未指定任何纯 Go 标签时才编译 Cgo 版本。根目录下的 x11_n.go、wayland_n.go、windows_n.go 等文件以及各后端目录win/、darwin/、x11/、wayland/、libei/下的robotgo.go构成了同一 API、多后端实现的分发层。另外robotgo_fn_v1.go 中还保留了大量兼容旧版命名的函数如MoveMouse转发到Move、GetMousePos转发到Location保证老代码渐进迁移。五、实战示例Examples以下七个示例完整摘自 lang/README.de.md可直接复制运行仓库内对应源码位于 examples/ 目录。5.1 鼠标控制对应仓库文件 examples/mouse/main.go。展示了绝对移动、相对移动、平滑移动、滚动、拖拽、点击与按键状态切换package main import ( fmt github.com/go-vgo/robotgo ) func main() { robotgo.MouseSleep 300 robotgo.Move(100, 100) fmt.Println(robotgo.Location()) robotgo.Move(100, -200) // multi screen supported robotgo.MoveSmooth(120, -150) fmt.Println(robotgo.Location()) robotgo.ScrollDir(10, up) robotgo.ScrollDir(20, right) robotgo.Scroll(0, -10) robotgo.Scroll(100, 0) robotgo.MilliSleep(100) robotgo.ScrollSmooth(-10, 6) // robotgo.ScrollRelative(10, -100) robotgo.Move(10, 20) robotgo.MoveRelative(0, -10) robotgo.DragSmooth(10, 10) robotgo.Click(wheelRight) robotgo.Click(left, true) robotgo.MoveSmooth(100, 200, 1.0, 10.0) robotgo.Toggle(left) robotgo.Toggle(left, up) }从源码看robotgo.goMove(x, y)内部先做缩放换算Windows 下会乘以 DPI 缩放因子随后调用 C 层moveMouse并休眠MouseSleep毫秒MoveSmooth(x, y, low, high, mouseDelay)的默认低/高速度为1.0/3.0实现类人轨迹移动DragSmooth则是按下左键 → 平滑移动 → 释放左键的组合。5.2 键盘输入对应仓库文件 examples/key/main.go。覆盖字符串输入含 Unicode 日文、按键敲击、组合键、按键状态与剪贴板读写package main import ( fmt github.com/go-vgo/robotgo ) func main() { robotgo.Type(Hello World) robotgo.Type(だんしゃり, 0, 1) // robotgo.Type(テストする) robotgo.Type(Hi, Seattle space needle, Golden gate bridge, One world trade center.) robotgo.Type(Hi galaxy, hi stars, hi MT.Rainier, hi sea. こんにちは世界.) robotgo.Sleep(1) // ustr : uint32(robotgo.CharCodeAt(Test, 0)) // robotgo.UnicodeType(ustr) robotgo.KeySleep 100 robotgo.KeyTap(enter) // robotgo.Type(en) robotgo.KeyTap(i, alt, cmd) arr : []string{alt, cmd} robotgo.KeyTap(i, arr) robotgo.MilliSleep(100) robotgo.KeyToggle(a) robotgo.KeyToggle(a, up) robotgo.WriteAll(Test) text, err : robotgo.ReadAll() if err nil { fmt.Println(text) } }注意robotgo.KeyTap(i, alt, cmd)中组合键以变参传入也可用字符串切片[]string{alt, cmd}。完整的键名对照表见 docs/keys.md。5.3 屏幕捕获对应仓库文件 examples/screen/main.go。展示鼠标位置、像素颜色、屏幕尺寸、区域截图、按显示器遍历截图与 JPEG 保存package main import ( fmt strconv github.com/go-vgo/robotgo github.com/vcaesar/imgo ) func main() { x, y : robotgo.Location() fmt.Println(pos: , x, y) color : robotgo.GetPixelColor(100, 200) fmt.Println(color---- , color) sx, sy : robotgo.GetScreenSize() fmt.Println(get screen size: , sx, sy) bit : robotgo.CaptureScreen(10, 10, 30, 30) defer robotgo.FreeBitmap(bit) img : robotgo.ToImage(bit) imgo.Save(test.png, img) num : robotgo.DisplaysNum() for i : 0; i num; i { robotgo.DisplayID i img1, _ : robotgo.CaptureImg() path1 : save_ strconv.Itoa(i) robotgo.Save(img1, path1.png) robotgo.SaveJpeg(img1, path1.jpeg, 50) img2, _ : robotgo.CaptureImg(10, 10, 20, 20) robotgo.Save(img2, test_strconv.Itoa(i).png) x, y, w, h : robotgo.GetDisplayBounds(i) img3, err : robotgo.CaptureImg(x, y, w, h) fmt.Println(Capture error: , err) robotgo.Save(img3, path1_1.png) } }源码细节robotgo.goCaptureScreen(x, y, w, h)不传参数时默认截取主屏幕全屏第 5 个可变参数可指定displayIdDisplayID全局变量为-1时表示主屏。截取返回的 C 位图必须用defer robotgo.FreeBitmap(bit)释放避免内存泄漏。5.4 位图查找Bitmap位图查找依赖 vcaesar/bitmap 包用于在屏幕截图中定位目标图像坐标package main import ( fmt github.com/go-vgo/robotgo github.com/vcaesar/bitmap ) func main() { bit : robotgo.CaptureScreen(10, 20, 30, 40) // use defer robotgo.FreeBitmap(bit) to free the bitmap defer robotgo.FreeBitmap(bit) fmt.Println(bitmap..., bit) img : robotgo.ToImage(bit) // robotgo.SavePng(img, test_1.png) robotgo.Save(img, test_1.png) bit2 : robotgo.ToCBitmap(robotgo.ImgToBitmap(img)) fx, fy : bitmap.Find(bit2) fmt.Println(FindBitmap------ , fx, fy) robotgo.Move(fx, fy) arr : bitmap.FindAll(bit2) fmt.Println(Find all bitmap: , arr) fx, fy bitmap.Find(bit) fmt.Println(FindBitmap------ , fx, fy) bitmap.Save(bit, test.png) }典型的找图 → 移鼠标 → 点击闭环先用CaptureScreen截取区域bitmap.Find返回命中坐标(fx, fy)随后robotgo.Move(fx, fy)定位过去。bitmap.FindAll则返回全部匹配点数组。5.5 OpenCV 图像识别图像识别示例使用 vcaesar/gcv基于 OpenCV 的 Go 封装提供模板匹配Template Matching与 SIFT 特征匹配两种方式package main import ( fmt math/rand github.com/go-vgo/robotgo github.com/vcaesar/gcv github.com/vcaesar/bitmap ) func main() { opencv() } func opencv() { name : test.png name1 : test_001.png robotgo.SaveCapture(name1, 10, 10, 30, 30) robotgo.SaveCapture(name) fmt.Print(gcv find image: ) fmt.Println(gcv.FindImgFile(name1, name)) fmt.Println(gcv.FindAllImgFile(name1, name)) bit : bitmap.Open(name1) defer robotgo.FreeBitmap(bit) fmt.Print(find bitmap: ) fmt.Println(bitmap.Find(bit)) // bit0 : robotgo.CaptureScreen() // img : robotgo.ToImage(bit0) // bit1 : robotgo.CaptureScreen(10, 10, 30, 30) // img1 : robotgo.ToImage(bit1) // defer robotgo.FreeBitmapArr(bit0, bit1) img, _ : robotgo.CaptureImg() img1, _ : robotgo.CaptureImg(10, 10, 30, 30) fmt.Print(gcv find image: ) fmt.Println(gcv.FindImg(img1, img)) fmt.Println() res : gcv.FindAllImg(img1, img) fmt.Println(res[0].TopLeft.Y, res[0].Rects.TopLeft.X, res) x, y : res[0].TopLeft.X, res[0].TopLeft.Y robotgo.Move(x, y-rand.Intn(5)) robotgo.MilliSleep(100) robotgo.Click() res gcv.FindAll(img1, img) // use find template and sift fmt.Println(find all: , res) res1 : gcv.Find(img1, img) fmt.Println(find: , res1) img2, _, _ : robotgo.DecodeImg(test_001.png) x, y gcv.FindX(img2, img) fmt.Println(x, y) }识别结果res[0].TopLeft给出目标左上角坐标配合robotgo.Moverobotgo.Click即可实现看见什么点什么的 Computer Use 流程。5.6 全局事件监听Event / Hook事件监听基于 robotn/gohook 包支持注册快捷键回调、底层事件流与单次按键阻塞等待三种模式package main import ( fmt // github.com/go-vgo/robotgo hook github.com/robotn/gohook ) func main() { add() low() event() } func add() { fmt.Println(--- Please press ctrl shift q to stop hook ---) hook.Register(hook.KeyDown, []string{q, ctrl, shift}, func(e hook.Event) { fmt.Println(ctrl-shift-q) hook.End() }) fmt.Println(--- Please press w---) hook.Register(hook.KeyDown, []string{w}, func(e hook.Event) { fmt.Println(w) }) s : hook.Start() -hook.Process(s) } func low() { evChan : hook.Start() defer hook.End() for ev : range evChan { fmt.Println(hook: , ev) } } func event() { ok : hook.AddEvents(q, ctrl, shift) if ok { fmt.Println(add events...) } keve : hook.AddEvent(k) if keve { fmt.Println(you press... , k) } mleft : hook.AddEvent(mleft) if mleft { fmt.Println(you press... , mouse left button) } }在 Linux 上使用事件功能时需要第二节中提到的xcb / xkb / libxkbcommon依赖对应sudo apt install xcb libxcb-xkb-dev x11-xkb-utils libx11-xcb-dev libxkbcommon-x11-dev libxkbcommon-dev。5.7 窗口与进程管理对应仓库文件 examples/window/main.go。覆盖按进程名查 PID、向指定 PID 注入输入、激活/杀死进程、进程存在性检测、弹窗与标题读取package main import ( fmt github.com/go-vgo/robotgo ) func main() { fpid, err : robotgo.FindIds(Google) if err nil { fmt.Println(pids... , fpid) if len(fpid) 0 { robotgo.Type(Hi galaxy!, fpid[0]) robotgo.KeyTap(a, fpid[0], cmd) robotgo.KeyToggle(a, fpid[0]) robotgo.KeyToggle(a, fpid[0], up) robotgo.ActivePid(fpid[0]) robotgo.Kill(fpid[0]) } } robotgo.ActiveName(chrome) isExist, err : robotgo.PidExists(100) if err nil isExist { fmt.Println(pid exists is, isExist) robotgo.Kill(100) } abool : robotgo.Alert(test, robotgo) if abool { fmt.Println(ok , ok) } title : robotgo.GetTitle() fmt.Println(title , title) }注意robotgo.Type(str, pid)、robotgo.KeyTap(key, pid, modifiers...)支持把输入定向到指定 PID 的窗口robotgo.ActivePid(pid)/robotgo.ActiveName(name)用于窗口激活。相关实现GetTitle、ActivePid、ActiveName等位于 robotgo.go 及 window/ 目录。六、深入默认 Cgo 后端与纯 Go 后端的取舍结合源码可以更清晰地理解两套体系的分工默认后端Cgo在 robotgo.go 中通过#cgo指令声明平台依赖——darwin 链接 Cocoa、CoreFoundation、IOKit、Carbon、OpenGLmacOS 14.5 额外链接 ScreenCaptureKitlinux 链接-lm -lX11 -lXtstwindows 链接-lgdi32 -luser32。功能最完整但要求系统装有对应开发库与编译器。纯 Go 后端通过构建标签把调用转发到 win/、darwin/、x11/、wayland/、libei/ 五个独立包。它们利用puregomacOS 动态加载 Quartz、jezek/xgbX11 协议、go-waylandwlroots 协议与xdg-desktop-portallibei实现等价能力从而支持CGO_ENABLED0交叉编译。如何选择场景推荐功能最全、本机开发调试默认 Cgo 后端不传标签追求零依赖部署、交叉编译-tags puregoLinux 上可purego,x11/purego,libei切换Linux 跑在 Sway/Hyprland 等 wlroots 合成器-tags waylandLinux 跑在 GNOME/KDE-tags libei仅输入无截图/窗口管理Windows 无 MinGW 环境-tags winmacOS 无 Xcode 环境-tags mac窗口管理不可用需要留意的是纯 Go 后端仍标注为实验性例如mac与libei后端的窗口管理均返回ErrNotSupportedWayland 后端依赖合成器协议支持程度跨显示器场景可能受限。生产使用前请针对目标环境做充分验证。七、路线图与许可官方规划见 lang/README.de.md 的 Plans 章节包括将部分 C 代码如 x11、windows重写为 Go、更好的多屏支持、Wayland 支持、窗口句柄更新以及尝试支持 Android 与 iOS。其中 Wayland 支持已在本文介绍的后端体系中落地。许可证方面RobotGo 主要以Apache License 2.0分发部分组件采用 BSD 类许可详见仓库 LICENSE。完整 API 文档可参考 docs/doc.md官方标注已过时未更新以 GoDoc。结语从环境依赖、安装更新到无 Cgo 纯 Go 构建、再到鼠标键盘屏幕窗口的七类实战示例RobotGo 已经形成一套一套 API、多后端分发的完整桌面自动化方案默认 Cgo 路径保证功能完整purego/win/mac/x11/wayland/libei标签保证部署灵活性。结合本文给出的构建命令与源码级原理你可以在 macOS、Windows、LinuxX11/Wayland/GNOME/KDE上快速落地 RPA、GUI 自动化测试与 Computer Use 应用。【免费下载链接】robotgoRobotGo, Go Native cross-platform RPA, GUI automation, Auto test and Computer use vcaesar项目地址: https://gitcode.com/gh_mirrors/ro/robotgo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考