Python pyautogui自动化：模拟鼠标键盘，让重复操作一键搞定

简介：这份PDF教程面向Python开发者与自动化测试新手，以pyautogui模块为主线，系统演示如何通过脚本模拟鼠标和键盘操作，覆盖光标移动、单击双击、拖拽、滚轮、屏幕截图、图像匹配、按键输入及组合快捷键等核心接口。教程结合实例解析moveTo、moveRel、click、dragTo、scroll、screenshot、locateOnScreen、hotkey、typewrite等常用函数，并专门说明PAUSE与FAILSAFE机制，帮助避免自动化流程失控。资源为单个PDF文档，大小仅80KB，内容紧凑精炼，既有函数讲解也有可运行的综合示例，适合用于UI自动化测试、批量数据处理和桌面辅助工具开发。目前已有2442人学习下载，对希望快速掌握桌面自动化的Python使用者具有较高的参考价值。 做自动化测试或者办公自动化的时候，遇到重复性的鼠标点击和键盘输入，很容易让人崩溃。与其天天对着表格点来点去，不如写个Python脚本替我们干活。Python生态里自动化方案不少，但要说上手最快、最“所见即所得”的，pyautogui绝对排得上号。它不需要修改被测程序，也不需要额外的驱动，直接模拟鼠标移动、点击、滚轮、键盘输入这些底层操作，只要屏幕上能看到的东西，它就能替你操作。这篇文章就按我自己的实际操作经验，把pyautogui的安装、鼠标操作、键盘操作、完整示例脚本，还有踩过的坑一条条讲清楚，适合刚入门Python自动化、想快速做个小工具解放双手的朋友。

1. 先搞清楚pyautogui到底能干什么

1.1 定位：屏幕和键盘的“机器人手”

pyautogui是一个纯Python的跨平台库，Windows、macOS、Linux都能跑。它的工作方式和Selenium这类工具完全不同：Selenium操作的是浏览器里的DOM元素，pyautogui直接向操作系统发送鼠标和键盘事件。你可以把它理解成一只“机器人手”，屏幕上坐标在哪儿它就点哪儿，你告诉它按什么键它就按什么键。

这个定位决定了它的能力边界：凡是人能通过鼠标键盘完成的重复操作，它基本都能做，比如自动填表、批量导出、定时点击、简单UI回归测试。但它本身不认识界面上的“按钮”和“输入框”，只能靠坐标和图像识别来定位，所以脚本的稳定性取决于目标界面是否固定。理解了这一点，后面很多“为什么这么写”的问题就迎刃而解。

1.2 为什么选pyautogui而不是其他方案

很多朋友一上来就问，有Selenium、Appium、还有各种接口自动化框架，为什么还要学pyautogui？我的选择标准很简单：看你要操作的对象在哪一层。

• 操作网页：首选Selenium或Playwright，能拿到DOM，定位稳定可靠。
• 操作移动App：用Appium，它管的是手机端。
• 操作桌面软件：企业微信、ERP客户端、老旧MIS系统这类，Selenium管不了，pyautogui就是最直接的选择。
• 接口自动化：用requests直接发HTTP请求，根本不需要界面。
• 跨程序联动：从Excel复制数据填到网页，再切到桌面软件点几下，这种混合场景pyautogui可以和Selenium、Excel自动化配合使用。

我实际项目里最常用的组合是pyautogui加Selenium：网页主体用Selenium处理，碰到弹窗、上传文件这类Selenium难搞的，再用pyautogui补刀。另外pyautogui自带了截屏和图像识别能力，这也是它比单独的keyboard、mouse这类库更好用的原因。

2. 环境准备和安装避坑

2.1 安装Python和pyautogui

系统里没有Python的话，先去官网下载安装包，装的时候记得勾选“Add Python to PATH”，不然命令行敲python会提示找不到命令。装完打开终端验证一下：

python --version pip --version

然后安装pyautogui，一条命令搞定：

pip install pyautogui

如果你在macOS或者Linux上遇到权限问题，多半是用了系统自带的Python，建议用虚拟环境，或者直接加 --user 参数：

pip install --user pyautogui

装完跑一下这个验证脚本，能打印出屏幕分辨率，说明基础环境没问题：

import pyautogui print(pyautogui.size())

平时用VSCode写Python的朋友注意，记得检查编辑器右下角选的解释器环境，别让命令行能import、编辑器里却报ModuleNotFoundError，这个错我见过太多次了，基本都是环境选错。

2.2 依赖库和权限设置

pyautogui安装时会自动带上Pillow、pyscreeze、pymsgbox、pytweening这些依赖。Pillow负责图像处理，pyscreeze负责屏幕截图识别。如果安装时网络不好导致依赖缺失，后面import大概率会报错，这个我在第六部分专门讲怎么排查。

macOS用户注意，首次运行会触发辅助功能权限，需要到“系统设置 - 隐私与安全性 - 辅助功能”里把Python解释器加进去，否则鼠标键盘事件会被系统拦截。Windows下一般没这个限制，但如果你在服务器或者远程桌面后台跑，必须保证会话里有真实桌面，否则脚本“看不见屏幕”就没法干活。

