强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

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 Google
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