PyAutoGUI 桌面自动化从入门到实战（附可直接运行代码）

在日常办公、软件测试、重复桌面操作处理等场景中，很多机械性的工作（如批量填写表单、重复点击按钮、自动保存文件）都可以通过桌面自动化工具解放双手。PyAutoGUI 是 Python 中一款轻量、跨平台、易用的桌面自动化库，无需深入了解底层系统 API，即可实现鼠标、键盘的精准控制，以及屏幕截图、图像识别等核心功能。本文以实操为核心，全程搭配可直接复制运行的代码，从环境搭建到综合实战，全面讲解 PyAutoGUI 的核心用法，适合Python初学者和办公自动化从业者参考。

一、前置准备：环境安装与核心避坑须知

在开始编写代码前，先完成环境搭建，并掌握几个关键注意事项，避免后续操作中出现程序失控、操作无响应等问题。

1. 环境安装（两步到位）

PyAutoGUI 支持 Windows、Mac、Linux 三大平台，安装流程简单，核心依赖 Pillow（用于截图处理）会自动附带安装。

（1）核心安装命令

打开命令提示符（Windows）或终端（Mac/Linux），输入以下命令直接安装：

pip install pyautogui

（2）进阶依赖安装（图像识别必备）

若需要使用图像定位功能（locateOnScreen() 等），需额外安装 OpenCV 以提高匹配精度，命令如下：

pip install opencv-python

2. 核心注意事项（新手必看，避坑关键）

（1）防呆机制：避免程序运行失控

PyAutoGUI 默认开启紧急停止机制（failSafe=True），当程序运行时，将鼠标快速移动到屏幕左上角（坐标 (0,0)），即可立即终止所有 PyAutoGUI 操作，防止出现“鼠标乱飘、无法停止程序”的尴尬场景。
若需关闭该机制（不推荐），可添加代码：pyautogui.FAILSAFE = False。

（2）分辨率一致性：定位操作的基础

PyAutoGUI 基于屏幕像素坐标进行操作，所有鼠标、截图操作都依赖当前屏幕的分辨率。

  • 查看当前屏幕分辨率：可通过 pyautogui.size() 获取，返回元组 (宽度, 高度)，例如 (1920, 1080)。
  • 坐标规则：屏幕左上角为原点 (0, 0)，向右为 x 轴正方向，向下为 y 轴正方向，右下角坐标为 (屏幕宽度-1, 屏幕高度-1)。

（3）权限问题：确保操作正常执行

  • Windows：建议以管理员身份运行 Python 脚本，避免部分软件（如办公软件、系统设置）拒绝自动化操作。
  • Mac：需要在「系统设置」→「隐私与安全性」→「辅助功能」中，勾选运行脚本的 Python 解释器，授予桌面控制权限。
  • Linux：需要安装额外依赖（sudo apt-get install scrot python3-tk python3-dev），并授予屏幕捕获权限。

（4）操作延迟：避免软件响应不及时

PyAutoGUI 操作速度极快，部分软件（如记事本、浏览器）可能无法及时响应，建议在关键操作之间添加延迟，可通过两种方式实现：

  1. 全局延迟：pyautogui.PAUSE = 0.5（所有 PyAutoGUI 操作后自动延迟 0.5 秒，推荐新手使用）。
  2. 局部延迟：使用 time.sleep() 函数，在指定操作之间添加自定义延迟。

二、核心基础1：鼠标自动化（移动、点击、拖拽、滚动）

鼠标操作是桌面自动化的核心，PyAutoGUI 提供了一系列简洁的函数，实现鼠标的精准控制，覆盖所有日常鼠标操作场景。

1. 核心鼠标操作函数与语法

