1. 项目概述一个典型的Appium连接困局如果你正在用Python写Appium自动化测试脚本并且已经成功启动了Appium Server但在脚本执行到driver webdriver.Remote()这一行时控制台突然抛出一个红色的错误信息Failed to establish a new connection: [WinError 10061] 由于目标计算机积极拒绝无法连接。那么恭喜你你遇到了Appium自动化测试入门路上一个非常经典也足够让人抓狂的“拦路虎”。这个错误的核心是你的Python客户端脚本尝试去和Appium Server建立网络连接但Appium Server那边“大门紧闭”直接拒绝了这次握手。对于新手来说这个错误信息往往让人一头雾水因为它指向了一个宽泛的网络问题但根源却可能藏在环境配置、启动参数、端口占用等各个角落。我处理过无数次类似的报错从个人经验来看WinError 10061在Appium语境下几乎可以等价于“客户端找不到服务端”。这就像你按照地址去朋友家做客但到了却发现要么门牌号不对要么朋友根本没在家要么他把门反锁了。解决这个问题的过程就是一个系统性的“侦探”工作需要你逐一排查地址IP和端口、主人状态Appium Server进程、以及敲门方式Desired Capabilities配置是否正确。本文将基于一个Python Appium的典型测试场景为你彻底拆解这个错误的成因并提供一套从简到繁、步步为营的排查与解决方案。无论你是刚入门Appium自动化测试的新手还是偶尔被此问题困扰的熟手这份“排错指南”都能帮你快速定位问题恢复测试流程。2. 核心原理与错误根源深度解析2.1 “积极拒绝”背后的网络通信模型要理解WinError 10061我们得先搞清楚Appium的工作模型。Appium遵循标准的客户端-服务器Client-Server架构服务器端 (Server)即appium主进程。它启动后会监听一个特定的网络端口默认是4723等待来自客户端的连接请求。你可以把它想象成一个提供“设备操控服务”的餐厅。客户端 (Client)即你的Python测试脚本使用selenium库中的webdriver.Remote类。它的职责是向服务器发起连接并发送一系列指令即Desired Capabilities告诉服务器“我想在哪个设备上打开哪个App进行什么操作”。这就像顾客根据餐厅地址找上门并点餐。Failed to establish a new connection: [WinError 10061] 由于目标计算机积极拒绝无法连接。这个错误发生在TCP/IP协议栈的“三次握手”阶段。当客户端向服务器指定的IP和端口发送SYN包请求连接时如果服务器端根本没有程序在监听那个端口操作系统内核会直接回一个RST包重置连接客户端收到后就会报告“连接被拒绝”。所谓“积极拒绝”就是指目标端口有响应回了RST而不是网络不通超时无响应。所以这个错误明确告诉我们客户端找对地方了IP可达但那个“门”端口后面没有我们要找的“服务生”Appium Server进程。2.2 导致“服务生不在岗”的五大常见原因根据我的排查经验导致Appium Server“不在岗”或“不认你”的原因主要可以归结为以下五类排查时也建议按此顺序进行Appium Server未启动或启动失败这是最直接的原因。你根本没有运行appium命令或者运行后因为环境问题如Node.js版本、依赖缺失导致进程异常退出。端口号不匹配客户端代码里指定的端口号如127.0.0.1:4723与Appium Server实际监听的端口号不一致。你可能改了默认端口但代码没改或者端口被其他程序占用了。主机地址Host错误在非本地执行时如脚本在机器AAppium Server和设备在机器B客户端代码中指定的主机IP地址不正确无法路由到运行Appium Server的机器。Appium Server启动参数限制启动Appium Server时使用了--address或--port参数但参数设置与客户端连接意图不匹配。例如--address 127.0.0.1会导致Server只接受来自本机的连接如果客户端用局域网IP连接就会被拒绝。防火墙或安全软件拦截系统防火墙、杀毒软件或公司网络策略阻止了本地回环地址127.0.0.1或特定端口4723的通信。这种情况在某些严格管控的企业环境中比较常见。注意很多人会混淆127.0.0.1和localhost。在绝大多数情况下它们都指向本机。但在某些系统如某些Windows配置了特定hosts文件或存在IPv6优先下localhost的解析可能会出问题。为了绝对可靠在代码中直接使用127.0.0.1是更推荐的做法。3. 系统性排查与解决方案实战遇到10061错误切忌盲目尝试。遵循一个系统的排查流程可以帮你最高效地解决问题。下面我将按照从外到内、从简单到复杂的顺序带你一步步操作。3.1 第一步基础检查——确认Appium Server状态这是所有排查的起点。打开你的命令行终端CMD, PowerShell, 或 Terminal。1. 检查Appium进程是否运行# 在Windows上查找包含‘appium’的进程 tasklist | findstr appium # 在macOS/Linux上 ps aux | grep appium如果没有任何输出说明Appium Server根本没有启动。你需要去启动它。2. 启动Appium Server并观察日志不要直接双击桌面图标如果有的话而是通过命令行启动这样你能看到所有输出日志这对于诊断启动失败至关重要。# 直接启动使用默认设置监听 0.0.0.0:4723 appium启动成功后你应该能看到类似以下的日志[Appium] Welcome to Appium v2.0.0 [Appium] Appium REST http interface listener started on 0.0.0.0:4723关键信息listener started on 0.0.0.0:4723。这表示Server正在0.0.0.0这个所有网络接口上监听4723端口可以接受来自任何IP地址的连接。如果启动失败日志会打印错误信息。常见问题有Node.js版本不兼容Appium 2.x 需要 Node.js 16。用node -v检查。依赖驱动未安装对于Android自动化你需要安装appium-uiautomator2-driver对于iOS需要appium-xcuitest-driver。可以通过appium driver install uiautomator2来安装。Java环境问题Android开发工具链ADB需要Java。确保JAVA_HOME环境变量已正确设置且java -version可以执行。3. 验证端口监听状态即使appium命令启动了也要确认它是否真的成功绑定了端口。# Windows 使用 netstat netstat -ano | findstr :4723 # macOS/Linux 使用 lsof 或 netstat lsof -i :4723 # 或 netstat -an | grep 4723如果端口4723被成功监听你会看到一条记录其中LISTENING状态表明正在监听。如果看不到说明Appium Server可能启动后立即崩溃了需要根据上一步的启动日志排查原因。3.2 第二步核对连接配置——客户端代码检查确保你的Python脚本中的连接地址与Appium Server的实际监听地址完全匹配。这是最常出错的环节。1. 检查Python连接代码from appium import webdriver from appium.options.common import AppiumOptions # 定义Desired Capabilities options AppiumOptions() options.load_capabilities({ platformName: Android, appium:platformVersion: 13, appium:deviceName: Android Emulator, appium:app: /path/to/your/app.apk, appium:automationName: UiAutomator2, appium:noReset: True }) # 重点关注这一行 # 尝试连接Appium Server driver webdriver.Remote(http://127.0.0.1:4723, optionsoptions)关键点分析协议必须是http://。虽然Appium也支持HTTPS但在本地测试中极少使用。主机地址 (Host)127.0.0.1代表本机。如果你的Appium Server运行在另一台电脑如一个专门的测试机上这里需要替换成那台电脑的局域网IP地址例如http://192.168.1.100:4723。端口 (Port)4723是Appium默认端口。如果你启动Appium时通过--port指定了其他端口如appium --port 4724这里必须同步修改。2. 处理复杂的启动场景场景A使用--address参数启动Appiumappium --address 127.0.0.1 --port 4723这种启动方式Appium Server只监听127.0.0.1这个回环地址。这意味着只有从本机发起的连接即Python脚本也在同一台机器才能成功。如果你试图从另一台机器用局域网IP连接会得到10061错误。解决方案如果不需要远程连接这样启动是安全的。如果需要远程连接应使用--address 0.0.0.0或直接不加此参数默认就是0.0.0.0。场景B端口被占用如果默认的4723端口已被其他程序可能是另一个Appium实例、或其他应用占用Appium Server会启动失败。你会看到类似Error: listen EADDRINUSE: address already in use :::4723的错误。解决方案关闭占用端口的进程通过netstat -ano | findstr :4723找到PID然后在任务管理器中结束。为Appium指定一个新端口启动appium --port 4724并相应修改Python代码中的连接地址为...:4724。3.3 第三步网络与系统环境深度排查如果前两步都没问题那么需要深入系统层面进行排查。1. 防火墙与安全软件检查尽管是本地回环通信127.0.0.1但某些过于“积极”的安全软件或Windows防火墙的某些规则可能会拦截。进行一个简单的测试临时完全关闭Windows Defender防火墙或你使用的第三方杀毒软件的网络防护功能然后重试。如果问题解决说明是防火墙的问题。你需要为Appium或Java因为Appium Server是Node.js应用但底层可能调用Java进程添加防火墙入站规则允许4723端口的TCP连接。2. 使用curl或浏览器进行快速测试在命令行中使用curl工具可以直接测试Appium Server的HTTP接口是否可达这比运行整个Python脚本更快捷。curl http://127.0.0.1:4723/wd/hub/status如果Appium Server正常运行且监听正确你会收到一个JSON格式的响应包含status: 0和一些版本信息。如果收到curl: (7) Failed to connect to 127.0.0.1 port 4723: Connection refused那就直观地证实了10061错误你需要回到第一步检查Server状态。如果没有curl也可以直接在浏览器地址栏输入http://127.0.0.1:4723/wd/hub/status。如果Server正常浏览器会显示JSON数据如果无法连接浏览器会显示“无法访问此网站”之类的错误。3. 检查主机文件 (Hosts File)极少数情况下系统的hosts文件位于C:\Windows\System32\drivers\etc\hosts被修改将localhost或127.0.0.1指向了错误的地址。用记事本以管理员身份运行打开这个文件确保没有异常的行将127.0.0.1重定向。通常这个文件除了注释外应该是空的或者只有一行127.0.0.1 localhost。3.4 第四步高级场景与疑难杂症处理1. 使用Appium Desktop或Inspector如果你同时在使用Appium Desktop带图形界面的Appium或Appium Inspector需要注意它们可能会启动自己内置的Appium Server并占用默认端口。确保你的Python脚本连接的是你意图中的那个Server实例。一个常见的冲突是用命令行启动了Appium Server在4723端口同时Appium Desktop也自动启动了一个Server在4723端口导致端口冲突。建议在调试阶段关闭Appium Desktop统一使用命令行管理Appium Server以减少不确定性。2. 公司代理或VPN影响如果你身处公司网络且系统设置了全局HTTP/HTTPS代理或者连接了VPN有时这些网络配置会干扰本地回环地址的通信。尝试暂时断开VPN并在系统设置中关闭代理“设置” - “网络和Internet” - “代理” - 关闭“使用代理服务器”然后重试。3. Python环境与库版本冲突虽然较少见但陈旧的selenium或appium-python-client库可能与新版的Appium Server存在兼容性问题。确保你的库是最新的pip install --upgrade selenium appium-python-client4. 一份可复现的完整工作流与示例代码为了让你有一个清晰的参照这里提供一个从零开始、确保能成功连接的最小化工作流和代码示例。工作流步骤环境准备确保已安装Node.js (16) Java JDK (8) Android SDK并设置好ANDROID_HOME和JAVA_HOME环境变量。安装Appiumnpm install -g appium。安装所需驱动appium driver install uiautomator2。启动设备启动Android模拟器如通过Android Studio的AVD Manager或连接真机并通过adb devices命令确认设备已识别。启动Appium Server打开一个命令行窗口执行appium。保持这个窗口打开观察日志。编写并执行Python脚本在另一个命令行窗口或IDE中运行下面的示例脚本。示例Python脚本 (test_connection.py):import time from appium import webdriver from appium.options.common import AppiumOptions from appium.webdriver.common.appiumby import AppiumBy def test_appium_connection(): 一个最小化的Appium连接测试脚本。 前提已启动Appium Server (默认端口4723)且有一个Android设备/模拟器可用。 # 1. 定义核心的Desired Capabilities # 这些参数告诉Appium你要在什么设备上测试什么应用 options AppiumOptions() options.load_capabilities({ # 平台必须是 Android 或 iOS platformName: Android, # 设备系统版本通过 adb shell getprop ro.build.version.release 获取 appium:platformVersion: 13, # 设备名称可以是任意字符串但用于日志区分。真机可通过 adb devices -l 查看model appium:deviceName: Pixel_6_Pro_API_33, # 自动化引擎Android通常用 UiAutomator2 appium:automationName: UiAutomator2, # 以下两项二选一 # A) 测试一个已安装的应用通过包名 # appium:appPackage: com.android.calculator2, # appium:appActivity: com.android.calculator2.Calculator, # B) 安装并测试一个APK文件提供绝对路径 # appium:app: rC:\Users\YourName\Downloads\your_app.apk, # 示例使用Android自带的计算器 appium:appPackage: com.android.calculator2, appium:appActivity: com.android.calculator2.Calculator, # 可选不重置应用数据避免每次测试都清空数据 appium:noReset: True, # 可选设置命令超时时间单位秒防止因设备慢导致失败 appium:newCommandTimeout: 60, }) # 2. 连接Appium Server # 这是最关键的连接行确保IP和端口与运行的Server一致 server_url http://127.0.0.1:4723 print(f正在尝试连接Appium Server: {server_url}) try: # 初始化驱动这会触发与Appium Server的HTTP连接 driver webdriver.Remote(server_url, optionsoptions) print(✅ 连接Appium Server成功) # 3. 一个简单的操作示例等待界面加载然后点击一个数字 time.sleep(2) # 等待应用启动 # 假设点击数字5根据实际计算器UI定位元素这里仅为示例 # 实际定位需要借助Appium Inspector获取 # digit_5 driver.find_element(AppiumBy.ID, com.android.calculator2:id/digit_5) # digit_5.click() print(执行简单的界面操作...) # 这里可以添加你的测试逻辑 # 4. 测试完成后等待几秒并退出 time.sleep(3) driver.quit() print(测试完成驱动已退出。) except Exception as e: # 捕获连接或其他异常 print(f❌ 连接或执行过程中发生错误{type(e).__name__}) print(f错误详情{e}) # 特别处理连接拒绝错误 if 10061 in str(e) or Connection refused in str(e): print(\n 疑似WinError 10061问题请按以下步骤排查) print(1. 确认Appium Server是否已在另一个终端窗口启动 (appium)。) print(2. 确认Server启动日志中显示 listener started on 0.0.0.0:4723。) print(3. 在浏览器中访问 http://127.0.0.1:4723/wd/hub/status看是否有JSON返回。) print(4. 检查Python代码中的 server_url 是否与Server监听的IP和端口一致。) print(5. 检查是否有防火墙或安全软件阻止了连接。) if __name__ __main__: test_appium_connection()执行与验证在一个终端运行appium。在另一个终端运行python test_connection.py。观察输出。如果看到“✅ 连接Appium Server成功”则大功告成。如果看到错误脚本最后的异常处理部分会给出针对性的排查提示。5. 常见问题排查速查表与避坑指南即使按照上述流程有时还是会遇到一些“诡异”的情况。下面这个表格总结了我遇到过的典型问题及解决方案你可以像查字典一样快速对照。问题现象可能原因排查步骤与解决方案运行appium命令后立即退出无成功日志1. Node.js版本过低。2. 必要的驱动未安装。3. 端口被占用。1.node -v检查版本需≥16。2.appium driver list查看已安装驱动未安装则用appium driver install uiautomator2安装。3. 换端口启动appium --port 4724或找出占用4723端口的进程并结束。Server日志显示启动成功但Python脚本报100611. 代码中IP/端口写错。2. Server用--address 127.0.0.1启动但脚本用局域网IP连接。3. 防火墙拦截。1. 核对代码webdriver.Remote()中的URL。2. 统一使用127.0.0.1:4723进行本地测试或Server用--address 0.0.0.0启动以接受远程连接。3. 临时关闭防火墙测试。adb devices能看到设备但Appium日志提示No devices connected1. Appium所需的设备信息与adb不一致。2. 设备未授权真机。3. 使用了旧版appium-adb驱动。1. 确保Desired Capabilities中的platformVersion和deviceName与设备匹配deviceName可任意但platformVersion必须准确。2. 真机上查看并点击“允许USB调试”授权框。3. 更新Appium及相关驱动到最新版。连接成功但在初始化会话时失败1. Desired Capabilities 配置错误如app路径不对、包名/Activity名错误。2. 设备系统版本与自动化驱动不兼容。1. 仔细检查app、appPackage、appActivity等参数值。对于已安装应用使用 adb shell dumpsys window脚本在webdriver.Remote()处长时间卡住最后超时1. Appium Server IP地址错误导致网络不可达。2. 设备响应极慢。1. 检查网络连通性ping server_ip。2. 在Capabilities中增加appium:newCommandTimeout: 120延长超时时间。使用模拟器时Appium无法安装测试服务器1. 模拟器系统镜像不带Google Play服务对于UiAutomator2是必须的。2. 模拟器磁盘空间不足。1. 在AVD Manager中创建模拟器时选择带有“Google Play”或“Google APIs”标签的系统镜像。2. 清理模拟器存储或创建一个新的模拟器。独家避坑技巧日志是你的最佳伙伴永远不要忽略Appium Server启动和运行时的控制台日志。错误信息、警告和堆栈跟踪都直接指向问题根源。养成启动Server后先扫一眼日志是否有红色错误信息的习惯。“最小化复现”原则当遇到问题时创建一个新的、最简单的测试脚本就像上面的示例只包含最基本的连接和打开应用操作。排除复杂业务逻辑的干扰能更快定位是环境问题还是脚本问题。固定你的环境在项目初期就记录下所有关键组件的版本号Node.js, Appium, Python库, 驱动版本设备系统版本。不同版本间可能存在兼容性问题。使用requirements.txt(Python) 和package.json(Node) 来管理依赖是个好习惯。善用appium-doctor这是一个官方提供的环境诊断工具。运行appium-doctor可以检查你的Android和iOS环境配置是否完整它会给出明确的修复建议。真机调试先授权使用Android真机调试时第一次连接电脑后手机屏幕上会弹出“允许USB调试吗”的授权对话框。务必点击“确定”否则adb devices会显示设备为unauthorizedAppium也无法连接。处理WinError 10061的过程本质上是对Appium工作原理和网络基础的一次实践性理解。每一次成功的排查都会让你对这套工具链的掌控更深一层。当你再看到这个错误时不再会是困惑和沮丧而是能冷静地打开终端按照“服务状态 - 连接配置 - 系统环境”的路径像侦探一样迅速找到那个被关上的“门”。