Selenium环境配置安装全指南：从Python到ChromeDriver一次搞定

先聊个现象很多人第一次装 Selenium卡住的往往不是 Selenium 本身而是 Python、pip、浏览器驱动、环境变量这一连串“周边配置”。明明照着教程敲了pip install selenium一运行却报一堆错什么ModuleNotFoundError、chromedriver executable needs to be in PATH、This version of ChromeDriver only supports Chrome version xx。我见过太多人在这里折腾一整天最后发现是浏览器版本和驱动版本差了半个版本号。这篇文章就是把“Selenium 环境配置安装”这件事从头到尾捋一遍包括到底要先准备哪些东西、每一步为什么要这么干、装完之后怎么验证它真的能跑起来以及我把各种报错按“症状、原因、解法”整理成了一张速查表。如果你是要做自动化测试、爬虫采集、或者只是想用脚本替自己干点浏览器里的重复劳动这篇都能让你少走很多弯路。1. 动手之前先把概念理清楚1.1 Selenium 到底是什么环境里面都有谁Selenium 是自动化测试领域的老牌工具它最大的特点是直接驱动真实浏览器模拟真实用户的操作点击、输入、滚动、切页面、提交表单统统能跑。它不依赖 IE 时代的那些“假浏览器”而是让你用代码像真人一样去操控 Chrome、Edge、Firefox。但这里有一个新手普遍没搞懂的点Selenium 不是一个文件而是一套组合。它至少包含三部分Selenium 库本身就是你的 Python 代码里import selenium引用的东西浏览器驱动比如 ChromeDriver、EdgeDriver、GeckoDriver它是 Python 和浏览器之间的翻译官一个真实的可执行浏览器Chrome、Edge、Firefox 之一。打个比方Selenium 库相当于你的“指挥棒”浏览器驱动是那个会把你的指令传达到具体操作的“中间人”浏览器才是真正干活的人。你在命令行里pip install selenium只是把第一件装备装好了第二件驱动和第三件浏览器需要你单独准备。所以后面所有配置的核心思路就一句话让代码找得到驱动让驱动配得上浏览器让它俩能对上话。后面咱们所有的安装步骤其实都是在解决这三件事。1.2 为什么网上教程读得懂自己装却总报错因为市面上的教程往往默认了“你已经装好 Python”“你已经装好了 Chrome”“你用的是 Windows 并且没别的乱七八糟的环境”但实际每个人的电脑都是不一样的。尤其是这几类情况最让人头疼电脑里有两个 Python 版本pip和python用的不是同一个解释器浏览器开了自动更新昨天还好好的 ChromeDriver今天早上就废了驱动装到了某个文件夹但系统PATH里没有这个文件夹程序找不到公司内网的电脑装了安全软件浏览器驱动被隔离或者被拦截用 Mac 的朋友第一次跑的时候忘了给驱动赋可执行权限。这五条我全踩过。所以我这篇内容排的方式就是把每一步都拆开讲清楚它到底在干什么这样哪怕报错变了样你也能顺着根儿排查。2. 装 Python 是这一切的大前提2.1 版本选择与安装步骤别选太新的也别选太旧的。Selenium 4.x 对 Python 3.8 到 3.12 都支持得不错我更推荐大多数人装 Python 3.10 或 3.11稳定而且生态兼容性最好。3.13 发布得比较早但很多底层库还在追兼容没必要拿自己当小白鼠。Windows 用户直接去 Python 官网下载对应系统的安装包注意有两个最容易看漏的选项第一安装界面第一屏下面的Add Python to PATH一定要勾选这是新手最容易忽略的。不勾的话你开命令行敲python会提示“不是内部或外部命令”但其实 Python 已经装好了只是系统在 PATH 里面找不到它。第二建议选Customize installation进入后把pip装上不要只装 python 本体后面全靠 pip 了。装完验证一下。Windows 上打开 CMD输入python --version如果显示类似Python 3.10.x说明解释器已经能用了。Mac 用户要注意系统自带的可能是老版本 Python建议去官网下 macOS 的安装包装完命令行里用python3 --version来验证因为很多 Mac 上python命令指向的还是旧版而python3才指向你新装的解释器。2.2 pip 和虚拟环境比 Python 本体更容易被忽略pip 是 Python 自带的包管理工具类似于手机里头的“应用商店”。你执行pip install xxx它就去仓库里找这个包下载并装到当前环境。Selenium 就是通过它来安装的。但默认官方源偶尔会慢、会超时这不算什么稀奇事。解决办法是临时换一个国内镜像源比如清华源pip install selenium -i https://pypi.tuna.tsinghua.edu.cn/simple这个-i参数就是告诉 pip 去哪个“商店”拿货只对这一次安装生效不想每次都敲也可以配置成默认源。再说虚拟环境。这可能看起来像“多此一举”但确实是高手的习惯建议从第一天就养成如果你电脑里同时有爬虫项目、自动化测试项目、日常脚本项目每个项目可能依赖不同版本的同一个库全靠一套环境的话会互相打架——今天为了 A 项目装了一个新版本 Selenium明天 B 项目就因为版本不兼容跑不起来了。虚拟环境就是给每个项目开一个独立的小房间各装各的。创建和激活的流程是这样的# 在项目目录下执行 python -m venv venv # Windows 激活 venv\Scripts\activate # Mac / Linux 激活 source venv/bin/activate激活后命令行前面会多一个(venv)标记这时候你执行的pip install全部装进这个隔离环境里不会污染全局。想退出就敲deactivate。3. 安装 Selenium 本体3.1 一条命令装完但三条命令帮你确认在虚拟环境激活状态下安装 Selenium 只需要一条命令pip install selenium不加版本号默认装最新稳定版目前是 4.x 系列。Selenium 4 比起老的 3 代有了不少改进其中之一是内置了 Selenium Manager能尝试自动下载浏览器驱动这也是我推荐新人不学旧教程、直接用 4.x 的原因。如果你更在意稳定性想指定大版本安装可以用pip install selenium4.21.0装完之后务必做一次验证确定真的装上了python -c import selenium; print(selenium.__version__)能打印出版本号说明库本身没问题。如果提示ModuleNotFoundError: No module named selenium那就要按顺序检查三件事是不是虚拟环境没激活是不是pip装到了另一个 Python 版本是不是当前终端窗口的路径不对导致python指向的不是你预期那个解释器我自己的排查习惯是先在命令行里敲pip --version和python --version看它们前面有没有(venv)标记以及各自指向哪个路径。只要这两个命令指向的环境不一致后面必然出乱子。3.2 顺手再解决一串“环境配置安装”的共同逻辑这里多说一句因为热搜词里面除了 Selenium 还频繁出现 nodejs、jmeter、vue、git、vscode 之类的环境配置安装。其实它们背后是同一套逻辑装解释器/运行时、配包管理器、把可执行文件放进 PATH、用版本命令做验证。你完全可以把装 Selenium 的经验平移到这些工具上。nodejsnpm install和pip install本质上都是包管理器的安装命令装完 nodejs 后验证node -v和npm -v跟上面python --version的思路如出一辙。jmeter它本身不需要复杂依赖但它要跑起来必须先装 JDK因为 Jmeter 是用 Java 写的。验证方式是java -version和echo $JAVA_HOMEWindows 上是echo %JAVA_HOME%。JAVA_HOME 这个环境变量的作用和把 Python 加进 PATH 是一样的。git装的时候一路默认装完git --version验证一下它也会把自己的可执行目录写进 PATH。vscode 配置 C/C 环境你装 vscode 只是装了个编辑器真正干活的是 MinGW 或者 MSYS2 提供的 gcc 编译器所以你要把gcc.exe所在的目录加进 PATH再去 vscode 里装 C/C 扩展、写 tasks.json。绕来绕去还是 PATH 那点事。所以这篇文章虽然标题是 Selenium但你看完如果领会到“环境配置 找得到 版本对 依赖全”这三件事那以后装什么开发工具都难不倒你。4. 浏览器驱动最容易被坑的环节4.1 版本匹配是头等大事装好 Selenium 库之后还差一个浏览器驱动。很多人到这里就踩坑了网上随便搜了个“下载 ChromeDriver”下回来一运行报错SessionNotCreatedException: This version of ChromeDriver only supports Chrome version xx。这个错误翻译成人话就是你的 Chrome 浏览器版本和 ChromeDriver 版本没有对齐。对浏览器驱动和浏览器之间是强绑定的。Chrome 大版本升上去了旧版驱动就失效了。所以第一步永远是去查你的 Chrome 版本。打开 Chrome在地址栏输入chrome://version会看到一个版本号比如126.0.6478.114。你要记住的是这个版本号开头的主版本号也就是126。然后去下载对应的 ChromeDriver。一个靠谱的办法是认准 Chrome for Testing 这个官方项目。选和你本地 Chrome 版本一致的版本号再选匹配的操作系统win64、mac-arm64、linux64 这种。千万别图省事随便乱下版本对不上是一切神奇的根源。4.2 驱动文件的三种安置方式拿到驱动文件后你面临一个选择把它放在哪。我按推荐顺序说三种。第一种直接把chromedriver.exeMac/Linux 是没有后缀的可执行文件丢进 Python 的 Scripts 目录。为什么不推荐新手这样做因为一旦你用了虚拟环境路径就对不上了而且浏览器一升级你就得重新找一次忙活得很。第二种把驱动放在你的项目目录下写代码的时候手动指定路径from selenium import webdriver from selenium.webdriver.chrome.service import Service service Service(r./chromedriver.exe) driver webdriver.Chrome(serviceservice)这种方式最直观逻辑上也说得通驱动就在项目根目录代码写死路径坏处是换台电脑代码可能报错路径写死了不灵活。第三种用webdriver-manager这个库自动管理。它会在运行的时候检查你的浏览器版本自动去下载对应驱动省得你天天手动追版本pip install webdriver-managerfrom selenium import webdriver from webdriver_manager.chrome import ChromeDriverManager from selenium.webdriver.chrome.service import Service service Service(ChromeDriverManager().install()) driver webdriver.Chrome(serviceservice)如果你用的是 Selenium 4.6 以上甚至可以不写 Service直接webdriver.Chrome()因为 Selenium Manager 会尝试自动处理驱动下载。但我仍然建议你自己至少手动跑一遍流程明白驱动到底在哪、版本是怎么对应的——因为这能让你在报错的时候不慌知道自己手里拿的是什么牌。4.3 驱动放置的底层原理PATH 变量再解释一下为什么驱动放错了位置就会报错。当你在代码里执行webdriver.Chrome()不指定 Service 的情况下Selenium 会去找一个叫chromedriver的可执行文件搜索范围就是系统的 PATH 环境变量包含的目录。PATH 就是一个“寻人启事列表”Windows 找到这个列表就可以无脑在命令行里直接敲python、git、npm也是靠 PATH 找到它们对应的 exe 文件。所以你把驱动放进 Python 的 Scripts 目录本质上是把它放进了 PATH 能搜到的位置。你也可以手动把驱动所在目录加进 PATH效果一样。这就是上一节讲到的通用逻辑——“找得到”。理解了这一点那个经典的报错WebDriverException: Message: chromedriver executable needs to be in PATH就不难破了加目录进 PATH或者在代码里指定 Service 路径二选一。5. 跑通第一段自动化脚本5.1 用什么写代码VS Code 的 Python 环境配合驱动放好以后咱们来写第一段能用的代码。编辑器我推荐 VS Code免费、轻量、生态全。装好之后在扩展面板里搜 Python安装微软官方的 Python 扩展。这一步很重要没有它 VS Code 只是一个朴素文本编辑器代码不会高亮、补全也差。接下来有个很容易被忽略的点VS Code 里要用哪个 Python 解释器。你按CtrlShiftPMac 上是CmdShiftP敲“Python: Select Interpreter”它会列出电脑里的所有 Python 环境这时候你要选之前建好的虚拟环境通常路径里带venv的字样而不是全局环境。选了不对的解释器VS Code 里面运行代码会报ModuleNotFoundError但你在命令行里跑却没有问题这就是解释器选错导致的。新建文件demo.py里面写最基础的打开页面的脚本。别急着写多复杂的逻辑第一步就是确认“代码能找到驱动、驱动能启动浏览器、浏览器能打开页面”。5.2 第一段可以直接抄的脚本这里给你一段我常用的“冒烟测试”脚本用途是验证整个环境是否真的通了from selenium import webdriver from selenium.webdriver.common.by import By import time # 不指定 service 时Selenium 4.6 会自动尝试管理驱动 driver webdriver.Chrome() try: driver.get(https://www.bing.com) driver.maximize_window() time.sleep(2) # 找到搜索框输入关键词并回车 search_box driver.find_element(By.NAME, q) search_box.send_keys(selenium 环境配置) search_box.submit() time.sleep(2) print(页面标题:, driver.title) driver.save_screenshot(selenium_test.png) finally: driver.quit()看到浏览器自动弹出来、自动搜索、控制台打印出标题的时候基本可以确定环境通了。但有一件事我想单独提醒上面用了time.sleep这在验证环境时没有错但真实写自动化脚本时不要到处用sleep。因为页面加载快慢是不确定的sleep多了浪费时间少了页面还没加载完就找不到元素了。正确的方案是用显式等待比如from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC element WebDriverWait(driver, 10).until( EC.presence_of_element_located((By.NAME, q)) )意思是给目标元素最多 10 秒的等待时间找到了立即继续等不到就抛超时异常。这才是写自动化脚本的正经姿势放到后面排查那一节我再细说。5.3 服务端无界面的情况无头模式还有一种特别常见的场景你的代码要跑在一台没有界面的服务器上比如定时跑一批自动化任务。这时候直接用webdriver.Chrome()启动会报错因为根本没有桌面环境。解决办法是用 headless 模式也就是让浏览器在“无头”状态下运行from selenium import webdriver from selenium.webdriver.chrome.options import Options options Options() # 把浏览器藏到后台运行一样的逻辑只是没有窗口 options.add_argument(--headless) options.add_argument(--window-size1920,1080) driver webdriver.Chrome(optionsoptions) driver.get(https://www.bing.com) print(driver.title) driver.quit()启动参数--window-size也得留意有的网站在小窗口下布局会变化元素定位可能受到影响设一个常见的分辨率能少很多麻烦。6. 常见问题与排错技巧实录6.1 高频报错排查速查表下面这些报错基本覆盖了环境配置阶段 90% 的问题。我按“症状、原因、解法”整理成了表格方便你以后直接查报错信息关键词出现原因解决思路ModuleNotFoundError: No module named seleniumSelenium 没装进当前解释器环境检查是否激活了虚拟环境pip list看有没有 seleniumchromedriver executable needs to be in PATH系统找不到驱动放驱动进 PATH 目录或在代码中用 Service 指定路径SessionNotCreatedException: This version of ChromeDriver only supports Chrome version 9x驱动和浏览器主版本不一致去查 Chrome 版本下载同主版本的 ChromeDriverWebDriverException: Message: unknown error: cannot find Chrome binary驱动找不到浏览器安装位置设置options.binary_location指向 Chrome 的可执行文件DevToolsActivePort file doesnt existLinux 服务器上用 root 身份直接跑 Chrome加启动参数--no-sandbox --disable-dev-shm-usagepip 不是内部或外部命令pip 没装好或不在 PATH重装 Python 并勾选 Add Python to PATH或用python -m pip代替AttributeError: WebDriver object has no attribute find_element_by_name使用了老版本的 APISelenium 3Selenium 4 里统一用find_element(By.NAME, q)写法浏览器打开后立刻闪退驱动版本过旧和浏览器不匹配或安全软件拦截更新驱动临时退出安全软件试一次这个表不是给你背的是让你按症状查答案。遇到问题先别慌对照报错关键词去找基本都能落在一两个原因内。6.2 我踩过的最深几个坑第一个坑来自浏览器自动更新。Chrome 默认是静默自动更新的今天装的驱动明天可能就废了。这个问题很难根治但我现在的习惯是在写正式项目时用webdriver-manager这类自动匹配驱动的库如果是长期跑的任务干脆考虑锁定 Chrome 版本关掉自动更新换来绝对的稳定。你不需要天天追新版本够用就行。第二个坑是 Windows 上多个 Python 版本的身影。我帮朋友排查过一个问题终端里敲python能用敲pip却说找不到包后来发现python指向 Python 3.12pip指向的却是 Python 3.9 的 Scripts 目录两个环境各有各的库互不相认。这种情况最好的解决办法是永远用虚拟环境永远确认当前虚拟环境激活状态。这样无论系统里藏着多少个 Python项目内部是统一的。第三个坑在外网访问这一侧。公司内网或者离线环境下pip 下载可能会超时、ChromeDriver 也未必能下载成功。我碰过一次这种情况最后是把离线安装包和驱动提前下好拷进内网再用pip install selenium-4.x-py3-none-any.whl方式装。这也是为什么我前面强调过多次要理解驱动和服务的关系——没有外网时你更需要手动指定路径因为自动管理驱动的工具很可能也下载不了东西。第四个坑是关于杀毒软件。某些安全软件会把chromedriver.exe当作可疑程序清理掉。很多老手说“我明明装了驱动但脚本就是说找不到”一查驱动文件已经被隔离了。建议先加到信任列表再跑。6.3 验证环节的补充细节最后跑冒烟测试脚本时如果发现浏览器打不开先检查命令行里打印的日志Selenium 会在报错信息里直接提示驱动路径或者版本信息。日志里的信息往往比报错本身更有价值比如Starting ChromeDriver 126.0.6478.114 (xxxxx) on port 51076这行就意味着驱动已经启动问题就出在后面的几句——比如only supports Chrome version 126。我还有个习惯第一次跑的时候不写任何等待直接打开一个空白页然后print(driver.title)测试最小通路成功了再往上面加搜索、点击、等待这些逻辑。分层验证让“环境问题”和“代码问题”分得很清排查起来事半功倍。7. 从 Selenium 延伸出去万能的环境配置方法论7.1 所有“环境配置安装”都逃不过这三件事前面说了热搜词里反复出现 nodejs、jmeter、vue、git、vscode、appium其实它们和环境配置打交道的模式完全一致。我把这些年配置各种开发环境的经验浓缩成三句话第一让命令行找得到。任何需要安装的工具最终都会有一个可执行文件这个文件所在的目录必须出现在 PATH 里。装 Python 时勾选 Add to PATH就是给python.exe加“寻人启事”配JAVA_HOME是为了让 Java 的命令行工具能找到 JDKgit 安装包里默认的“Git from the command line”选项也是这个作用。第二让版本对得上。Selenium 和 ChromeDriver 要匹配版本nodejs 项目的package.json里要求某个库版本vue 项目要求 node 版本在某个范围appium 要求 Android SDK 的ANDROID_HOME指向正确的版本。版本不匹配的表现通常就一句话“软件能装但跑不起来”。第三让依赖装得全。pip 装 Python 库npm 装 JS 库Maven 管理 Java 包其实都是依赖管理的事。项目换一台电脑之后跑不起来绝大多数都是因为只拷贝了代码、没有带着依赖清单一起走。所以 Python 项目里我会放一个requirements.txt前端项目里有package.json这俩文件就是“告诉新环境该装什么”的清单。7.2 用清单管好你的环境依赖具体到 Selenium 项目我建议你养成一个习惯安装依赖后顺手把已经装过的包导出来记录下来。pip freeze requirements.txt下次换电脑重装环境时直接pip install -r requirements.txt一条命令把所有依赖都装回来。看起来是小事但它能让你在三个月后回看自己的项目时不用头疼回忆“当时用了哪几个包、什么版本”。这套思路也完全可以平移到 node 项目的npm install、Java 项目的pom.xml底层逻辑一模一样。7.3 环境配置问题的排查顺序最后给你一套我的排查顺序遇到任何环境问题按这个顺序来先看“装没装对”用python --version、pip --version、chromedriver --version这类命令逐个验证可执行文件是否存在、版本是多少再看“对不对得上”浏览器版本和驱动版本主版本号是否一致、当前项目要求的依赖版本是否满足最后再看“找不找得到”代码里引用的路径是否存在、PATH 环境变量是否正确。这三步走完基本能把环境问题踩在脚下。我个人这些年陆续配过 Selenium、node、JMeter、Vue、appium 的环境最大的感受就是环境配置这事其实一点都不神秘你缺的不是智商而是一条清晰的排查思路。按上面这个顺序来大部分坑都能在十分钟内定位出来。最后再分享一个小习惯我的桌面永远放一个env_check.batWindows 或 Mac 对应env_check.sh里面写着几行验证命令。每次新的环境配完不用打开各种教程比对直接双击跑一遍所有核心组件的版本号和状态一目了然。配置环境这件事本质上就是把“不确定的东西”一个一个变成“确定的东西”。等所有 “不确定” 都被你验证完项目自然就跑起来了。