操作类型 核心函数 功能说明 关键参数
绝对移动 pyautogui.moveTo(x, y, duration=0) 将鼠标移动到屏幕指定坐标 (x,y) duration：移动耗时（秒），默认瞬间移动
相对移动 pyautogui.moveRel(dx, dy, duration=0) 以当前鼠标位置为基准，相对移动 dx（左右）、dy（上下） dx 为正向右，dy 为正向下
单击鼠标 pyautogui.click(x=None, y=None, button='left', clicks=1, interval=0) 在指定坐标单击鼠标（默认左键） button：指定按键（'left'/'right'/'middle'）；clicks：点击次数；interval：多次点击间隔
右键单击 pyautogui.rightClick(x=None, y=None) 简化版左键单击，仅实现右键单次点击 -
双击鼠标 pyautogui.doubleClick(x=None, y=None) 简化版左键单击，仅实现左键双击 -
鼠标拖拽 pyautogui.dragTo(x, y, duration=0) 按住鼠标左键，拖拽到指定坐标 (x,y) duration：拖拽耗时（秒）
相对拖拽 pyautogui.dragRel(dx, dy, duration=0) 按住鼠标左键，相对当前位置拖拽 dx、dy -
鼠标滚动 pyautogui.scroll(clicks, x=None, y=None) 在指定坐标滚动鼠标滚轮 clicks：滚动步数（正为向上，负为向下）

2. 完整实操代码：鼠标自动化综合演示

# PyAutoGUI 鼠标自动化核心演示
import pyautogui
import time

# 1. 初始化设置（防呆+全局延迟，新手必备）
pyautogui.FAILSAFE = True  # 开启紧急停止机制
pyautogui.PAUSE = 0.8      # 所有操作后延迟 0.8 秒，避免软件无响应
screen_width, screen_height = pyautogui.size()  # 获取当前屏幕分辨率
print(f"当前屏幕分辨率：{screen_width} × {screen_height}")

# 2. 鼠标绝对移动：从原点移动到屏幕中心，再移动到右下角
print("开始鼠标绝对移动演示...")
pyautogui.moveTo(0, 0, duration=1)  # 移动到左上角（原点）
time.sleep(1)
pyautogui.moveTo(screen_width/2, screen_height/2, duration=1.5)  # 移动到屏幕中心
time.sleep(1)
pyautogui.moveTo(screen_width-100, screen_height-100, duration=1.5)  # 移动到右下角（预留100像素，避免超出屏幕）

# 3. 鼠标相对移动：以当前位置（右下角）为基准，向上、向左移动
print("开始鼠标相对移动演示...")
pyautogui.moveRel(0, -200, duration=1)  # 向上移动 200 像素（dy 为负）
time.sleep(1)
pyautogui.moveRel(-300, 0, duration=1)  # 向左移动 300 像素（dx 为负）

# 4. 鼠标点击：左键单击、右键单击、左键双击
print("开始鼠标点击演示...")
click_x, click_y = screen_width/2, screen_height/2  # 点击目标坐标（屏幕中心）
pyautogui.moveTo(click_x, click_y, duration=1)  # 先移动到目标坐标
pyautogui.click(click_x, click_y, button='left', clicks=1)  # 左键单击
time.sleep(1)
pyautogui.rightClick(click_x, click_y)  # 右键单击
time.sleep(1)
pyautogui.doubleClick(click_x, click_y)  # 左键双击

# 5. 鼠标拖拽：从屏幕中心拖拽到左下方
print("开始鼠标拖拽演示...")
drag_target_x, drag_target_y = 200, screen_height-200
pyautogui.dragTo(drag_target_x, drag_target_y, duration=2)  # 按住左键拖拽到目标坐标

# 6. 鼠标滚动：在拖拽目标位置，向上滚动 5 步，再向下滚动 10 步
print("开始鼠标滚动演示...")
pyautogui.moveTo(drag_target_x, drag_target_y, duration=1)
pyautogui.scroll(5, x=drag_target_x, y=drag_target_y)  # 向上滚动 5 步
time.sleep(1)
pyautogui.scroll(-10, x=drag_target_x, y=drag_target_y)  # 向下滚动 10 步

# 7. 演示结束，返回屏幕中心
print("鼠标自动化演示结束，返回屏幕中心...")
pyautogui.moveTo(screen_width/2, screen_height/2, duration=1.5)
print("所有操作完成！")

3. 运行效果说明

