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

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 / Debianapt + 手动见上文
CentOS / RHELyum + 手动见上文
macOS (Homebrew)brewbrew install --cask chromedriver
macOS (手动)下载解压同 Linux 手动方式
Windows (Chocolatey)chocochoco install chromedriver
Windows (Scoop)scoopscoop 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)PythonSergeyPirogov
WebDriverManager (Java)JavaBoni Garcia
@puppeteer/browsersNode.jsGoogle
playwright installNode/Py/JavaMicrosoft
chromedriver-autoinstallerPython⚠️社区

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 PATHChromeDriver 不在 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 binaryChrome 未安装或路径不对安装 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 Testinghttps://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