Selenium：W3C WebDriver 标准浏览器自动化框架｜部署与使用全指南

Selenium 是一套跨语言、跨浏览器的浏览器自动化基础设施，为 W3C WebDriver 规范提供官方参考实现。本文按照官方仓库 README 与 Selenium 官方用户手册，梳理本地安装、语言绑定最小示例、Selenium Manager 驱动自动管理与常见问题排查。

1. 项目简介与定位

Selenium 是一个"伞形项目"（umbrella project），封装了一系列用于 Web 浏览器自动化的工具与库。它为 W3C WebDriver 规范 提供基础设施——一套与平台、语言无关的编程接口，可驱动所有主流 Web 浏览器（Chrome、Edge、Firefox、Safari）。项目由志愿者贡献者维护，是浏览器自动化领域事实上的标准。

1.1 核心信息一览

1.2 适用场景

• Web 端到端（E2E）功能测试
• 多浏览器兼容性测试矩阵
• 基于真实浏览器的 Web 抓取与页面渲染
• 跨语言团队共享同一套自动化 API
• 通过 Selenium Grid 在多机 / 多容器上并行分发用例

1.3 能力边界（官方口径）

官方 README 明确说明：本仓库 README 面向希望为 Selenium 贡献代码的开发者；普通使用者应直接查阅 User Manual。Selenium 只负责"驱动浏览器"，不负责断言、报告、测试用例编排，这些通常由 pytest、JUnit、TestNG、WebdriverIO 等测试框架配合完成。

2. 开源协议

Selenium 采用 Apache License 2.0。允许商业使用、修改、分发、专利授权，需保留版权与许可声明；修改文件需标注变更。

3. 官方仓库链接

• 主仓库：https://github.com/SeleniumHQ/selenium
• 用户手册：https://www.selenium.dev/documentation/
• 支持入口：https://www.selenium.dev/support/
• Java API 文档：https://seleniumhq.github.io/selenium/docs/api/java/index.html
• Python API 文档：https://seleniumhq.github.io/selenium/docs/api/py/
• JavaScript API 文档：https://seleniumhq.github.io/selenium/docs/api/javascript/
• C# API 文档：https://seleniumhq.github.io/selenium/docs/api/dotnet/
• Ruby API 文档：https://seleniumhq.github.io/selenium/docs/api/rb/

4. 前置要求

普通使用者不需要从源码构建 Selenium，只需准备：

仅当你要为 Selenium 贡献源码时，才需要按官方 README 安装 Bazelisk、JDK 17、Xcode / MSYS2 / Visual Studio 等构建工具。

5. 安装部署

5.1 Python 绑定（最常用）

pip install selenium

5.2 Node.js / JavaScript 绑定

npm install selenium-webdriver

5.3 Java 绑定（Maven）

在 pom.xml 中加入：

<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-java</artifactId>
  <version>4.0.0</version>
</dependency>

5.4 Selenium Manager（驱动自动管理）

自 Selenium 4.6 起，Selenium 内置 Selenium Manager，会自动检测本机浏览器版本并下载匹配的 chromedriver / geckodriver / msedgedriver，无需手动安装 driver，也无需配置 webdriver.chrome.driver 环境变量。首次运行会在用户缓存目录下缓存 driver 二进制。

5.5 从源码构建（仅贡献者）

官方 README 给出的最小构建路径：

# 需要 Bazelisk 与 JDK 17+
bazel build //java/...       # 构建 Java 模块
bazel build grid             # 构建 Selenium Grid（别名）
./go java:install            # 安装到本地 ~/.m2
./go py:install              # 构建并安装 Python wheel 到当前 venv

6. 最小示例代码

6.1 Python 最小脚本

from selenium import webdriver
from selenium.webdriver.common.by import By

# Selenium Manager 自动找到 Chrome 与 chromedriver
driver = webdriver.Chrome()

driver.get("https://www.selenium.dev/selenium/web/web-form.html")
title = driver.title
print("Title:", title)

text_box = driver.find_element(By.NAME, "my-text")
submit_button = driver.find_element(By.CSS_SELECTOR, "button")

text_box.send_keys("Selenium")
submit_button.click()

message = driver.find_element(By.ID, "message")
print("Message:", message.text)

driver.quit()

6.2 headless 模式（服务器无显示器）

from selenium.webdriver.chrome.options import Options

options = Options()
options.add_argument("--headless=new")
options.add_argument("--no-sandbox")
options.add_argument("--disable-dev-shm-usage")

driver = webdriver.Chrome(options=options)

6.3 远程连接 Selenium Grid

from selenium import webdriver

options = webdriver.ChromeOptions()
driver = webdriver.Remote(
    command_executor="http://localhost:4444",
    options=options,
)

启动 Grid Standalone（默认监听 4444）：

docker run -d -p 4444:4444 selenium/standalone-chrome

7. 配置项

容器化部署 Grid 时，官方镜像 selenium/standalone-chrome、selenium/standalone-firefox、selenium/hub、selenium/node-chrome 通过 SE_JAVA_OPTS、SE_NODE_MAX_SESSIONS 等环境变量调参，详见 Selenium Docker 子项目文档。

8. 常见问题

Q1：SessionNotCreatedException: This version of ChromeDriver only supports Chrome version XX A：升级到 Selenium 4.6+，让 Selenium Manager 自动匹配；或手动下载与本机 Chrome 同版本的 chromedriver。

Q2：服务器上启动 Chrome 报 Failed to move to new namespace / DevToolsActivePort file doesn't exist A：容器内必须加 --no-sandbox --disable-dev-shm-usage --headless=new，并使用官方 selenium/standalone-chrome 镜像。

Q3：找不到 webdriver.chrome.driver？ A：Selenium 4.6+ 不再需要手动设置该路径。如仍报错，确认 pip show selenium 版本 ≥ 4.6，或在代码中 Service(executable_path=...) 显式指定。

Q4：元素定位偶尔超时？ A：不要混用 time.sleep()，改用 WebDriverWait + expected_conditions 显式等待。

Q5：如何在 CI 中跑？ A：GitHub Actions / GitLab CI 直接用 browser-actions/setup-chrome 装 Chrome，或直接 docker run selenium/standalone-chrome -p 4444:4444，再用 webdriver.Remote 连接。

9. 与同类工具对比

一句话：Selenium 胜在语言与浏览器最广、生态最久；Puppeteer / Playwright 在 Node 生态里 API 更现代；WebdriverIO 是站在 Selenium 协议之上的完整测试框架。

10. 许可

Apache License 2.0。详见 https://github.com/SeleniumHQ/selenium/blob/trunk/LICENSE 。

11. 责任使用声明

使用 Selenium 进行任何自动化访问时，请遵守目标站点的 robots.txt 与服务条款（ToS）。请控制并发频率并在请求之间加入合理延时，避免对目标服务器造成压力。请勿使用 Selenium 绕过登录验证、付费墙、验证码或反爬机制。请勿批量抓取、存储或传播个人隐私数据。本工具仅应用于公开数据的合法研究、自身站点的 E2E 测试与授权范围内的自动化任务。请尊重网页内容的版权与知识产权，抓取结果的二次发布需获得权利人许可。