运行上述代码后，可观察到鼠标按照预设流程自动移动、点击、拖拽、滚动，每一步操作之间有 0.8 秒延迟（全局设置），关键步骤之间额外添加了 time.sleep() 延迟，方便清晰观察演示效果。所有操作均围绕屏幕分辨率进行，适配不同尺寸的显示器，无需额外修改参数。

三、核心基础2：键盘自动化（输入、按键、组合键）

键盘自动化主要用于文本输入、快捷键操作等场景，PyAutoGUI 支持普通字符串输入、单键操作、组合键操作，覆盖办公自动化中绝大多数键盘使用场景。

1. 核心键盘操作函数与语法

操作类型 核心函数 功能说明 关键参数
文本输入 pyautogui.typewrite(text, interval=0) 输入指定字符串（支持英文、数字、符号） interval：每个字符输入间隔（秒），默认瞬间输入
单键按下 pyautogui.keyDown(key) 按住指定按键，不释放 key：按键名称（如 'enter'、'ctrl'、'a'）
单键释放 pyautogui.keyUp(key) 释放已按住的按键 -
热键/组合键 pyautogui.hotkey(*keys, interval=0) 按下并释放一组组合键（如 Ctrl+C、Ctrl+V） *keys：组合键列表，按操作顺序排列

2. 常用特殊按键名称对照表（新手必备）

PyAutoGUI 对特殊按键有固定的命名规则，以下是日常使用频率最高的特殊按键，直接复制即可使用：

实际按键 PyAutoGUI 名称 实际按键 PyAutoGUI 名称
回车键 enter 制表符（Tab） tab
退格键 backspace 空格键 space
删除键（Del） delete 大写锁定（Caps Lock） capslock
ESC 键 esc 上档键（Shift） shift
控制键（Ctrl） ctrl 备选键（Alt） alt
窗口键（Windows） win 方向键（上/下/左/右） up/down/left/right

3. 完整实操代码：键盘自动化综合演示（结合记事本）

# PyAutoGUI 键盘自动化核心演示（自动操作记事本）
import pyautogui
import time

# 1. 初始化设置
pyautogui.FAILSAFE = True
pyautogui.PAUSE = 0.6
screen_width, screen_height = pyautogui.size()

# 2. 第一步：打开记事本（Windows 系统，通过运行命令打开）
print("正在打开记事本...")
# 按下 Win+R 打开运行窗口
pyautogui.hotkey('win', 'r')
time.sleep(1)
# 输入 notepad 并按下回车，启动记事本
pyautogui.typewrite('notepad', interval=0.1)
pyautogui.press('enter')  # press() 是 keyDown()+keyUp() 的简化版，单次按键释放

# 3. 第二步：等待记事本启动，调整鼠标位置到记事本编辑区域
print("等待记事本启动...")
time.sleep(2)  # 等待程序加载，根据电脑性能可调整延迟时间
notepad_x, notepad_y = screen_width/2 - 200, screen_height/2 - 150
pyautogui.moveTo(notepad_x, notepad_y, duration=1)
pyautogui.click()  # 点击编辑区域，激活输入

# 4. 第三步：输入普通文本（带字符间隔，模拟人工输入）
print("正在输入普通文本...")
content = "Hello PyAutoGUI!\n这是一款强大的 Python 桌面自动化库。\n支持鼠标、键盘、截图、图像识别等功能。"
pyautogui.typewrite(content, interval=0.08)  # 每个字符间隔 0.08 秒，模拟人工打字速度
time.sleep(1)

# 5. 第四步：快捷键操作（全选、复制、粘贴、保存）
print("正在执行快捷键操作...")
# 全选文本（Ctrl+A）
pyautogui.hotkey('ctrl', 'a')
time.sleep(0.5)
# 复制文本（Ctrl+C）
pyautogui.hotkey('ctrl', 'c')
time.sleep(0.5)
# 粘贴文本（Ctrl+V），在当前文本后追加一份
pyautogui.press('enter')
pyautogui.hotkey('ctrl', 'v')
time.sleep(0.5)
# 保存文件（Ctrl+S），打开保存对话框
pyautogui.hotkey('ctrl', 's')
time.sleep(1)

