什么是 PyAutoGUI？
PyAutoGUI 是一个 Python 的第三方库，它提供了一组简单易用的函数，可以模拟鼠标的移动、点击、拖拽以及键盘的按键输入，这使得编写自动化脚本、测试 GUI 应用程序、制作游戏辅助工具等任务变得非常简单。
（图片来源网络，侵删）
安装 PyAutoGUI
你需要安装这个库，打开你的终端或命令提示符,运行以下命令：
pip install pyautogui
为了获得更好的体验，建议同时安装 opencv-python 和 numpy，因为 pyautogui 的图像识别功能依赖它们。
pip install opencv-python numpy
安全措施：防呆设计
pyautogui 有一个非常棒的安全特性：失败安全机制。
- 如果你的鼠标指针移动到屏幕的四个角落的任何一个，
pyautogui会抛出一个pyautogui.FailSafeException异常,从而终止你的脚本。 - 这个功能是为了防止脚本失控，导致鼠标和键盘在屏幕上无休止地乱动,让你无法手动干预。
如何使用：
默认情况下，这个机制是开启的，你可以通过 pyautogui.FAILSAFE = False 来禁用它，但强烈不建议在生产环境中禁用它。
（图片来源网络，侵删）
import pyautogui # 禁用失败安全机制（仅在绝对必要时使用） pyautogui.FAILSAFE = False
核心功能详解
1 屏幕和分辨率操作
在开始控制鼠标之前,了解屏幕的尺寸和获取屏幕截图是非常有用的。
import pyautogui
import time
# 1. 获取屏幕尺寸
screen_width, screen_height = pyautogui.size()
print(f"屏幕尺寸: {screen_width} x {screen_height}")
# 2. 获取当前鼠标位置
current_x, current_y = pyautogui.position()
print(f"当前鼠标位置: ({current_x}, {current_y})")
# 3. 获取屏幕截图
# screenshot() 方法会返回一个 Image 对象 (来自 Pillow 库)
screenshot = pyautogui.screenshot()
# 可以保存截图
screenshot.save("screenshot.png")
# 4. 屏幕上的像素颜色
pixel_color = pyautogui.pixel(100, 200)
print(f"(100, 200) 坐标的像素颜色: {pixel_color}")
# 你也可以用颜色来定位
# 查找屏幕上所有颜色为 (255, 0, 0) (红色) 的像素位置
# red_pixels = list(pyautogui.imageall('red')) # 这种方法效率不高
# 更高效的方法是结合截图和图像处理库
2 鼠标控制
这是 pyautogui 最核心的功能之一。
import pyautogui import time # 添加一个延迟，让你有时间把鼠标移到安全区之外 time.sleep(5) # --- 鼠标移动 --- # 1. 移动鼠标到绝对坐标 (x, y) pyautogui.moveTo(100, 200, duration=1.0) # 在1秒内平滑移动到 (100, 200) # 2. 从当前位置相对移动 pyautogui.moveRel(50, 0, duration=0.5) # 向右移动50像素 pyautogui.moveRel(0, -30, duration=0.5) # 向上移动30像素 # --- 鼠标点击 --- # 1. 点击左键 pyautogui.click() # 默认在当前位置左键单击 # 2. 在指定位置点击 pyautogui.click(x=500, y=300, button='left') # 3. 右键点击 pyautogui.click(button='right') # 4. 双击 pyautogui.doubleClick() # 5. 三击 pyautogui.tripleClick() # --- 鼠标拖拽 --- # 1. 按下鼠标 -> 移动 -> 释放 pyautogui.dragTo(700, 400, duration=2, button='left') # 拖到 (700, 400) pyautogui.dragRel(100, 50, duration=1, button='left') # 从当前位置向右下拖 # --- 其他鼠标操作 --- # 1. 按下鼠标（不释放） pyautogui.mouseDown() # 2. 释放鼠标 pyautogui.mouseUp() # 3. 滚动鼠标滚轮 # 正数向上滚动，负数向下滚动 pyautogui.scroll(10) # 向上滚动10个单位 pyautogui.scroll(-20) # 向下滚动20个单位
3 键盘控制
除了鼠标，pyautogui 也能模拟键盘输入。
import pyautogui
import time
time.sleep(3)
# --- 按键输入 ---
# 1. 输入字符串
pyautogui.write('Hello, PyAutoGUI!', interval=0.1) # 每个字符间隔0.1秒
# 2. 按下单个特殊键
pyautogui.press('enter') # 按下回车键
pyautogui.press('esc') # 按下ESC键
pyautogui.press('f1') # 按下F1键
# --- 组合键 ---
# 1. 按住 -> 输入 -> 释放
pyautogui.hotkey('ctrl', 'c') # 模拟 Ctrl+C
pyautogui.hotkey('ctrl', 'v') # 模拟 Ctrl+V
pyautogui.hotkey('alt', 'f4') # 模拟 Alt+F4
# 2. 更精细的组合键控制
pyautogui.keyDown('shift') # 按下 Shift 键
pyautogui.write('hello') # 此时输入的是 'HELLO'
pyautogui.keyUp('shift') # 释放 Shift 键
# --- 特殊键的字符串表示 ---
# 'ctrl', 'alt', 'shift', 'win', 'command' (Mac)
# 'backspace', 'tab', 'enter', 'shift', 'ctrl', 'alt', 'pause', 'capslock', 'esc', 'pageup', 'pagedown', 'end', 'home', 'left', 'up', 'right', 'down', 'insert', 'delete', 'lwin', 'rwin', 'apps', 'sleep'
4 图像识别与自动化
这是 pyautogui 最强大的功能之一，你可以截取一个按钮或图标的图像，然后让 pyautogui 在屏幕上查找这个图像，如果找到了,就在它的中心位置进行点击。
（图片来源网络，侵删）
准备工作：
- 打开你想要自动化的应用程序（例如记事本）。
- 使用截图工具截取你想要定位的目标（文件”菜单按钮），保存为
target.png。
Python 脚本示例：
import pyautogui
import time
# 给用户一些时间来切换窗口
print("请在5秒内切换到目标窗口...")
time.sleep(5)
# --- 在屏幕上查找图像 ---
try:
# locateOnScreen() 会返回一个 (left, top, width, height) 的元组
# 如果找不到，会抛出 ImageNotFoundException 异常
target_location = pyautogui.locateOnScreen('target.png')
if target_location:
print(f"找到目标！位置: {target_location}")
# 获取目标区域的中心点坐标
target_center = pyautogui.center(target_location)
print(f"目标中心点坐标: {target_center}")
# 移动鼠标到中心点并点击
pyautogui.moveTo(target_center, duration=0.5)
pyautogui.click()
print("点击完成！")
else:
print("未在屏幕上找到目标图像。")
except pyautogui.ImageNotFoundException:
print("错误：未找到目标图像！请确保 'target.png' 在正确的路径下，并且屏幕上可见该图像。")
except Exception as e:
print(f"发生未知错误: {e}")
图像识别的高级用法：
locateAllOnScreen(): 查找屏幕上所有匹配的图像,返回一个生成器。confidence参数 (重要！):pyautogui版本 0.9.53 之后引入了基于 OpenCV 的高精度匹配，你可以设置一个置信度阈值（0到1之间，默认0.9）来允许一定程度的颜色差异。
# 使用置信度参数，允许10%的差异
try:
# 在一个区域内查找
region = (0, 0, 1920, 1080) # (left, top, width, height)
target_location = pyautogui.locateOnScreen('target.png', region=region, confidence=0.8)
# 或者查找所有匹配项
all_targets = list(pyautogui.locateAllOnScreen('target.png', confidence=0.8))
print(f"找到了 {len(all_targets)} 个目标。")
except pyautogui.ImageNotFoundException:
print("未找到目标图像。")
完整示例：自动打开记事本并输入文本
这个示例结合了前面讲到的多种功能。
import pyautogui
import subprocess
import time
import sys
# 确保失败安全是开启的
pyautogui.FAILSAFE = True
def open_notepad():
"""打开记事本"""
try:
# Windows系统
subprocess.Popen(['notepad.exe'])
print("已启动记事本...")
except FileNotFoundError:
print("错误：找不到 notepad.exe，请确保您在 Windows 系统上运行。")
sys.exit(1)
time.sleep(2) # 等待记事本启动
def automate_typing():
"""自动化输入"""
print("开始自动化输入...")
# 1. 点击记事本窗口（假设窗口在左上角）
pyautogui.click(x=50, y=50)
# 2. 输入标题
pyautogui.write('PyAutoGUI 自动化测试', interval=0.05)
# 3. 按回车换行
pyautogui.press('enter')
pyautogui.press('enter')
# 4. 输入正文
pyautogui.write('这是一个由 Python 脚本自动生成的文本。', interval=0.05)
# 5. 按下 Ctrl+S 保存
time.sleep(1)
pyautogui.hotkey('ctrl', 's')
# 6. 在保存对话框中输入文件名并保存
time.sleep(1)
pyautogui.write('auto_generated_note.txt', interval=0.1)
pyautogui.press('enter')
print("自动化任务完成！")
if __name__ == "__main__":
print("脚本将在3秒后开始...")
time.sleep(3)
open_notepad()
automate_typing()
print("所有操作已完成。")
最佳实践和注意事项
- 添加延迟: 在自动化脚本中，
time.sleep()是你的好朋友，计算机和应用程序需要时间来响应，在点击、输入或窗口切换后添加短暂的延迟,可以大大提高脚本的稳定性。 - 使用相对坐标: 如果可能，尽量使用相对移动 (
moveRel) 和相对拖拽 (dragRel)，而不是绝对坐标,这使得脚本在不同分辨率的屏幕上更具适应性。 - 异常处理: 总是使用
try...except块来捕获pyautogui.ImageNotFoundException等异常，这样即使某个步骤失败,脚本也不会直接崩溃。 - 调试: 在调试脚本时，可以先用
pyautogui.PAUSE = 1.0设置每个pyautogui函数执行后暂停1秒，让你能看清每一步操作，或者，你可以用print(pyautogui.position())来实时打印鼠标位置,帮助你找到目标坐标。 - 性能: 图像识别是相对耗时的操作，如果目标图像很小或者屏幕上有很多相似的元素，可能会比较慢，尽量使用高对比度、清晰的截图作为目标图像。
- 权限: 在某些操作系统（如 macOS）上，你可能需要授予终端/Python 脚本辅助功能权限,才能允许其控制鼠标和键盘。
希望这份详细的指南能帮助你掌握 pyautogui！祝你玩得开心！
