PyAutoGUI 技能
使用 PyAutoGUI 进行桌面自动化，实现鼠标、键盘和屏幕控制。
何时使用
✅ 在以下情况下使用此技能：
- - 自动化重复的鼠标/键盘任务
- GUI 测试和交互
- 桌面应用的点击/输入序列
- 为自动化截取屏幕截图
- 在屏幕上定位简单图像
- 将鼠标移动到特定坐标
- 键盘快捷键和热键
- 表单填写自动化
❌ 在以下情况下不要使用此技能：
- - 网页浏览器自动化 → 使用 Playwright 或 Selenium
- 移动应用自动化 → 使用 Appium
- 复杂图像识别 → 使用 OpenCV/ML 模型
- 无障碍自动化 → 使用平台原生 API
- 高速自动化 → PyAutoGUI 有安全延迟
安全第一
PyAutoGUI 包含安全防护机制。切勿禁用它们：
python
安全防护：将鼠标移动到 (0,0) 位置可中止操作
pyautogui.FAILSAFE = True # 请保持此设置！
添加操作间隔以确保安全
pyautogui.PAUSE = 0.5 # 操作之间的秒数
快速入门
python
import pyautogui
基本移动
pyautogui.moveTo(100, 100, duration=0.5)
pyautogui.click()
输入文字
pyautogui.write(Hello world!, interval=0.1)
键盘快捷键
pyautogui.hotkey(ctrl, c) # 复制
pyautogui.hotkey(ctrl, v) # 粘贴
核心操作
鼠标控制
python
import pyautogui
获取屏幕尺寸
width, height = pyautogui.size()
获取当前位置
x, y = pyautogui.position()
移动鼠标（持续时间以秒为单位）
pyautogui.moveTo(100, 100, duration=0.5)
pyautogui.moveRel(0, 50, duration=0.3) # 相对移动
点击操作
pyautogui.click() # 在当前位置左键单击
pyautogui.click(x=100, y=100)
pyautogui.rightClick()
pyautogui.doubleClick()
pyautogui.dragTo(200, 200, duration=0.5)
按钮控制
pyautogui.mouseDown()
pyautogui.mouseUp()
键盘控制
python
import pyautogui
输入文本
pyautogui.write(Hello!, interval=0.1) # 字符输入间隔
特殊按键
pyautogui.press(enter)
pyautogui.press([up, up, down, down])
按键保持
pyautogui.keyDown(shift)
pyautogui.write(CAPS)
pyautogui.keyUp(shift)
热键（快捷键）
pyautogui.hotkey(ctrl, s) # 保存
pyautogui.hotkey(ctrl, shift, n) # 新建文件夹（Windows）
pyautogui.hotkey(command, space) # 聚焦搜索（Mac）
特殊按键名称
修饰键
ctrl, shift, alt, command（Mac）, win（Windows）
导航键
enter, tab, space, escape, backspace, delete
up, down, left, right
home, end, pageup, pagedown
功能键
f1 到 f12
其他
capslock, numlock, scrolllock
printscreen, pause
屏幕截图
python
import pyautogui
全屏截图
screenshot = pyautogui.screenshot()
screenshot.save(screen.png)
区域截图
screenshot = pyautogui.screenshot(region=(0, 0, 300, 400))
直接保存到文件
pyautogui.screenshot(saved.png)
图像定位
python
import pyautogui
在屏幕上查找图像
location = pyautogui.locateOnScreen(button.png, confidence=0.8)
if location:
x, y = pyautogui.center(location)
pyautogui.click(x, y)
查找所有匹配项
locations = pyautogui.locateAllOnScreen(icon.png, confidence=0.8)
获取中心点
center = pyautogui.center(location) # 返回 (x, y)
注意： confidence 参数需要 Pillow 库。取值范围 0-1，值越高匹配越严格。
常见工作流程
表单填写
python
import pyautogui
import time
pyautogui.PAUSE = 0.5
点击第一个字段
pyautogui.click(x=100, y=200)
pyautogui.write(John Doe)
Tab 键切换到下一个字段
pyautogui.press(tab)
pyautogui.write(john@example.com)
提交
pyautogui.press(enter)
窗口管理（依赖操作系统）
python
import pyautogui
最小化（Windows）
pyautogui.hotkey(win, down)
最大化
pyautogui.hotkey(win, up)
切换应用（Alt+Tab）
pyautogui.hotkey(alt, tab)
关闭窗口
pyautogui.hotkey(alt, f4) # Windows
pyautogui.hotkey(command, w) # Mac
截图+点击模式
python
import pyautogui
定位并点击按钮
button = pyautogui.locateOnScreen(submit_btn.png, confidence=0.9)
if button:
x, y = pyautogui.center(button)
pyautogui.click(x, y)
else:
print(未找到按钮！)
配置
时间与安全
python
import pyautogui
所有操作之间的暂停时间（秒）
pyautogui.PAUSE = 0.5
安全防护（移动到角落停止）
pyautogui.FAILSAFE = True
locateOnScreen 的超时时间（秒）
pyautogui.locateOnScreen(img.png, timeout=10)
平台检测
python
import platform
system = platform.system()
if system == Darwin:
# macOS 快捷键
cmd = command
elif system == Windows:
cmd = win
else:
cmd = ctrl
脚本
查看 scripts/ 目录获取可复用的自动化脚本：
- - scripts/clickimage.py - 定位并点击图像
- scripts/typesequence.py - 输入文本序列
- scripts/take_screenshot.py - 捕获屏幕区域
故障排除
PyAutoGUI 无法工作
- 1. 权限问题（macOS）：
- 系统设置 → 隐私与安全性 → 辅助功能
- 将终端/Python 添加到允许的应用列表
- 2. 权限问题（Windows）：
- 必要时以管理员身份运行
- 3. Linux 系统：
bash
sudo apt-get install python3-dev python3-pip
sudo apt-get install scrot python3-tk python3-dev
pip3 install pyautogui
图像未找到
- - 检查图像路径（使用绝对路径）
- 调整 confidence 值（尝试 0.7-0.9）
- 确保截图与当前屏幕分辨率匹配
- 图像比例可能不同（视网膜显示屏）
速度太慢
python
减少暂停时间（但保持安全！）
pyautogui.PAUSE = 0.1
移除持续时间以实现即时移动
pyautogui.moveTo(100, 100) # 无持续时间 = 即时移动
速度太快/不可靠
python
增加暂停时间
pyautogui.PAUSE = 1.0
添加显式等待
import time
time.sleep(2) # 等待 UI 加载
最佳实践
- 1. 始终先进行视觉测试 - 观察自动化运行过程
- 使用延迟 - 给 UI 响应时间
- 添加错误处理 - 检查元素是否存在
- 记录操作日志 - 出现问题时便于调试
- 谨慎使用图像 - 分辨率变化会破坏图像匹配
- 尊重安全防护机制 - 切勿禁用它