# 6. 第五步：在保存对话框中，输入文件名并保存到桌面
print("正在保存文件...")
# 输入文件名（PyAutoGUI_记事本演示.txt）
file_name = "PyAutoGUI_记事本演示.txt"
pyautogui.typewrite(file_name, interval=0.1)
time.sleep(0.5)
# 按下回车，完成保存（默认保存路径为桌面，可自行修改）
pyautogui.press('enter')
time.sleep(1)

# 7. 第六步：关闭记事本（Alt+F4）
print("正在关闭记事本...")
pyautogui.hotkey('alt', 'f4')
time.sleep(1)

# 8. 演示结束
print("键盘自动化演示结束！文件已保存到桌面，可前往查看。")

4. 运行效果说明

该代码仅支持 Windows 系统，运行后会自动完成以下操作：

  1. 按下 Win+R 打开运行窗口，输入 notepad 启动记事本；
  2. 在记事本编辑区域输入预设文本，模拟人工打字速度；
  3. 通过 Ctrl+A、Ctrl+C、Ctrl+V 实现文本的全选、复制、粘贴；
  4. 通过 Ctrl+S 打开保存对话框，输入文件名并完成保存；
  5. 通过 Alt+F4 关闭记事本，最终在桌面可找到名为 PyAutoGUI_记事本演示.txt 的文件。

注意：Mac/Linux 系统可替换为“文本编辑”软件，修改打开方式即可适配。

四、进阶功能：屏幕截图与图像识别（精准定位目标）

前面的鼠标、键盘操作都是基于固定坐标，但实际场景中，目标窗口的位置可能会变化，此时需要通过「图像识别」来精准定位目标位置。PyAutoGUI 提供了屏幕截图和图像匹配功能，能够根据预先准备的目标图像，自动查找其在屏幕上的坐标，实现“动态定位”。

1. 核心截图与图像识别函数与语法

操作类型 核心函数 功能说明 关键参数
全屏截图 pyautogui.screenshot(image_path=None) 捕获整个屏幕，可选保存为图片文件 image_path：图片保存路径（如 'screen.png'）
区域截图 pyautogui.screenshot(image_path=None, region=(x, y, w, h)) 捕获指定区域的屏幕内容 region：截图区域（x,y 为左上角坐标，w 为宽度，h 为高度）
图像定位 pyautogui.locateOnScreen(target_image, confidence=0.8) 在屏幕上查找目标图像的位置，返回矩形坐标 confidence：匹配精度（0~1），值越高匹配越严格，需安装 OpenCV
获取中心坐标 pyautogui.center(rectangle) 从图像定位返回的矩形坐标中，提取中心坐标 rectangle：locateOnScreen() 返回的矩形数据

2. 完整实操代码：图像识别定位桌面图标并双击打开

# PyAutoGUI 屏幕截图与图像识别演示（定位桌面图标并打开）
import pyautogui
import time

# 1. 初始化设置
pyautogui.FAILSAFE = True
pyautogui.PAUSE = 0.7
confidence_value = 0.85  # 图像匹配精度，建议 0.8~0.9 之间

# 2. 前置准备：提醒用户准备目标图像（桌面图标截图，保存为 target_icon.png）
print("温馨提示：请确保桌面存在目标图标，并已将该图标截图保存为 target_icon.png，放置在脚本同一目录下。")
print("等待 5 秒，准备开始图像识别...")
time.sleep(5)

# 3. 第一步：尝试在屏幕上定位目标图像（桌面图标）
try:
    print("正在查找目标图像...")
    # locateOnScreen() 查找目标图像，返回 (x, y, w, h) 矩形坐标
    target_rect = pyautogui.locateOnScreen('target_icon.png', confidence=confidence_value)
    if target_rect is None:
        print("未找到目标图像，请检查图像文件是否正确、是否清晰。")
        exit()
    
    # 提取目标图像的中心坐标（方便鼠标点击）
    target_x, target_y = pyautogui.center(target_rect)
    print(f"找到目标图像！中心坐标：({target_x}, {target_y})")

