简介Selenium 3.141.0 离线安装包属于 Python 生态中浏览器自动化测试与爬虫辅助的核心库可驱动 Chrome、Firefox 等主流浏览器实现网页操作、数据采集与回归测试专为因网络波动而无法顺利在线安装的爬虫工程师、自动化测试人员及 Web 开发者准备。压缩包共 104 个文件以 86 个 py 模块源文件为主体另含少量 txt、js、so、pkg-info 等辅助文件——py 文件承载库的主要功能逻辑pkg-info 与 cfg 记录版本和安装元数据js、so 文件用于 WebDriver 底层驱动支持整包体积仅 905KB轻量易携。下载后解压即可在本机完成离线安装部署彻底规避在线安装反复中断、官网源码下载缓慢的痛点尤其适合网络受限或对安装成功率要求较高的开发场景。此外资源包目录结构简洁清晰便于快速核对文件完整性。目前已有 2130 人学习下载对该版本有明确依赖或需要快速搭建自动化环境的读者可直接选用。1. 为什么要死守 selenium 3.141.0旧版本依然能打的场景如果你的手边还留着selenium-3.141.0.zip这个安装包大概率是吃过新版本 API 迁移的亏。Selenium 3.141.0 是 Selenium 3.x 这条线的收尾版本之后官方直接跳到 4.x很多老代码用的find_element_by_id、find_element_by_xpath这一套方法在 4.x 里被标为弃用代码一跑就告警刷屏严重的直接改成find_element(By.ID, ...)的写法被迫重写。而这个 3.141.0 版本恰好卡在「功能完整、API 稳定、存量教程最多」的甜蜜点是很多遗留自动化项目的离线安装首选。这篇笔记就围绕这个 zip 包展开怎么装、怎么配驱动、怎么写第一个能跑的脚本、哪些坑我踩过。适合三类人——维护老测试脚本的、给内网环境离线装 Selenium 的、以及不想被 4.x API 变更折腾的初学者。2. 从 zip 到能跑的浏览器自动化安装与第一个连接2.1 安装方式一标准安装命令与离线安装的取舍拿到selenium-3.141.0.zip最省事的方式是解压后直接用setup.py安装。这个 zip 是源码包里面是 Selenium 的 Python 客户端源码不能用pip install selenium-3.141.0.zip直接装要先解压再执行安装脚本。# 解压源码包 unzip selenium-3.141.0.zip cd selenium-3.141.0 # 用 setuptools 安装到当前 Python 环境 python setup.py install这条命令会把这个版本的 Selenium 装进当前 Python 解释器的 site-packages 里。如果你用的是虚拟环境先进虚拟环境再执行否则会装到全局环境污染系统 Python。我一般会顺手验证一下安装结果python -c from selenium import webdriver; print(webdriver.__version__)能打印出3.141.0就说明装好了。另一种方式是pip install selenium3.141.0适合有外网的机器离线场景下上面这种解压安装是最稳的不需要编译也不需要额外依赖装完就能用。缺点是卸载麻烦得手动删 site-packages 里的selenium目录但多数人不会频繁卸这个包。2.2 驱动与浏览器的版本匹配第一时间踩平Selenium 3.141.0 本身只是控制脚本真正打开浏览器窗口、执行操作的是浏览器的 WebDriver 驱动。Chrome 用 chromedriverFirefox 用 geckodriver版本对不上启动脚本时直接报SessionNotCreatedException这是新手最先遇到的坑。版本对应关系大致是这样Selenium 3.141.0 官方支持到 Chrome 75 左右的版本如果你的浏览器比这新需要找匹配的驱动版本。常见做法是去对应浏览器的驱动发布页下载然后把驱动文件放到系统 PATH 里或者直接用绝对路径指定位置。浏览器驱动文件常见错误提示Chromechromedriver(.exe)SessionNotCreatedException: This version of ChromeDriver only supports Chrome version XXFirefoxgeckodriver(.exe)WebDriverException: Message: Expected browser binary location, but binary was not foundEdge (旧版)MicrosoftWebDriver.exeWebDriverException: Unable to find a matching set of capabilities我一般习惯把驱动放到venv/bin/或C:\tools\这类固定目录然后在代码里写死路径避免系统 PATH 被污染。Windows 上还要注意用.exe后缀Linux/macOS 上要给驱动文件加执行权限chmod x geckodriver2.3 第一个连接脚本验证环境可用环境配好后写一个最小脚本验证 Selenium 能拉起浏览器并执行 JavaScript。这个脚本能跑通后面大部分问题都有迹可循。from selenium import webdriver # 指定驱动路径避免 PATH 问题 driver webdriver.Chrome(executable_path/path/to/chromedriver) try: driver.get(https://example.com) title driver.title print(页面标题:, title) assert title Example Domain finally: driver.quit()这段代码做了三件事初始化 Chrome 驱动、打开测试页面、读取页面标题并断言。executable_path参数在 Selenium 3.141.0 里是合法的到了 4.x 被移除了这也是很多老脚本升级后报错的原因之一。driver.quit()放在finally里是习惯确保浏览器进程被回收不残留僵尸进程。3. 页面自动化实战定位、交互、等待三板斧3.1 元素定位7 种基础定位器与 CSS 选择器提速Selenium 3.141.0 的定位 API 是一套完整的体系按优先级我一般这样排id最优先、name其次、CSS_SELECTOR第三、XPath兜底。id 是页面元素的唯一标识速度快且稳定没有 id 就用 name都没有才上 CSS 或 XPath。from selenium import webdriver from selenium.webdriver.common.by import By driver webdriver.Chrome(executable_path/path/to/chromedriver) driver.get(https://example.com/login) # 7 种基础定位方式 driver.find_element_by_id(username) driver.find_element_by_name(password) driver.find_element_by_class_name(btn-login) driver.find_element_by_tag_name(form) driver.find_element_by_link_text(注册账号) driver.find_element_by_partial_link_text(注册) driver.find_element_by_xpath(//*[idusername])这套 API 在 3.141.0 里全部可用但要注意它们返回第一个匹配的元素如果没有匹配会直接抛NoSuchElementException。定位时如果页面里的元素是动态渲染的还没加载完就定位十有八九会失败。定位策略的选择直接影响脚本稳定性能用 id 不要用 XPathXPath 写得太长前端一改页面就崩。3.2 交互操作点击、输入、下拉框与文件上传定位到元素之后交互操作是下一步。模拟用户行为最常用的就是click()和send_keys()但下拉框和文件上传这两类交互有专门的处理方式。from selenium.webdriver.support.ui import Select # 1. 普通输入 点击 username_input driver.find_element_by_id(username) username_input.send_keys(tester01) password_input driver.find_element_by_name(password) password_input.send_keys(pass123) driver.find_element_by_class_name(btn-login).click() # 2. 下拉框选择 select Select(driver.find_element_by_id(city)) select.select_by_value(beijing) select.select_by_visible_text(北京) select.select_by_index(2) # 3. 文件上传直接传本地绝对路径 upload_btn driver.find_element_by_id(uploadFile) upload_btn.send_keys(/home/user/test_case.xlsx)send_keys不只是输入文本对于input typefile控件它会模拟在文件选择框里输入路径的操作绕过 Windows 的弹窗这是最稳定的文件上传方案。下拉框用Select类包装之后select_by_value和select_by_visible_text是两种最常用的选法前者按 value 属性选后者按显示文本选。注意select_by_index的索引从 0 开始不是从 1 开始不少人对这个翻过车。3.3 等待策略隐式等待与显式等待的边界动态页面是自动化脚本最大的敌人。早期很多脚本跑着跑着突然挂了50% 是元素没加载出来。Selenium 3.141.0 提供两种等待机制我简单说下区别implicitly_wait()是全局隐式等待设置一次之后每次find_element都会轮询等待指定时间直到元素出现或超时。WebDriverWait是显式等待配合expected_conditions使用只对某个特定条件生效控制更精细。from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC from selenium.webdriver.common.by import By # 隐式等待全局兜底 driver.implicitly_wait(10) # 显式等待等登录按钮可点击最长 15 秒 login_btn WebDriverWait(driver, 15).until( EC.element_to_be_clickable((By.CLASS_NAME, btn-login)) ) login_btn.click() # 等待某个元素消失常用于加载遮罩层 WebDriverWait(driver, 10).until( EC.invisibility_of_element_located((By.ID, loading-mask)) )显式等待的核心思路是「等到能操作为止」而不是固定睡几秒。element_to_be_clickable不仅检查元素存在还检查可见和可点击状态presence_of_element_located只检查存在不检查可见两者适用场景不一样。4. 避坑记录Selenium 3.141.0 的 5 条血泪经验4.1 现象NoSuchElementException找不到元素定位一个元素明明页面上能看到脚本却报找不到。这种情况在登录页和列表页最常见。原因通常是三点元素在 iframe 里、元素在 Shadow DOM 里、或页面是异步渲染的定位时元素还没出现。iframe 的问题最隐蔽因为 Selenium 默认只查找顶层文档不主动进入 frame。解决方式先检查页面里有没有 iframe有的话先切换进去操作完再切出来。异步渲染的用显式等待不要用time.sleep()那个是玄学。# 切换到 iframe driver.switch_to.frame(driver.find_element_by_tag_name(iframe)) # 操作完切回主文档 driver.switch_to.default_content()4.2 现象WebDriverException: Message: unknown error: DevToolsActivePort file doesnt exist脚本启动 Chrome浏览器窗口没弹出来直接报这个错。大部分情况是 Chrome 和 chromedriver 版本不匹配新版 Chrome 需要新版驱动而 Selenium 3.141.0 配套的旧驱动对话机制有时跟不上。也可能是 Chrome 的沙箱权限问题特别是在容器或 CI 环境里。解法是加启动参数禁用沙箱和旧的 DevTools 协议冲突from selenium import webdriver options webdriver.ChromeOptions() options.add_argument(--no-sandbox) options.add_argument(--disable-dev-shm-usage) driver webdriver.Chrome(executable_path/path/to/chromedriver, optionsoptions)--no-sandbox会降低浏览器安全级别只推荐在隔离的测试环境里用。4.3 现象StaleElementReferenceException元素过期代码里已经把元素对象拿出来了点击的时候报元素过期。原因是元素对象是页面刚渲染时定位到的但页面经过局部刷新这个元素被重新创建了原来的引用失效。解决方式是重新获取元素。不要把find_element的返回值存成变量复用多次每次操作前都重新定位一次。如果循环里操作一组元素要特别注意这个坑。# 循环里每次重新定位 for i in range(len(driver.find_elements_by_class_name(row)): row driver.find_elements_by_class_name(row)[i] row.click()4.4 现象点击登录按钮没反应也不报错按钮明明定位到了click()执行完但页面没有跳转。这种坑最难受因为没有任何报错信息可以查。原因一般是按钮被某个元素遮住了或者按钮本身有禁用的样式但属性没更新。解决方式两个一个是改用element_to_be_clickable等显式条件另一个是使用 JavaScript 强制点击绕过遮挡物from selenium.webdriver.common.by import By from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC btn WebDriverWait(driver, 10).until( EC.element_to_be_clickable((By.CLASS_NAME, btn-login)) ) # JavaScript 直接触发 click 事件 driver.execute_script(arguments[0].click();, btn)execute_script能直接执行 JS 代码用来处理一些罕见的点击困境但不能滥用能用原生click()还是用原生的。4.5 现象循环跑测试跑到中途突然浏览器崩了自动化脚本在长时间循环里的稳定性是另一个大坑。表现是脚本跑了几十轮之后浏览器进程内存暴涨或驱动连接断掉quit()没生效。原因一是没清理浏览器进程driver.quit()只关闭主进程有些子进程残留原因二是日志文件无限增长。解决方式每次循环结束强制关闭浏览器进程并清理临时文件。Windows 上用taskkillLinux/macOS 用pkill# Windows taskkill /F /IM chromedriver.exe /T # Linux/macOS pkill -f chromedriver另外可以定期重启驱动每跑一定轮数就quit()后重新初始化是实践下来最稳定的长跑方案。5. 用无头模式从头验证脚本稳定性一条命令跑通全流程手动测试和自动化测试的最大区别是自动化要能无人值守地跑。Selenium 3.141.0 支持无头模式就是浏览器不显示窗口在后台运行页面。无头模式的优势是节省资源、跑得快适合当脚本稳定性的最终验证手段。from selenium import webdriver from selenium.webdriver.chrome.options import Options options Options() options.add_argument(--headless) options.add_argument(--window-size1920,1080) options.add_argument(--disable-gpu) options.add_argument(--no-sandbox) driver webdriver.Chrome(executable_path/path/to/chromedriver, chrome_optionsoptions) driver.get(https://example.com) print(driver.title) driver.quit()--window-size比较关键。无头模式下默认窗口尺寸很小页面布局可能是移动端样式会影响元素的可点击性。强制设置 1920x1080 之后桌面版布局和元素位置才跟有头模式一致。--disable-gpu是传统保留参数在部分 Linux 环境不加会报错。无头模式验证脚本稳定性我一般这么操作把脚本从「打开浏览器→执行用例→关闭浏览器」整段套上循环跑 20 轮观察有没有偶发失败。有失败就定位是哪一步一般逃不出前面说的四种异常。有头模式跑正常的脚本无头模式跑压力验证。import time from selenium import webdriver def run_case(): options webdriver.ChromeOptions() options.add_argument(--headless) driver webdriver.Chrome(executable_path/path/to/chromedriver, optionsoptions) try: driver.get(https://example.com) time.sleep(2) assert driver.title return True except Exception as e: print(f失败: {e}) return False finally: driver.quit() # 连跑 20 轮验证稳定性 passed 0 for i in range(20): if run_case(): passed 1 print(f通过率: {passed}/20)这套无头模式验证脚本是我每次改完定位逻辑之后强制走的流程。从那以后我每次迁移环境或换驱动版本都会先跑一遍这套 20 轮无头验证再跑有头确认布局最大程度上避免了「本地能跑、放到服务器上就崩」的尴尬。希望帮到你。本文还有配套的精品资源点击获取