先说一个核心判断：用 pyautogui 做自动化，90% 的“翻车”都不是代码逻辑的问题，而是你对坐标系、图像匹配、输入法和系统权限这四个底层机制的了解还不够。很多新手上来就照着教程敲 click() 和 typewrite()，结果发现鼠标点不准、图片找不到、中文输不了、脚本动不动就自己退出——这其实不是 pyautogui 不好用，而是它运行的“环境”压根没对齐。
下面把这四个最容易出问题的环节拆开讲清楚，每个地方都直接给结论和可落地的调试方法。
pyautogui.click() 点不到目标位置？先确认坐标系和缩放比例
如果你在 macOS 或者高分屏 Windows 上运行 pyautogui.click()，发现总是偏位，那大概率不是代码写错了，而是系统 UI 缩放搞的鬼。pyautogui 读取的是物理像素坐标，但系统可能以 200% 缩放渲染界面，结果就是你用截图工具量出来的“100, 200”，在 pyautogui 里其实得传 (50, 100)（缩放 2 倍时）。
- Windows：去「显示设置 → 缩放与布局」看一眼，如果不是 100%，就得手动折算坐标，或者先用
pyautogui.size()校验当前有效分辨率，再配合pyautogui.FAILSAFE = False试跑一遍。 - macOS：如果你开启了「显示器 → 默认缩放」中的“更多空间”模式，Retina 像素翻倍就会让
pyautogui.position()返回的是逻辑坐标，但locateOnScreen()匹配的是物理图像——这就容易出问题。解决办法是：截图时关闭模糊和动画效果，并且用confidence=0.9来匹配。 - 调试技巧：运行脚本前先加一句
print(pyautogui.position())，把鼠标悬停在目标按钮上，看输出坐标和你量出来的是否一致。不一致，就说明缩放干扰了。
locateOnScreen() 找不到按钮图片？图像匹配比你想的更脆弱
pyautogui.locateOnScreen() 不是 OCR，它只做灰度模板匹配。只要按钮的背景色、字体抗锯齿、阴影、甚至动效帧稍微不同，匹配就直接失败。这一点必须提前有心理准备。
- 截图必须来自同一台机器、同一分辨率、同一缩放、同一主题（比如深色模式下按钮颜色变了，就得重新截图）。
- 避免截到窗口边框或阴影——用画图工具裁剪干净，保存为 PNG，不要用 JPEG（压缩噪点会干扰匹配）。
- 可以加
confidence=0.8来缓解轻微失真，但别低于 0.7，否则误匹配概率会飙升。如果目标和背景亮度区分明显，配合grayscale=True既能提速又能略微提升稳定性。 - 如果按钮上的文字会变（比如“提交 (3)”、“提交 (4)”），别截整个按钮，只截图标或固定文字部分，再用
region=(x, y, w, h)锁定搜索范围，能大幅减少干扰。
键盘输入中文乱码或卡住？pyautogui.typewrite() 不走系统输入法
pyautogui.typewrite() 发送的是键码（keycode），不是文本流。它能敲 a、enter、ctrl+v，但没法让微信或钉钉弹出中文输入法候选框——输入法进程根本不接收它的事件。很多人在这一步卡住，然后怀疑 pyautogui 的中文支持有问题，其实方向就错了。
- 纯英文/数字场景：放心用
pyautogui.typewrite("hello123")，加interval=0.1防止速度太快导致丢键。 - 需要中文：必须绕道走系统剪贴板。先用
pyperclip.copy("你好")把内容复制到剪贴板，再聚焦目标窗口，然后pyautogui.hotkey("ctrl", "v")粘贴进去。这是目前最稳妥的方式。 - 注意焦点：
pyautogui.typewrite()前务必确保目标窗口已激活，否则键会发到后台去。可以用pyautogui.getWindowsWithTitle("微信")配合.activate()来激活窗口（Windows/macOS 12+ 支持有限，建议用pygetwindow补足）。
脚本一运行就鼠标乱跳？FAILSAFE 触发和权限问题最常被忽略
pyautogui 默认开启 FAILSAFE 机制：一旦鼠标移到左上角 (0, 0)，会立刻抛出 FailSafeException 并中断脚本。这本来是安全设计，但新手常因为手抖、远程桌面缩放错乱、多显示器拖拽误触，导致脚本“莫名退出”。
- 开发阶段可以临时关闭：
pyautogui.FAILSAFE = False，但上线前务必重新打开，否则鼠标失控时可能点穿重要对话框。 - macOS 上：首次运行会弹出“辅助功能权限”提示，必须手动去「系统设置 → 隐私与安全性 → 辅助功能」里勾选你的 Python 进程（不是 Terminal.app，而是 python 或 pycharm 的具体路径）。
- Linux（X11）：需要确保
DISPLAY环境变量正确，Wayland 下基本不可用——别在 Ubuntu 22.04+ 的默认桌面试，老老实实换 Xorg 会话，或者改用xdotool。
坐标的物理性、图像的脆弱性、输入法的隔离性、系统的权限墙——这四个地方，但凡有一个没对齐，再熟的 API 也会表现得像抽风。调的时候别急着改逻辑，先盯死这四点。