# 4. 第二步：移动鼠标到目标图标，双击打开
    print("正在打开目标程序...")
    pyautogui.moveTo(target_x, target_y, duration=1.2)
    pyautogui.doubleClick(target_x, target_y)
    time.sleep(2)

# 5. 第三步：全屏截图，保存操作结果
    print("正在截取当前屏幕，保存操作结果...")
    pyautogui.screenshot('PyAutoGUI_图像识别操作结果.png')
    print("屏幕截图已保存为 PyAutoGUI_图像识别操作结果.png")

except Exception as e:
    print(f"操作出错：{e}")
    print("请检查：1. 目标图像文件是否存在；2. OpenCV 是否已安装；3. 图像是否清晰可识别。")

# 6. 演示结束
print("图像识别与屏幕截图演示结束！")

3. 运行前准备与效果说明

（1）运行前准备

  1. 截取一张桌面图标（如 Chrome 浏览器、微信）的清晰截图，保存为 target_icon.png，放置在 Python 脚本同一目录下；
  2. 确保已安装 OpenCV（pip install opencv-python），否则 confidence 参数无法使用，匹配精度会大幅下降；
  3. 运行脚本前，将桌面其他无关图标隐藏，提高图像匹配成功率。

（2）运行效果

脚本运行后，会自动在屏幕上查找 target_icon.png 对应的图标，找到后移动鼠标并双击打开该程序，最后截取全屏并保存操作结果，方便验证操作是否成功。

4. 图像识别避坑技巧

  1. 目标图像需清晰无遮挡，避免模糊、反光、缩放变形；
  2. 匹配精度 confidence 建议设置在 0.8~0.9 之间，过高容易匹配失败，过低容易出现误匹配；
  3. 若屏幕分辨率发生变化，需重新截取目标图像，否则无法匹配；
  4. 对于动态变化的界面（如按钮高亮、文字变化），需截取多个状态的图像，提高匹配成功率。

五、综合实战：办公自动化案例（批量整理桌面文件）

结合前面的鼠标、键盘、图像识别功能，实现一个实用的办公自动化案例：自动将桌面所有文件按后缀名分类，移动到对应文件夹（如文档、图片、压缩包）。

完整实战代码

# PyAutoGUI 办公自动化实战：批量整理桌面文件
import pyautogui
import os
import shutil
import time

# 1. 初始化设置
pyautogui.FAILSAFE = True
pyautogui.PAUSE = 0.5
screen_width, screen_height = pyautogui.size()

# 2. 定义文件分类规则（后缀名 → 文件夹名称）
file_categories = {
    # 文档类
    '.txt': '文档文件',
    '.doc': '文档文件',
    '.docx': '文档文件',
    '.pdf': '文档文件',
    '.xlsx': '文档文件',
    '.pptx': '文档文件',
    # 图片类
    '.jpg': '图片文件',
    '.jpeg': '图片文件',
    '.png': '图片文件',
    '.gif': '图片文件',
    '.bmp': '图片文件',
    # 压缩包类
    '.zip': '压缩包文件',
    '.rar': '压缩包文件',
    '.7z': '压缩包文件',
    # 可执行文件类
    '.exe': '可执行文件',
    '.msi': '可执行文件'
}

# 3. 定义桌面路径（适配 Windows 系统）
desktop_path = os.path.join(os.path.expanduser("~"), "Desktop")
print(f"桌面路径：{desktop_path}")
print("正在准备整理桌面文件...")
time.sleep(2)

# 4. 第一步：创建对应分类文件夹（若不存在）
for folder_name in set(file_categories.values()):
    folder_path = os.path.join(desktop_path, folder_name)
    if not os.path.exists(folder_path):
        os.makedirs(folder_path)
        print(f"创建文件夹：{folder_name}")
time.sleep(1)

# 5. 第二步：获取桌面所有文件，遍历并分类移动
desktop_files = [f for f in os.listdir(desktop_path) if os.path.isfile(os.path.join(desktop_path, f))]
if not desktop_files:
    print("桌面无文件需要整理！")
    exit()