3. 鼠标自动化核心操作

3.1 先理解坐标系和保护机制

pyautogui的坐标系以屏幕左上角为原点，向右是x轴，向下是y轴，单位是像素。比如1920x1080的屏幕，右下角坐标就是(1919, 1079)。写脚本前我建议先记住两个全局配置：

import pyautogui pyautogui.FAILSAFE = True # 失控保护，默认True pyautogui.PAUSE = 0.3 # 每条操作之间停顿0.3秒

FAILSAFE是pyautogui最贴心的设计：脚本跑偏时，只要把鼠标甩到屏幕左上角，它会立刻抛出FailSafeException中断程序，避免脚本在电脑上乱点一通。PAUSE则是给每条指令之间加固定间隔，防止操作太快导致界面反应不过来。这两个配置我建议任何脚本都保留。

3.2 移动、点击和拖拽

鼠标操作的核心函数不多，但每个都有讲究。先说移动，moveTo是绝对坐标，moveRel是相对当前位置偏移。给duration传一个非零值，鼠标会以“人肉速度”滑过去，视觉上更像真人操作，也能给界面留出响应时间。

pyautogui.moveTo(500, 400, duration=0.5) # 绝对移动 pyautogui.moveRel(100, -200, duration=0.5) # 相对移动

点击函数有click、doubleClick、tripleClick、rightClick。doubleClick也可以写成click(clicks=2)，内部间隔用interval控制：

pyautogui.click(520, 420, button='left') pyautogui.click(520, 420, clicks=2, interval=0.1) # 双击 pyautogui.rightClick(520, 420)

拖拽用dragTo和dragRel，注意它和moveTo的区别是按键要一直按住。很多人第一次用拖拽失效，其实是忘了指定button参数：

pyautogui.dragTo(800, 600, duration=0.5, button='left') pyautogui.dragRel(-100, 50, duration=0.3, button='left')

滚轮操作也放在这一节，函数是scroll，参数为正数时向上滚，负数时向下滚，传几就滚几格。别以为滚轮只能滚一档，它的参数可以是任意整数，适合做页面长距离滚动。比如浏览器里往下翻很多屏，直接传一个较大的负数，比反复调小滚轮函数快得多。

pyautogui.scroll(3) # 向上滚3格 pyautogui.scroll(-5) # 向下滚5格

我个人习惯是把这些操作封装成小函数，比如click_with_retry，先根据坐标点击，再截图校验结果，发现没生效就重试，这样脚本稳定性会好很多。

4. 键盘自动化核心操作

4.1 文本输入

键盘部分最常用的是write，它模拟敲击键盘输入字符串。支持interval参数控制每个字符的间隔：

pyautogui.write('hello world', interval=0.05)

注意write只支持键盘上能直接打出来的ASCII字符，遇到中文、特殊符号可能会出问题。这里有个隐藏的坑：如果当前输入法处于中文模式，write输入的英文字母可能被输入法截胡，最后上屏变成拼音。稳妥的做法是脚本运行前先切成英文输入法，或者干脆用后面第三小节讲的剪贴板方案。

4.2 组合键和特殊按键

组合键是自动化的高频操作，比如保存、复制、粘贴、切换窗口。pyautogui提供了hotkey，它会自动处理按键按下和释放的先后顺序，不用自己操心：

pyautogui.hotkey('ctrl', 's') # 保存 pyautogui.hotkey('ctrl', 'c') # 复制 pyautogui.hotkey('alt', 'tab') # 切换窗口 pyautogui.press('enter') # 回车

如果想自己控制按键的“按下”和“松开”时机，就用keyDown和keyUp。比如某些自绘界面只认长按事件，需要拆开用：

pyautogui.keyDown('shift') pyautogui.press('a') pyautogui.keyUp('shift')

特殊按键在press、hotkey里用的是字符串别名，我整理了一份常用对照表：

4.3 中文输入的最稳方案

上面说了，write输入中文很不可靠。我试过几种方案，最稳的还是“剪贴板粘贴大法”：把文本复制到系统剪贴板，然后模拟Ctrl+V粘贴。配合pyperclip这个库，代码写起来非常干净：

import pyperclip import pyautogui pyperclip.copy('这是一段中文内容') pyautogui.hotkey('ctrl', 'v')

这个方法还有个额外好处：哪怕目标界面支持富文本，粘贴也能保留格式。我遇到需要输入中文、编号、长文本的场景，一律用粘贴，实测下来从来没翻过车。需要提前装一下pyperclip，pip install pyperclip就能搞定。

5. 一个完整实战脚本

5.1 用图像识别定位元素

坐标写死最大的问题是：窗口位置一变，脚本就废了。pyautogui自带locateOnScreen，可以按图片找坐标，原理就是先截取屏幕，再在整屏里搜索目标图片，返回找到区域的Box对象。

box = pyautogui.locateOnScreen('save_button.png', confidence=0.8) if box: center = pyautogui.center(box) pyautogui.click(center) else: print('没找到目标按钮')

