简介这份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这类库更好用的原因。方案面向对象优点缺点pyautogui桌面/任意界面跨平台、无驱动、含截屏识别坐标敏感、盲操作Selenium浏览器DOM元素定位稳定需要下载驱动、仅限WebAppium移动App多端覆盖环境重、上手成本高requestsHTTP接口轻量快速只适合接口层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, duration0.5) # 绝对移动 pyautogui.moveRel(100, -200, duration0.5) # 相对移动点击函数有click、doubleClick、tripleClick、rightClick。doubleClick也可以写成click(clicks2)内部间隔用interval控制pyautogui.click(520, 420, buttonleft) pyautogui.click(520, 420, clicks2, interval0.1) # 双击 pyautogui.rightClick(520, 420)拖拽用dragTo和dragRel注意它和moveTo的区别是按键要一直按住。很多人第一次用拖拽失效其实是忘了指定button参数pyautogui.dragTo(800, 600, duration0.5, buttonleft) pyautogui.dragRel(-100, 50, duration0.3, buttonleft)滚轮操作也放在这一节函数是scroll参数为正数时向上滚负数时向下滚传几就滚几格。别以为滚轮只能滚一档它的参数可以是任意整数适合做页面长距离滚动。比如浏览器里往下翻很多屏直接传一个较大的负数比反复调小滚轮函数快得多。pyautogui.scroll(3) # 向上滚3格 pyautogui.scroll(-5) # 向下滚5格我个人习惯是把这些操作封装成小函数比如click_with_retry先根据坐标点击再截图校验结果发现没生效就重试这样脚本稳定性会好很多。4. 键盘自动化核心操作4.1 文本输入键盘部分最常用的是write它模拟敲击键盘输入字符串。支持interval参数控制每个字符的间隔pyautogui.write(hello world, interval0.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里用的是字符串别名我整理了一份常用对照表按键pyautogui别名回车enter空格space方向键上up方向键下down退格backspace删除delete大写锁定caps lock制表符tabEscesc4.3 中文输入的最稳方案上面说了write输入中文很不可靠。我试过几种方案最稳的还是“剪贴板粘贴大法”把文本复制到系统剪贴板然后模拟CtrlV粘贴。配合pyperclip这个库代码写起来非常干净import pyperclip import pyautogui pyperclip.copy(这是一段中文内容) pyautogui.hotkey(ctrl, v)这个方法还有个额外好处哪怕目标界面支持富文本粘贴也能保留格式。我遇到需要输入中文、编号、长文本的场景一律用粘贴实测下来从来没翻过车。需要提前装一下pyperclippip install pyperclip就能搞定。5. 一个完整实战脚本5.1 用图像识别定位元素坐标写死最大的问题是窗口位置一变脚本就废了。pyautogui自带locateOnScreen可以按图片找坐标原理就是先截取屏幕再在整屏里搜索目标图片返回找到区域的Box对象。box pyautogui.locateOnScreen(save_button.png, confidence0.8) if box: center pyautogui.center(box) pyautogui.click(center) else: print(没找到目标按钮)confidence参数是相似度阈值0.8意味着允许20%以内的像素差异图标尺寸、颜色稍有变化也能认出来。为了提速还可以加grayscaleTrue把图像转灰度再匹配识别速度能快不少代价是颜色区分度变差。注意confidence参数依赖opencv-python第一次用需要单独安装pip install opencv-python。5.2 示例脚本自动打开记事本并输入保存我拿一个非常典型的场景演示自动打开记事本、输入内容、保存文件。这套动作虽然简单但完整覆盖了快捷键、输入、文件保存三个自动化高频点。import pyautogui import time pyautogui.FAILSAFE True pyautogui.PAUSE 0.5 # 1. 用WinR打开运行框 pyautogui.hotkey(win, r) time.sleep(0.5) # 2. 输入notepad并回车 pyautogui.write(notepad, interval0.05) pyautogui.press(enter) time.sleep(1) # 等程序完全打开 # 3. 输入内容 pyautogui.write(Hello, pyautogui!, interval0.05) # 4. CtrlS调出保存窗口 pyautogui.hotkey(ctrl, s) time.sleep(0.5) # 5. 输入文件名并回车保存 pyautogui.write(demo.txt, interval0.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这套东西本身不复杂真正复杂的永远是你对使用场景的理解程度。本文还有配套的精品资源点击获取