Chromium / ChromeDriver 完全指南 / 02 - 安装与版本管理
02 - 安装与版本管理
在 Linux / macOS / Windows 上正确安装 Chromium、Chrome 和 ChromeDriver,掌握版本匹配机制与自动化驱动管理。
2.1 安装前的版本策略
在安装之前,需要先确定一个关键决策:使用固定版本还是最新版本?
| 策略 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| 固定版本 | CI/CD、生产环境 | 稳定可复现 | 需手动更新安全补丁 |
| 最新稳定版 | 本地开发 | 始终最新特性与安全修复 | 可能引入兼容性问题 |
| LTS 式版本 | 大型团队 | 平衡稳定与功能 | 需要版本管理工具 |
版本格式: Major.Minor.Build.Patch
120 . 0 . 6099 . 109
└── 必须匹配 ──┘
ChromeDriver 与 Chrome 的 Major 版本必须一致
2.2 安装 Chrome / Chromium
2.2.1 Linux — Ubuntu / Debian
安装 Google Chrome (Stable)
# 方法 1: 使用官方 deb 包
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt-get install -f -y # 修复依赖
# 验证安装
google-chrome --version
# 输出: Google Chrome 120.0.6099.109
安装 Chromium
# 方法 2: 使用 snap (Ubuntu 默认)
sudo snap install chromium
# 方法 3: 使用 apt
sudo apt-get update
sudo apt-get install -y chromium-browser
# 验证安装
chromium-browser --version
2.2.2 Linux — CentOS / RHEL / Fedora
# 安装 Google Chrome
sudo cat > /etc/yum.repos.d/google-chrome.repo << 'EOF'
[google-chrome]
name=google-chrome
baseurl=https://dl.google.com/linux/chrome/rpm/stable/x86_64
enabled=1
gpgcheck=1
gpgkey=https://dl.google.com/linux/linux_signing_key.pub
EOF
sudo yum install -y google-chrome-stable
# Fedora 使用 dnf
sudo dnf install -y google-chrome-stable
2.2.3 macOS
# 方法 1: 使用 Homebrew (推荐)
brew install --cask google-chrome
# 方法 2: 使用 Homebrew 安装 Chromium
brew install --cask chromium
# 验证
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --version
2.2.4 Windows
# 方法 1: 使用 Chocolatey
choco install googlechrome -y
# 方法 2: 使用 winget
winget install Google.Chrome
# 方法 3: 使用 Scoop
scoop install chromium
# 验证 (PowerShell)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --version
2.3 安装 ChromeDriver
2.3.1 Chrome 115+ — Chrome for Testing (推荐)
从 Chrome 115 开始,Google 提供了全新的分发端点 Chrome for Testing,可以自动获取匹配版本的 ChromeDriver。
# 查询指定版本的下载链接
# 以 Chrome 120.0.6099.71 为例
curl -sS https://googlechromelabs.github.io/chrome-for-testing/LATEST_RELEASE_120
# 获取所有平台的下载链接 (JSON)
curl -sS https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json \
| jq '.versions[] | select(.version == "120.0.6099.71") | .downloads.chromedriver'
手动下载安装:
# Linux x64
CHROME_VERSION="120.0.6099.71"
wget "https://storage.googleapis.com/chrome-for-testing-public/${CHROME_VERSION}/linux64/chromedriver-linux64.zip"
unzip chromedriver-linux64.zip
sudo mv chromedriver-linux64/chromedriver /usr/local/bin/
sudo chmod +x /usr/local/bin/chromedriver
# 验证
chromedriver --version
2.3.2 Chrome 114 及以下 — 旧版方式
# 查询当前 Chrome 版本
CHROME_VERSION=$(google-chrome --version | grep -oP '\d+\.\d+\.\d+')
echo "Chrome version: $CHROME_VERSION"
# 下载对应版本的 ChromeDriver
CHROMEDRIVER_VERSION=$(curl -sS "https://chromedriver.storage.googleapis.com/LATEST_RELEASE_${CHROME_VERSION%.*}")
wget "https://chromedriver.storage.googleapis.com/${CHROMEDRIVER_VERSION}/chromedriver_linux64.zip"
unzip chromedriver_linux64.zip
sudo mv chromedriver /usr/local/bin/
2.3.3 各平台安装汇总
| 平台 | 安装方式 | 命令 |
|---|---|---|
| Ubuntu / Debian | apt + 手动 | 见上文 |
| CentOS / RHEL | yum + 手动 | 见上文 |
| macOS (Homebrew) | brew | brew install --cask chromedriver |
| macOS (手动) | 下载解压 | 同 Linux 手动方式 |
| Windows (Chocolatey) | choco | choco install chromedriver |
| Windows (Scoop) | scoop | scoop install chromedriver |
| Windows (手动) | 下载解压 | 解压到 PATH 目录 |
2.4 驱动管理工具 (WebDriver Manager)
手动管理 ChromeDriver 版本既繁琐又容易出错。WebDriver Manager 可以自动下载和管理浏览器驱动。
2.4.1 Python — webdriver-manager
pip install webdriver-manager
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager
# 自动下载并缓存匹配版本的 ChromeDriver
service = Service(ChromeDriverManager().install())
driver = webdriver.Chrome(service=service)
driver.get("https://www.google.com")
print(driver.title)
driver.quit()
自定义版本:
from webdriver_manager.chrome import ChromeDriverManager
# 指定版本
path = ChromeDriverManager(version="120.0.6099.71").install()
# 使用 Chrome for Testing 端点 (115+)
from webdriver_manager.core.os_manager import ChromeType
path = ChromeDriverManager(chrome_type=ChromeType.CHROMIUM).install()
2.4.2 Java — WebDriverManager
<!-- pom.xml -->
<dependency>
<groupId>io.github.bonigarcia</groupId>
<artifactId>webdrivermanager</artifactId>
<version>5.6.3</version>
</dependency>
import io.github.bonigarcia.wdm.WebDriverManager;
import org.openqa.selenium.chrome.ChromeDriver;
public class Main {
public static void main(String[] args) {
// 自动下载并配置 ChromeDriver
WebDriverManager.chromedriver().setup();
ChromeDriver driver = new ChromeDriver();
driver.get("https://www.google.com");
System.out.println(driver.getTitle());
driver.quit();
}
}
高级配置:
WebDriverManager.chromedriver()
.driverVersion("120.0.6099.71") // 指定版本
.browserInDocker() // Docker 环境
.proxy("http://proxy:8080") // 代理
.cachePath("/tmp/wdm") // 缓存目录
.timeout(Duration.ofSeconds(60)) // 下载超时
.setup();
2.4.3 Node.js — @puppeteer/browsers
npm install @puppeteer/browsers
const { install, Browser, ChromeReleaseChannel } = require('@puppeteer/browsers');
// 安装指定版本的 Chrome
const chromePath = await install({
browser: Browser.CHROME,
buildId: '120.0.6099.71',
cacheDir: './.cache/puppeteer',
});
// 安装 ChromeDriver
const driverPath = await install({
browser: Browser.CHROMEDRIVER,
buildId: '120.0.6099.71',
cacheDir: './.cache/puppeteer',
});
2.4.4 各工具对比
| 工具 | 语言 | 自动匹配 | 缓存 | Docker 支持 | 维护方 |
|---|---|---|---|---|---|
| webdriver-manager (Python) | Python | ✅ | ✅ | ✅ | SergeyPirogov |
| WebDriverManager (Java) | Java | ✅ | ✅ | ✅ | Boni Garcia |
| @puppeteer/browsers | Node.js | ✅ | ✅ | ✅ | |
| playwright install | Node/Py/Java | ✅ | ✅ | ✅ | Microsoft |
| chromedriver-autoinstaller | Python | ✅ | ✅ | ⚠️ | 社区 |
2.5 版本匹配的编程实践
2.5.1 Python — 版本校验脚本
import subprocess
import json
import urllib.request
def get_chrome_version() -> str:
"""获取本地 Chrome 版本"""
try:
# Linux
output = subprocess.check_output(
['google-chrome', '--version'], text=True
)
except FileNotFoundError:
try:
# macOS
output = subprocess.check_output(
['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
'--version'], text=True
)
except FileNotFoundError:
# Windows
output = subprocess.check_output(
r'reg query "HKEY_CURRENT_USER\Software\Google\Chrome\BLBeacon" /v version',
shell=True, text=True
)
return output.strip().split()[-1]
return output.strip().split()[-1]
def get_chromedriver_version() -> str:
"""获取已安装的 ChromeDriver 版本"""
output = subprocess.check_output(['chromedriver', '--version'], text=True)
return output.strip().split()[1]
def check_version_match() -> bool:
"""检查 Chrome 与 ChromeDriver 版本是否匹配"""
chrome = get_chrome_version()
driver = get_chromedriver_version()
chrome_major = chrome.split('.')[0]
driver_major = driver.split('.')[0]
match = chrome_major == driver_major
print(f"Chrome: {chrome}")
print(f"ChromeDriver: {driver}")
print(f"Major 版本匹配: {'✅' if match else '❌'}")
if not match:
print(f"\n⚠️ 版本不匹配! Chrome major={chrome_major}, Driver major={driver_major}")
print("请更新 ChromeDriver 或使用 WebDriver Manager 自动管理。")
return match
if __name__ == '__main__':
check_version_match()
2.5.2 Shell — 自动下载匹配驱动
#!/bin/bash
set -euo pipefail
# 获取 Chrome 主版本号
CHROME_VERSION=$(google-chrome --version | grep -oP '\d+\.\d+\.\d+\.\d+')
CHROME_MAJOR=$(echo "$CHROME_VERSION" | cut -d. -f1)
echo "Chrome version: $CHROME_VERSION (major: $CHROME_MAJOR)"
# 获取 ChromeDriver 版本
if [ "$CHROME_MAJOR" -ge 115 ]; then
# 115+: 使用 Chrome for Testing 端点
DRIVER_VERSION=$(curl -sS "https://googlechromelabs.github.io/chrome-for-testing/LATEST_RELEASE_${CHROME_MAJOR}")
else
# 114 及以下: 使用旧端点
DRIVER_VERSION=$(curl -sS "https://chromedriver.storage.googleapis.com/LATEST_RELEASE_${CHROME_MAJOR}")
fi
echo "ChromeDriver version: $DRIVER_VERSION"
# 检查是否已安装且版本匹配
if command -v chromedriver &>/dev/null; then
CURRENT=$(chromedriver --version | grep -oP '\d+\.\d+\.\d+\.\d+')
if [ "$CURRENT" = "$DRIVER_VERSION" ]; then
echo "✅ ChromeDriver 已是最新: $CURRENT"
exit 0
fi
fi
# 下载并安装
PLATFORM="linux64"
if [[ "$OSTYPE" == "darwin"* ]]; then
PLATFORM="mac-arm64"
[[ $(uname -m) == "x86_64" ]] && PLATFORM="mac-x64"
fi
if [ "$CHROME_MAJOR" -ge 115 ]; then
URL="https://storage.googleapis.com/chrome-for-testing-public/${DRIVER_VERSION}/${PLATFORM}/chromedriver-${PLATFORM}.zip"
else
URL="https://chromedriver.storage.googleapis.com/${DRIVER_VERSION}/chromedriver_linux64.zip"
fi
echo "Downloading: $URL"
cd /tmp
curl -sS -o chromedriver.zip "$URL"
unzip -o chromedriver.zip
sudo mv chromedriver*/chromedriver /usr/local/bin/
sudo chmod +x /usr/local/bin/chromedriver
rm -rf chromedriver.zip chromedriver*
echo "✅ ChromeDriver 安装完成: $(chromedriver --version)"
2.6 驱动缓存与目录结构
WebDriver Manager 通常在以下位置缓存驱动:
| 工具 | 默认缓存路径 |
|---|---|
| webdriver-manager (Python) | ~/.wdm/ |
| WebDriverManager (Java) | ~/.cache/selenium/ 或 ~/.wdm/ |
| @puppeteer/browsers | ~/.cache/puppeteer/ |
| Playwright | ~/.cache/ms-playwright/ |
# 查看 webdriver-manager 缓存
tree ~/.wdm/ -L 3
# 清除缓存
rm -rf ~/.wdm/
# 设置自定义缓存目录 (Python)
export WDM_LOCAL=1
export WDM_CACHE_DIR="/opt/drivers"
2.7 防火墙与离线环境
在无法直接访问外网的环境中,需要预下载驱动或配置代理。
代理配置
# 环境变量
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
# webdriver-manager (Python)
export WDM_PROXY="http://proxy.example.com:8080"
# WebDriverManager (Java)
WebDriverManager.chromedriver().proxy("http://proxy.example.com:8080").setup();
离线安装
# 1. 在联网环境下载
wget "https://storage.googleapis.com/chrome-for-testing-public/120.0.6099.71/linux64/chromedriver-linux64.zip"
# 2. 传输到目标机器
scp chromedriver-linux64.zip user@target:/tmp/
# 3. 在目标机器安装
ssh user@target "cd /tmp && unzip chromedriver-linux64.zip && sudo mv chromedriver-linux64/chromedriver /usr/local/bin/"
2.8 常见安装问题排查
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
SessionNotCreatedException: This version of ChromeDriver only supports Chrome version XX | 版本不匹配 | 更新 ChromeDriver 或 Chrome |
WebDriverException: 'chromedriver' executable needs to be in PATH | ChromeDriver 不在 PATH 中 | 将 chromedriver 移到 /usr/local/bin/ 或配置 Service 路径 |
chromedriver: error while loading shared libraries: libnss3.so | 缺少系统依赖 | sudo apt-get install -y libnss3 libgconf-2-4 |
cannot find Chrome binary | Chrome 未安装或路径不对 | 安装 Chrome 或在选项中指定 binary_location |
net::ERR_CERT_AUTHORITY_INVALID | 证书问题 | 添加 --ignore-certificate-errors 选项 |
系统依赖安装 (Ubuntu/Debian)
# 安装 Chrome/Chromium 所需的系统依赖
sudo apt-get update && sudo apt-get install -y \
libnss3 \
libnspr4 \
libatk1.0-0 \
libatk-bridge2.0-0 \
libcups2 \
libdrm2 \
libxkbcommon0 \
libxcomposite1 \
libxdamage1 \
libxfixes3 \
libxrandr2 \
libgbm1 \
libpango-1.0-0 \
libcairo2 \
libasound2 \
libatspi2.0-0 \
fonts-liberation \
xdg-utils
2.9 要点回顾
| 要点 | 说明 |
|---|---|
| 版本匹配是核心 | ChromeDriver 与 Chrome 主版本号必须一致 |
| 115+ 新端点 | 使用 Chrome for Testing 分发,不再用旧 API |
| 使用驱动管理工具 | 自动下载、缓存、匹配版本,避免手动管理 |
| 系统依赖不能少 | 无头环境需要额外安装字体和系统库 |
| 离线环境需预下载 | 配置代理或提前下载到目标机器 |
2.10 注意事项
⚠️ 不要硬编码路径: 生产环境中不要将 ChromeDriver 路径硬编码,应使用环境变量或驱动管理工具。
⚠️ CI 环境版本锁定: CI/CD 流水线中应锁定 Chrome 和 ChromeDriver 版本,避免意外更新导致测试失败。
⚠️ 权限问题: Linux 下 ChromeDriver 需要可执行权限 (
chmod +x),且不能以 root 用户运行 Chrome (需添加--no-sandbox)。⚠️ 镜像源: 国内环境下载 ChromeDriver 可能较慢,可使用淘宝镜像:
https://registry.npmmirror.com/binary.html?path=chromedriver/
2.11 扩展阅读
| 资源 | 链接 |
|---|---|
| Chrome for Testing | https://googlechromelabs.github.io/chrome-for-testing/ |
| webdriver-manager (Python) | https://github.com/SergeyPirogov/webdriver_manager |
| WebDriverManager (Java) | https://github.com/bonigarcia/webdrivermanager |
| ChromeDriver 下载 (旧版) | https://chromedriver.storage.googleapis.com/index.html |
| ChromeDriver 版本说明 | https://chromedriver.chromium.org/downloads/version-selection |