简介：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 selenium==3.141.0，适合有外网的机器；离线场景下，上面这种解压安装是最稳的，不需要编译，也不需要额外依赖，装完就能用。缺点是卸载麻烦，得手动删 site-packages 里的selenium目录，但多数人不会频繁卸这个包。

2.2 驱动与浏览器的版本匹配：第一时间踩平

Selenium 3.141.0 本身只是控制脚本，真正打开浏览器窗口、执行操作的是浏览器的 WebDriver 驱动。Chrome 用 chromedriver，Firefox 用 geckodriver，版本对不上，启动脚本时直接报SessionNotCreatedException，这是新手最先遇到的坑。

版本对应关系大致是这样：Selenium 3.141.0 官方支持到 Chrome 75 左右的版本，如果你的浏览器比这新，需要找匹配的驱动版本。常见做法是去对应浏览器的驱动发布页下载，然后把驱动文件放到系统 PATH 里，或者直接用绝对路径指定位置。

我一般习惯把驱动放到venv/bin/或C:\tools\这类固定目录，然后在代码里写死路径，避免系统 PATH 被污染。Windows 上还要注意用.exe后缀，Linux/macOS 上要给驱动文件加执行权限：

chmod +x geckodriver

2.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('//*[@id="username"]')

这套 API 在 3.141.0 里全部可用，但要注意它们返回第一个匹配的元素，如果没有匹配会直接抛NoSuchElementException。定位时如果页面里的元素是动态渲染的，还没加载完就定位，十有八九会失败。定位策略的选择直接影响脚本稳定性，能用 id 不要用 XPath，XPath 写得太长，前端一改页面就崩。

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 type="file">控件，它会模拟在文件选择框里输入路径的操作，绕过 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 doesn't 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', options=options)

--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 上用taskkill，Linux/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-size=1920,1080') options.add_argument('--disable-gpu') options.add_argument('--no-sandbox') driver = webdriver.Chrome(executable_path='/path/to/chromedriver', chrome_options=options) 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', options=options) 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 轮无头验证，再跑有头确认布局，最大程度上避免了「本地能跑、放到服务器上就崩」的尴尬。希望帮到你。

本文还有配套的精品资源，点击获取