confidence参数是相似度阈值，0.8意味着允许20%以内的像素差异，图标尺寸、颜色稍有变化也能认出来。为了提速，还可以加grayscale=True把图像转灰度再匹配，识别速度能快不少，代价是颜色区分度变差。注意confidence参数依赖opencv-python，第一次用需要单独安装：pip install opencv-python。

5.2 示例脚本：自动打开记事本并输入保存

我拿一个非常典型的场景演示：自动打开记事本、输入内容、保存文件。这套动作虽然简单，但完整覆盖了快捷键、输入、文件保存三个自动化高频点。

import pyautogui import time pyautogui.FAILSAFE = True pyautogui.PAUSE = 0.5 # 1. 用Win+R打开运行框 pyautogui.hotkey('win', 'r') time.sleep(0.5) # 2. 输入notepad并回车 pyautogui.write('notepad', interval=0.05) pyautogui.press('enter') time.sleep(1) # 等程序完全打开 # 3. 输入内容 pyautogui.write('Hello, pyautogui!', interval=0.05) # 4. Ctrl+S调出保存窗口 pyautogui.hotkey('ctrl', 's') time.sleep(0.5) # 5. 输入文件名并回车保存 pyautogui.write('demo.txt', interval=0.05) pyautogui.press('enter')

每一步sleep都是有目的的：程序启动、窗口弹出都需要时间。脚本跑得比人手快太多，不给界面留缓冲时间，后面的输入就可能丢。实际开发中，我会把这些固定等待替换成循环检测，比如反复用图像识别找“保存”按钮，找到了再继续，这样比傻等更稳定。

5.3 给脚本加上“防呆”设计

只要脚本会在无人值守的情况下跑，就必须考虑异常兜底。我的习惯是三个防呆：一是全局try-finally保证失败时能截图留证据；二是关键位置输出日志；三是永远保留FAILSAFE。截图留证据用screenshot很方便：

import traceback try: run_automation() except pyautogui.FailSafeException: print('检测到紧急停止，退出脚本') except Exception: pyautogui.screenshot('error.png') # 出错时留现场 traceback.print_exc() finally: pyautogui.click() # 确保松开所有按键

这套组合在跑UI回归脚本时救过我很多次，尤其是半夜跑批量任务，第二天一看截图就知道挂在哪一步了，不用对着黑窗口猜。

6. 踩坑记录和常见问题速查

6.1 导入时提示pyscreeze相关错误

很多人刚装完pyautogui，一import就弹出类似“pyautogui was unable to import pyscreeze”的提示，然后图像识别功能全部罢工。这个问题的根源多半是依赖装得不完整，常见的修复顺序是：

pip install --upgrade pyautogui pip install pillow pip install pyscreeze pip install opencv-python

装完重新打开Python解释器再import一次。如果还报错，多半是环境里多个Python版本混了，pip装到了A环境，解释器用的却是B环境。用python -m pip install xxx这种写法，能保证装到当前解释器对应的环境里。

6.2 Failsafe突然触发导致脚本中断

脚本跑着跑着，鼠标自己跳到屏幕左上角，然后抛异常退出——这是FAILSAFE生效了。有时候是程序把鼠标移动到了(0,0)点附近，有时候是我们在调试时手动碰了一下鼠标。解决方案有两个：一是把脚本里的移动目标避开左上角区域；二是明确知道脚本安全时，可以显式设置pyautogui.FAILSAFE = False。我不建议轻易关掉它，它就像安全气囊，日常嫌它碍事，真出事的时候能救命。

6.3 屏幕缩放导致坐标偏移

Windows高分屏经常把显示缩放设成125%、150%，这时候用moveTo(1000, 500)点击，实际点到的可能是缩放后的另一个位置，因为逻辑坐标和物理像素对不上。最省事的解决办法：跑脚本前把显示缩放临时改成100%。如果不想动全局设置，就只能用locateOnScreen做图像定位，让脚本自己去“找”目标，不依赖写死的坐标。

6.4 操作太快导致程序卡顿或丢事件

截图和图像识别本身就很耗时，如果脚本循环里没有停顿，很容易把CPU跑满，界面也会变得迟钝。我的经验是：每个循环至少加0.2到0.5秒的sleep，能用PAUSE全局控制就用PAUSE，不要每个函数手写一堆sleep。另外，pyautogui的截图接口是同步阻塞的，在需要连续截图的场景里，尽量复用截图结果，减少无谓的重复截屏。

如果你想让pyautogui跑进Jenkins这类自动化流水线，一定要确认执行节点是有真实桌面的交互式会话。挂在后台服务里的GUI自动化经常什么都点不到，这不是代码问题，是会话环境问题。

最后再分享一个我自己的习惯：正式脚本跑之前，永远准备一份“测试副本”，先用慢速度、多日志的模式完整跑通一遍，再调快参数。自动化脚本不怕慢，就怕不可控。pyautogui这套东西本身不复杂，真正复杂的永远是你对使用场景的理解程度。

本文还有配套的精品资源，点击获取