print(f"找到 {len(desktop_files)} 个桌面文件，开始批量整理...")
for file_name in desktop_files:
    file_path = os.path.join(desktop_path, file_name)
    file_ext = os.path.splitext(file_name)[1].lower()  # 获取文件后缀名，转为小写
    
    # 匹配分类文件夹
    if file_ext in file_categories:
        target_folder = file_categories[file_ext]
        target_folder_path = os.path.join(desktop_path, target_folder)
        
        # 移动文件到目标文件夹
        try:
            shutil.move(file_path, target_folder_path)
            print(f"已移动：{file_name} → {target_folder}")
            
            # 模拟人工操作间隔，避免系统卡顿
            time.sleep(0.3)
        except Exception as e:
            print(f"移动失败：{file_name} → 错误：{e}")
    else:
        # 未匹配到分类的文件，移动到「其他文件」文件夹
        other_folder = "其他文件"
        other_folder_path = os.path.join(desktop_path, other_folder)
        if not os.path.exists(other_folder_path):
            os.makedirs(other_folder_path)
        try:
            shutil.move(file_path, other_folder_path)
            print(f"已移动：{file_name} → {other_folder}")
            time.sleep(0.3)
        except Exception as e:
            print(f"移动失败：{file_name} → 错误：{e}")

# 6. 第三步：操作完成，弹出提示（通过记事本显示）
print("桌面文件整理完成，正在弹出提示...")
# 打开记事本，显示整理结果
pyautogui.hotkey('win', 'r')
time.sleep(1)
pyautogui.typewrite('notepad')
pyautogui.press('enter')
time.sleep(2)

# 输入整理结果提示
result_content = f"桌面文件整理完成！\n共处理 {len(desktop_files)} 个文件，已按后缀名分类到对应文件夹。\n查看桌面即可看到分类结果。"
pyautogui.typewrite(result_content, interval=0.05)
time.sleep(3)

# 7. 演示结束
print("办公自动化实战：桌面文件批量整理 已完成！")

运行效果说明

  1. 脚本适配 Windows 系统，运行后会自动在桌面创建「文档文件」「图片文件」等分类文件夹；
  2. 遍历桌面所有文件，根据后缀名自动移动到对应文件夹，未匹配到后缀名的文件移动到「其他文件」；
  3. 整理完成后，自动打开记事本显示整理结果，方便用户确认；
  4. 所有操作均为后台文件操作，结合 PyAutoGUI 实现结果提示，兼顾效率与可视化验证。

六、常见问题与避坑指南（新手必备）

  1. 程序运行失控，无法停止：立即将鼠标移动到屏幕左上角（原点 (0,0)），触发紧急停止机制；若无效，可通过任务管理器结束 Python 进程。
  2. 鼠标/键盘操作无响应：① 未以管理员身份运行脚本（Windows）；② Mac 未授予辅助功能权限；③ 目标窗口被最小化或遮挡，需确保目标窗口在前台显示。
  3. 图像识别返回 None，匹配失败：① 目标图像文件不存在或路径错误；② 未安装 OpenCV，无法使用 confidence 参数；③ 目标图像模糊、变形或屏幕分辨率变化，需重新截取清晰图像。
  4. 文本输入出现乱码或无法输入中文：PyAutoGUI 仅支持英文输入法，不支持中文输入法直接输入；若需输入中文，可通过「复制粘贴」方式（先将中文复制到剪贴板，再用 hotkey('ctrl', 'v') 粘贴）。
  5. 操作速度过快导致软件卡顿/出错：① 提高全局延迟 pyautogui.PAUSE；② 在关键操作之间添加 time.sleep() 自定义延迟；③ 文本输入时设置 interval 参数，模拟人工输入速度。
  6. 文件夹创建/文件移动失败：① 目标文件正在被其他程序占用；② 没有文件操作权限，需以管理员身份运行脚本；③ 桌面路径错误，需适配对应系统（Mac 桌面路径：os.path.join(os.path.expanduser("~"), "Desktop")）。
posted @ 2025-12-30 22:21  python农工  阅读(641)  评论(0)    收藏  举报