简介PyAutoGUI-0.9.26.zip 是 Python 生态中广受欢迎的 GUI 自动化库源码包面向希望用脚本替代重复鼠标键盘操作的开发者、测试人员与自动化爱好者。它通过模拟点击、移动、滚动、输入及热键触发等行为帮助完成自动化测试、数据采集与界面流程设计并兼容 Windows、macOS 与 Linux 多平台。压缩包共 37 个文件约 53KB以 14 个 py 源码文件为核心辅以 12 个 rst 文档、4 个 txt 说明及 pkg-info、bat、md、cfg、makefile 等配置与构建文件目录中同时包含 tests 测试用例与 docs 文档模块便于理解库的分层实现与使用方式。目前已有 486 人学习下载。读者可从中获得完整的库源码结构、各平台适配实现、官方文档与测试示例既能快速集成到现有 Python 项目也能作为学习 GUI 自动化原理与二次开发的参考素材。1. 桌面自动化的“最后一公里”为什么我还在用 PyAutoGUI-0.9.26上周帮一个做数据录入的朋友处理一个破事他们内部有个老系统没有 API没有数据库权限每天要把几百条 Excel 记录手动敲进一个客户端界面里。他问我有没有办法“让电脑自己点”。这种需求其实特别常见——不是所有自动化都能走接口很多时候你面对的就是一个只能鼠标键盘操作的窗口。PyAutoGUI 就是干这个的用 Python 脚本模拟鼠标移动、点击、拖拽和键盘输入还能截图定位屏幕上的元素。它不依赖任何应用内部接口纯粹从“操作系统输入层”下手所以对老系统、游戏窗口、远程桌面里的界面都有效。0.9.26 这个版本号看着老但它是 PyAutoGUI 一个非常稳定的发行版依赖少、兼容性好在 Windows 和 macOS 上跑批量操作很少出玄学问题。如果你手头有重复性的 GUI 操作要自动化又不想折腾重量级 RPA 工具这个包值得拆开看看。2. 拆包与最小可运行环境从 zip 到第一次点击2.1 包结构里有什么为什么选这个版本拿到 PyAutoGUI-0.9.26.zip 之后先别急着装。解压看一眼目录通常包含pyautogui/源码目录、setup.py、README.md和tests/。这个包的核心逻辑全在pyautogui/__init__.py里它做了一层跨平台封装Windows 上调ctypes走user32.dllmacOS 上调Quartz事件服务Linux 上依赖Xlib。0.9.26 这个版本没有引入后续版本里那些对 Python 3.10 的强制要求所以在一些还在跑 Python 3.7/3.8 的老环境里反而更省心。我一般会先看setup.py里的install_requires确认它只依赖pymsgbox、pytweening、pyscreeze这几个小包没有隐藏的编译依赖。如果你是在内网离线环境部署这个 zip 包可以直接pip install本地路径不用去外网拉 wheel。2.2 安装与依赖检查安装方式有两种直接解压后进目录跑pip install .或者用pip install PyAutoGUI-0.9.26.zip。我习惯先建一个干净的虚拟环境避免和系统里已有的pyautogui冲突。# 创建虚拟环境Python 版本建议 3.7 到 3.9 python -m venv venv_auto # Windows 激活 venv_auto\Scripts\activate # macOS/Linux 激活 source venv_auto/bin/activate # 从本地 zip 安装 pip install PyAutoGUI-0.9.26.zip # 验证安装和版本 python -c import pyautogui; print(pyautogui.__version__)这里有个细节pip install本地 zip 时pip 会自动解压并执行setup.py但不会把 zip 里的tests/装进 site-packages。如果你需要跑测试用例得手动解压后进目录执行python -m pytest tests/。另外macOS 上第一次运行会弹辅助功能权限申请必须去“系统偏好设置 → 安全性与隐私 → 辅助功能”里勾选你的终端或 IDE否则所有鼠标键盘调用都会静默失败——这个坑后面还会细说。2.3 第一次移动鼠标确认坐标体系PyAutoGUI 的坐标原点在屏幕左上角x 向右递增y 向下递增。多显示器环境下主显示器左上角是 (0,0)副屏坐标可能是负数或超出主屏分辨率。先跑一个最简单的脚本把鼠标移到屏幕中心再移回左上角确认库能正常工作。import pyautogui import time # 获取屏幕分辨率 width, height pyautogui.size() print(f屏幕分辨率: {width}x{height}) # 移动鼠标到屏幕中心duration 控制移动耗时秒 pyautogui.moveTo(width // 2, height // 2, duration0.5) # 获取当前鼠标位置 x, y pyautogui.position() print(f当前鼠标位置: ({x}, {y})) # 移回左上角附近避免挡住后续操作 pyautogui.moveTo(10, 10, duration0.3)moveTo的duration参数很关键设成 0 是瞬间跳过去有些应用会检测不到鼠标事件设成 0.2 到 0.5 之间比较像真人操作。pyautogui.size()返回的是主显示器分辨率如果你有副屏且需要跨屏操作得用pyautogui.getAllScreens()或者直接硬编码坐标。第一次跑完这个脚本如果鼠标没动先检查权限再检查是不是在远程桌面里——有些远程协议会拦截本地输入模拟。3. 鼠标键盘核心操作参数怎么设才不翻车3.1 点击、拖拽与滚轮坐标和按钮的坑点击用pyautogui.click(x, y, buttonleft)不传坐标就点当前位置。拖拽用pyautogui.dragTo(x, y, duration1, buttonleft)注意dragTo是从当前位置拖到目标位置而dragRel是相对拖拽。滚轮用pyautogui.scroll(clicks)正数向上滚负数向下滚但不同系统上“一格”对应的像素数不一样Windows 上通常 120 像素一格macOS 上更细碎。import pyautogui # 双击某个位置interval 是两次点击间隔 pyautogui.doubleClick(x500, y300, interval0.1) # 右键点击 pyautogui.rightClick(x500, y300) # 从 (100,100) 拖到 (800,600)按住左键耗时 1.5 秒 pyautogui.moveTo(100, 100) pyautogui.dragTo(800, 600, duration1.5, buttonleft) # 向下滚动 5 格 pyautogui.scroll(-5)拖拽最容易翻车的地方是duration太短有些应用尤其是基于 Web 的表格或画布需要连续的mousemove事件才能识别拖拽如果 duration 设成 0它只收到一个mousedown和一个mouseup中间没有移动轨迹就会当成普通点击。我一般把拖拽 duration 设在 0.8 到 2 秒之间并且拖拽前先moveTo到起点让系统有时间处理鼠标进入事件。3.2 键盘输入与热键write 和 press 的区别pyautogui.write(hello)是逐字符模拟按键只支持单字符键不能输入中文。pyautogui.press(enter)是按下再松开一个键。组合键用pyautogui.hotkey(ctrl, c)它会按顺序按下所有键再逆序松开。如果要输入中文得用pyautogui.write配合剪贴板或者直接用pyperclip复制粘贴。import pyautogui import pyperclip # 输入英文和数字 pyautogui.write(Hello World 123, interval0.05) # 按下回车 pyautogui.press(enter) # 组合键全选、复制 pyautogui.hotkey(ctrl, a) pyautogui.hotkey(ctrl, c) # 输入中文先复制到剪贴板再粘贴 pyperclip.copy(这是一段中文文本) pyautogui.hotkey(ctrl, v)write的interval参数控制每个字符之间的延迟默认是 0但有些应用比如远程桌面或虚拟机里的输入框处理太快会丢字符设成 0.03 到 0.1 比较稳。hotkey里修饰键的顺序无所谓但建议按ctrl、alt、shift、win的顺序写可读性好。注意 macOS 上ctrl要换成commandpyautogui会自动映射但如果你写死了ctrl在 mac 上就会变成右键菜单。3.3 截图定位locateOnScreen 的精度与性能PyAutoGUI 最实用的功能之一是locateOnScreen给一张小图它在屏幕上找匹配区域返回中心坐标。底层用的是pyscreeze默认容差是 0像素级精确匹配实际用的时候几乎不可能精确匹配因为渲染有抗锯齿、颜色有偏差。import pyautogui # 在屏幕上找目标图片confidence 需要 opencv-python 支持 try: location pyautogui.locateOnScreen(button.png, confidence0.8) if location: center pyautogui.center(location) pyautogui.click(center) else: print(未找到目标) except pyautogui.ImageNotFoundException: print(截图匹配失败)confidence参数需要额外安装opencv-python不装的话只能精确匹配。0.8 到 0.9 是比较常用的范围太低会误匹配太高会找不到。locateOnScreen在大屏幕上很慢因为它要逐像素扫描我一般先用locateAllOnScreen看有没有多个匹配或者把搜索区域用region参数限定在窗口范围内能快好几倍。4. 避坑与排查那些让我重跑脚本的瞬间4.1 权限与安全软件拦截现象脚本在本地跑得好好的换一台机器或者换一个用户账户所有鼠标键盘操作全部无效也不报错。原因Windows 的 UAC 或 macOS 的辅助功能权限没有授予给执行脚本的进程。macOS 上尤其严格终端、IDE、Python 解释器分别需要单独授权。解决Windows 上以管理员身份运行终端或者在“隐私和安全性 → 辅助功能”里把对应程序加进去。macOS 上去“系统偏好设置 → 安全性与隐私 → 辅助功能”勾选终端和 IDE改完重启终端。4.2 坐标偏移与多显示器现象在开发机上坐标是对的部署到另一台机器上点到了错误的位置。原因屏幕分辨率不同或者任务栏位置、缩放比例DPI不一样。Windows 上 125% 缩放会让pyautogui.size()返回逻辑分辨率但实际鼠标坐标是物理像素两者对不上。解决脚本里不要硬编码绝对坐标尽量用locateOnScreen找图。如果必须用坐标先跑一个校准脚本打印pyautogui.size()和实际屏幕分辨率确认缩放比例。多显示器场景下用pyautogui.getAllScreens()获取每个屏幕的边界。4.3 截图匹配失败颜色、缩放与动态内容现象locateOnScreen一直返回None但肉眼明明能看到目标。原因截图时的系统主题、字体渲染、窗口透明度变了或者目标按钮有 hover 效果、动画。另外如果截图是在 100% 缩放下截的目标机器是 125% 缩放图片会被拉伸匹配不上。解决截图时用pyautogui.screenshot(region(x, y, w, h))只截目标区域减少干扰。匹配时加confidence0.7到0.85并安装opencv-python。如果目标有动态效果先移动鼠标到目标附近触发 hover等 0.5 秒再截图匹配。4.4 脚本跑飞了怎么紧急停止现象脚本进入死循环鼠标疯狂点击键盘乱按根本停不下来。原因循环里没有退出条件或者locateOnScreen一直找不到目标导致无限重试。解决PyAutoGUI 内置了故障安全机制把鼠标猛地移到屏幕左上角0,0会触发pyautogui.FailSafeException并终止脚本。但这个机制默认是开启的如果你在代码里设了pyautogui.FAILSAFE False就失去了这个后悔药。我一般会在循环里加一个计数器超过 N 次就sys.exit()并且永远不关 FAILSAFE。4.5 输入法冲突与中文输入现象pyautogui.write输入英文时输入法突然弹出来把字符变成了中文候选。原因系统默认输入法是中文write模拟的按键被输入法拦截了。解决脚本开头用pyautogui.hotkey(shift)或者pyautogui.press(esc)切换到英文输入法或者直接用pyperclip复制粘贴中文绕过键盘模拟。更稳妥的做法是在自动化开始前用pyautogui.hotkey(win, space)切换到英文键盘布局。5. 进阶技巧用截图定位 重试机制写一个稳定录入脚本前面把基础操作和坑都过了一遍最后落到一个实际能跑的模板上。假设你要从一个 Excel 里读数据逐条录入到一个老客户端里客户端界面固定但偶尔会弹确认框。核心思路是用locateOnScreen定位输入框和按钮用pyperclip粘贴中文用重试机制处理弹窗。import pyautogui import pyperclip import time import sys # 全局设置每次操作后暂停 0.3 秒给界面响应时间 pyautogui.PAUSE 0.3 # 保持故障安全开启 pyautogui.FAILSAFE True def find_and_click(image_name, confidence0.8, retries3): 在屏幕上找图并点击中心失败重试 for i in range(retries): try: location pyautogui.locateOnScreen(image_name, confidenceconfidence) if location: center pyautogui.center(location) pyautogui.click(center) return True except pyautogui.ImageNotFoundException: pass time.sleep(0.5) print(f找不到目标: {image_name}) return False def input_text(text): 用剪贴板输入文本支持中文 pyperclip.copy(text) pyautogui.hotkey(ctrl, v) time.sleep(0.2) # 主流程 records [记录001, 记录002, 记录003] # 实际从 Excel 读取 for idx, record in enumerate(records): print(f处理第 {idx1} 条: {record}) # 1. 点击输入框 if not find_and_click(input_box.png): sys.exit(输入框定位失败终止) # 2. 清空并输入 pyautogui.hotkey(ctrl, a) input_text(record) # 3. 点击提交按钮 if not find_and_click(submit_btn.png): sys.exit(提交按钮定位失败终止) # 4. 处理可能的确认弹窗 time.sleep(0.5) if pyautogui.locateOnScreen(confirm_dialog.png, confidence0.8): pyautogui.press(enter) # 5. 等待界面回到初始状态 time.sleep(1) print(全部录入完成)这个模板里几个关键点PAUSE全局延迟比在每个操作后面写time.sleep更干净find_and_click封装了重试避免因为界面卡顿导致一次找不到就崩input_text用剪贴板绕开了中文输入法问题每条记录处理完等 1 秒给客户端刷新时间。实际跑的时候我会先把records换成从openpyxl读 Excel 的代码并且在循环里加一个try...except捕获FailSafeException这样鼠标甩到左上角就能安全退出。还有一个技巧如果客户端窗口位置会变可以在脚本开头用pyautogui.getWindowsWithTitle(窗口标题)拿到窗口对象然后window.activate()把它置顶再用window.left、window.top算出相对坐标。不过 0.9.26 的窗口控制接口在 Windows 上比较稳macOS 上支持有限跨平台的话还是用截图定位更省心。从那以后我每次写自动化脚本都会先在目标机器上跑一遍“坐标校准 截图匹配测试”确认权限、缩放、输入法都没问题再上正式数据。希望帮到你。本文还有配套的精品资源点击获取