基于Selenium与ChromeDriver实现无头浏览器全页面滚动截图

1. 项目概述：为什么需要无头模式下的滚动截图？

在自动化测试、数据采集或者日常的网页归档工作中，我们经常会遇到一个看似简单却颇为棘手的需求：如何完整地截取一个长网页？无论是瀑布流式的社交媒体，还是包含大量表格和图表的数据仪表盘，传统的浏览器截图往往只能截取当前视窗（Viewport）的内容。手动拼接不仅效率低下，而且难以保证精度和一致性。这正是“无头模式下的全页面滚动截图”技术要解决的核心痛点。

所谓“无头模式”，指的是浏览器在后台运行，没有图形用户界面（GUI）。这对于服务器环境、持续集成（CI/CD）流水线或者需要批量处理的任务来说至关重要，因为它能显著节省系统资源，提升执行效率。而“全页面滚动截图”，则是通过程序控制浏览器模拟滚动，并分块捕获屏幕，最终将这些图像片段无缝拼接成一张完整的长图。

我之所以花时间研究并实践这套方案，是因为在多个数据监控和UI自动化项目中，客户或产品经理经常需要一份“所见即所得”的页面快照作为报告附件或证据留存。手动操作既不现实，也不符合自动化运维的理念。市面上虽然有一些现成的工具或浏览器插件，但它们要么无法集成到自动化流程中，要么在无头环境下表现不稳定。因此，基于Selenium和ChromeDriver打造一个可靠、可配置的滚动截图工具，就成了一个非常实用的技术选型。

2. 核心工具链解析：Selenium与ChromeDriver的协同

要实现滚动截图，我们依赖的核心工具是Selenium WebDriver和ChromeDriver。很多人对它们的关系和角色有些混淆，这里先简单拆解一下。

Selenium WebDriver 是一个用于Web应用程序自动化测试的框架。它提供了一套统一的API（支持Python、Java、C#等多种语言），允许你通过代码来模拟用户对浏览器的所有操作，比如点击、输入、滚动等。你可以把它理解为一个“遥控器”，它发送指令，但本身并不直接驱动浏览器。

ChromeDriver 则是这个“遥控器”和Chrome浏览器之间的“翻译官”或“桥梁”。它是一个独立的可执行文件，实现了WebDriver协议。当你的Selenium代码（例如， driver = webdriver.Chrome() ）运行时，它会启动ChromeDriver进程，然后由ChromeDriver去启动和控制一个真正的Chrome浏览器实例（无论是有头还是无头模式）。

在无头模式下，Chrome浏览器依然会完整地加载页面、执行JavaScript、渲染CSS，只是不显示窗口。这为我们进行截图提供了完整的渲染环境，同时避免了GUI带来的性能开销和干扰。

注意 ：ChromeDriver的版本必须与本地安装的Chrome浏览器版本严格匹配，否则大概率会报错。这是新手最容易踩的坑。通常，ChromeDriver的版本号会对应支持某个大版本的Chrome（例如，ChromeDriver 114.x 支持 Chrome 114版本）。你可以在Chrome的“关于”页面查看版本号，然后去官方仓库或镜像站下载对应版本的驱动。

3. 环境准备与基础配置

工欲善其事，必先利其器。在开始编写截图代码之前，我们需要搭建一个稳定可用的基础环境。这个过程虽然步骤不多，但每一步的细节都关系到后续能否成功运行。

3.1 Python环境与Selenium库安装

首先，确保你有一个Python环境（建议3.7及以上版本）。通过pip安装Selenium库是最简单的方式：

pip install selenium

如果你需要更精确地控制版本，或者处于隔离的虚拟环境中，可以使用：

pip install selenium==4.10.0

我通常建议使用较新的稳定版（如4.10.x），因为它们包含了对无头模式更好的支持和更多的功能。

3.2 Chrome浏览器与ChromeDriver的版本管理

这是最关键也最繁琐的一步。我的经验是，永远使用“版本匹配”的策略。

1. 检查Chrome版本 ：打开Chrome浏览器，在地址栏输入 chrome://version/ ，查看第一行的“Google Chrome”版本号（例如， 114.0.5735.198 ）。

2. 下载对应ChromeDriver ：

   • 官方渠道 ：访问 ChromeDriver 的官方下载站点。你需要根据你的操作系统（Windows、macOS、Linux）和Chrome版本号，下载对应的压缩包。
   • 更稳定的实践 ：由于网络原因，官方站点有时访问不稳定。我更倾向于使用国内的镜像源或者通过包管理工具安装。例如，在Mac上可以使用 brew install --cask chromedriver ，它会自动匹配当前Chrome版本。在Linux服务器上，可以编写脚本自动检测和下载。

3. 配置ChromeDriver路径 ：下载后，你会得到一个可执行文件（如 chromedriver.exe 或 chromedriver ）。有三种方式让Selenium找到它：

   • 方法A（推荐，灵活） ：将ChromeDriver所在目录添加到系统的PATH环境变量中。
   • 方法B（简单） ：将 chromedriver 文件直接放在Python脚本的同级目录下。
   • 方法C（显式指定） ：在代码中通过 service 参数指定绝对路径（这是最可靠的方式，尤其适合服务器部署）。

3.3 初始化无头Chrome浏览器

环境准备好后，我们就可以用代码启动一个无头Chrome实例了。以下是一个基础配置示例，包含了我常用的优化选项：

from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from selenium.webdriver.chrome.options import Options

def create_headless_chrome_driver(driver_path):
    """
    创建一个配置了常用选项的无头Chrome WebDriver实例。
    :param driver_path: ChromeDriver可执行文件的绝对路径。
    :return: 配置好的WebDriver对象。
    """
    chrome_options = Options()

    # 1. 启用无头模式
    chrome_options.add_argument('--headless=new')  # Chrome 109+ 推荐使用 new
    # 旧版本或备用方案: chrome_options.add_argument('--headless')

    # 2. 禁用GPU加速，在无头模式下有时可增加稳定性
    chrome_options.add_argument('--disable-gpu')

    # 3. 禁用沙箱（在某些Linux环境或Docker容器中可能需要）
    chrome_options.add_argument('--no-sandbox')

    # 4. 禁用DevTools监听端口，避免端口冲突
    chrome_options.add_argument('--remote-debugging-port=0')

    # 5. 使用/dev/shm共享内存，而不是/tmp，可以提高性能（Linux）
    chrome_options.add_argument('--disable-dev-shm-usage')

    # 6. 设置一个默认的用户代理，避免被一些简单的反爬机制拦截
    chrome_options.add_argument('--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36')

    # 7. 设置窗口大小。即使是无头模式，也有一个虚拟的窗口尺寸，影响渲染和截图。
    # 先设置一个较大的初始尺寸，确保页面布局正常。
    chrome_options.add_argument('--window-size=1920,1080')

    # 初始化Service和Driver
    service = Service(executable_path=driver_path)
    driver = webdriver.Chrome(service=service, options=chrome_options)

    # 8. 设置页面加载超时和脚本超时
    driver.set_page_load_timeout(30)
    driver.set_script_timeout(30)

    return driver

# 使用示例
driver = create_headless_chrome_driver('/path/to/your/chromedriver')
try:
    driver.get('https://www.example.com')
    # ... 后续操作
finally:
    driver.quit()

实操心得 ： --headless=new 是Chrome 109版本后引入的新无头模式，它使用真正的Chrome渲染管道，比旧模式更稳定、特性支持更全。如果你使用的是旧版Chrome（<109），请使用 --headless 。另外， --window-size 参数非常重要，它决定了浏览器渲染页面的“画布”大小。如果设置得过小，一些响应式布局的页面可能会以移动端样式渲染，导致截图不符合预期。我通常从1920x1080开始调整。

4. 全页面滚动截图的核心算法与实现

有了配置好的无头浏览器，我们就可以进入核心环节：如何滚动并截图。这里的核心思路是“分而治之”：将整个网页的高度分成若干个视窗高度的区块，依次滚动到每个区块的位置进行截图，最后将所有图片拼接起来。

4.1 获取页面总高度与视窗高度

首先，我们需要知道要滚动的总距离（页面总高度）以及每次滚动的步长（当前视窗高度）。我们可以通过执行JavaScript来获取这些值。

def get_page_dimensions(driver):
    """
    获取页面的总高度和当前视窗的高度。
    :param driver: WebDriver 实例。
    :return: (总高度, 视窗高度)
    """
    # 使用JavaScript获取页面总高度。document.documentElement.scrollHeight 通常最准确。
    total_height = driver.execute_script("return document.documentElement.scrollHeight")
    # 获取当前视窗的高度
    viewport_height = driver.execute_script("return window.innerHeight")
    return total_height, viewport_height

这里有一个 关键细节 ： scrollHeight 的获取对象。我测试过 document.body.scrollHeight 和 document.documentElement.scrollHeight ，在大多数现代网页中，后者更能准确反映包含所有内容（包括padding、margin）的完整文档高度。特别是在一些使用了特殊CSS（如 height: 100vh ）的页面，两者的差异可能导致计算错误。因此，我统一使用 document.documentElement.scrollHeight 。

4.2 分步滚动与视窗截图

知道了总高度和视窗高度，我们就可以计算需要滚动多少次。这里采用一个循环，每次滚动一个视窗的高度，并进行截图。

from PIL import Image
import io
import time

def take_fullpage_screenshot(driver, save_path='fullpage_screenshot.png'):
    """
    执行全页面滚动截图并保存。
    :param driver: WebDriver 实例。
    :param save_path: 最终拼接图片的保存路径。
    """
    # 1. 获取页面尺寸
    total_height, viewport_height = get_page_dimensions(driver)
    print(f"页面总高度: {total_height}px, 视窗高度: {viewport_height}px")

    # 2. 计算需要滚动的次数
    # 注意：如果页面高度小于视窗高度，则只需要截一次图。
    # 使用整数除法向上取整，确保覆盖最后一小部分。
    total_scrolls = (total_height + viewport_height - 1) // viewport_height
    print(f"预计需要滚动 {total_scrolls} 次")

    # 3. 初始化一个列表，用于存储每一部分的截图（PIL Image对象）
    screenshot_parts = []

    for i in range(total_scrolls):
        # 4. 计算当前滚动位置
        scroll_y = i * viewport_height
        # 执行滚动操作
        driver.execute_script(f"window.scrollTo(0, {scroll_y});")
        # 等待一小段时间，让页面内容（特别是懒加载的图片）稳定下来
        time.sleep(0.5)  # 这个等待时间可以根据网络和页面复杂度调整

        # 5. 截取当前视窗
        # driver.get_screenshot_as_png() 返回的是二进制数据
        screenshot_binary = driver.get_screenshot_as_png()
        # 将二进制数据转换为PIL Image对象，便于后续处理
        part_image = Image.open(io.BytesIO(screenshot_binary))
        screenshot_parts.append(part_image)

        print(f"已截取第 {i+1}/{total_scrolls} 部分")

    # 6. 所有部分截图完毕，滚动回顶部（可选，保持状态干净）
    driver.execute_script("window.scrollTo(0, 0);")

    # 7. 图片拼接逻辑（见下一小节）
    # ... 此处先跳过，假设有一个 stitch_images 函数
    final_image = stitch_images(screenshot_parts, total_height, viewport_height)
    final_image.save(save_path)
    print(f"全页面截图已保存至: {save_path}")
    return final_image

注意事项 ： time.sleep(0.5) 这个等待是 经验值 ，非常重要。在滚动后，页面可能正在进行AJAX请求、加载懒加载图片、执行动画等。如果不等页面稳定就截图，可能会截到空白、错位或者未加载完全的内容。对于复杂的单页应用（SPA），这个等待时间可能需要增加到1-2秒，甚至需要使用Selenium的“显式等待”来等待某个特定元素出现。

4.3 图像拼接算法详解

拿到了所有部分的截图列表 screenshot_parts ，现在需要把它们拼成一张长图。拼接的核心是创建一个足够高的新画布，然后将每个部分按顺序贴上去。但这里有几个陷阱需要避开。

def stitch_images(image_parts, total_height, viewport_height):
    """
    将多个视窗截图垂直拼接成一张完整的长图。
    :param image_parts: PIL Image 对象的列表，按从上到下的顺序。
    :param total_height: 页面总高度（像素）。
    :param viewport_height: 视窗高度（像素）。
    :return: 拼接后的PIL Image对象。
    """
    if not image_parts:
        raise ValueError("没有可拼接的图片部分")

    # 1. 确定最终图片的宽度（以第一张图的宽度为准）
    width = image_parts[0].width
    # 创建一张新的空白图片，模式为RGB，高度为页面总高度
    # 注意：这里使用 total_height 作为画布高度，但实际内容可能略小于它。
    final_image = Image.new('RGB', (width, total_height), color=(255, 255, 255))

    # 2. 当前粘贴的垂直位置
    current_y = 0

    for i, part in enumerate(image_parts):
        # 3. 计算当前部分理论上应占的高度
        # 如果是最后一部分，高度可能不是完整的 viewport_height
        if i == len(image_parts) - 1:
            # 最后一部分的高度 = 总高度 - 已滚动的高度
            part_expected_height = total_height - (i * viewport_height)
            # 但截图本身的高度仍然是 viewport_height，我们需要裁剪或处理
            # 更稳健的做法：直接粘贴，然后根据最终画布高度进行整体裁剪
            pass
        # 4. 将当前部分图片粘贴到画布上
        final_image.paste(part, (0, current_y))
        # 5. 更新粘贴位置
        current_y += part.height  # 使用实际截图高度作为偏移量

    # 6. 最终裁剪：由于计算和渲染的细微误差，最终画布高度可能略大于实际内容高度。
    # 一个常见的处理方法是：将画布裁剪到最后一个像素有内容的位置。
    # 我们可以通过计算所有部分实际高度的总和来得到更精确的最终高度。
    actual_total_height = sum(img.height for img in image_parts)
    if actual_total_height < total_height:
        # 如果实际截图总高度小于理论总高度，按实际高度裁剪（更常见）
        final_image = final_image.crop((0, 0, width, actual_total_height))
    # 反之，如果实际高度大于理论高度（罕见），则保留，说明页面在截图过程中可能动态变长了。

    return final_image

为什么拼接后会有白边或重叠？ 这是滚动截图中最常见的问题。原因通常有以下几个：

1. 页面固定定位元素 ：如导航栏、悬浮按钮。它们在滚动时始终停留在视窗固定位置，会被重复截取到每一张部分图中，导致拼接后出现重复的条状区域。解决方案是在截图前，通过JavaScript暂时隐藏这些元素（ element.style.visibility = 'hidden' ），截图后再恢复。
2. 滚动误差 ： window.scrollTo 是精确的，但浏览器渲染、CSS transform 、 position: sticky 等效果可能导致视觉上的滚动位置与JavaScript计算的滚动位置有细微偏差。这可能导致相邻图片之间有1-2像素的重叠或缝隙。一种高级的应对策略是，截图后使用图像处理算法（如特征点匹配）进行自动对齐，但这比较复杂。
3. 我的实战技巧 ：对于大多数新闻、文档类网页，上面的简单拼接算法已经足够好。如果遇到复杂页面，我会在滚动后，不仅等待时间，还额外执行一次 driver.execute_script(“return window.pageYOffset”) 来获取实际的滚动位置，并用这个值来校准计算，而不是完全依赖 i * viewport_height 。

5. 高级功能与优化实践

基础功能实现后，我们可以根据实际需求，为这个滚动截图工具增加更多实用功能和优化点。

5.1 处理懒加载与动态内容

现代网页大量使用懒加载技术，图片、评论等内容只在滚动到视窗内时才加载。我们的滚动截图逻辑必须能触发这些内容的加载。

策略一：增加智能等待 不仅仅是固定的 time.sleep ，我们可以结合Selenium的“显式等待”，等待某个区域内的特定元素（如图片的 img 标签）加载完成。

from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

def scroll_and_wait(driver, scroll_y, wait_timeout=5):
    """滚动到指定位置，并等待页面可能出现的懒加载内容稳定。"""
    driver.execute_script(f"window.scrollTo(0, {scroll_y});")
    try:
        # 示例：等待页面主体内容区域内的所有图片的 naturalWidth 大于0（即已加载）
        # 这需要根据目标页面的具体结构来调整选择器
        WebDriverWait(driver, wait_timeout).until(
            lambda d: all(img.get_attribute('naturalWidth') != '0' for img in d.find_elements(By.CSS_SELECTOR, '.content-area img'))
        )
    except:
        # 如果等待超时，不代表失败，可能该区域没有图片或已加载完毕，继续执行
        print(f"滚动到 {scroll_y} 后等待懒加载超时，继续。")
        pass
    # 额外增加一个短时间的通用等待，处理CSS渲染等
    time.sleep(0.3)

策略二：模拟人类滚动行为 一次性跳转到目标滚动位置可能不会触发某些基于滚动事件的懒加载库。可以模拟更平滑的滚动：

def smooth_scroll_to(driver, target_y, steps=10):
    """平滑滚动到目标位置，分 steps 步完成。"""
    current_y = driver.execute_script("return window.pageYOffset;")
    distance = target_y - current_y
    step = distance / steps
    for i in range(steps):
        current_y += step
        driver.execute_script(f"window.scrollTo(0, {current_y});")
        time.sleep(0.05)  # 每步之间短暂停顿

5.2 控制截图质量与格式

driver.get_screenshot_as_png() 获取的是PNG格式的二进制数据。我们可以通过PIL库对其进行压缩或转换格式。

def take_optimized_screenshot(driver, quality=85):
    """
    截图并进行优化（如转换为JPEG以减小文件大小）。
    :param quality: JPEG保存质量，1-100，值越大质量越好文件越大。
    """
    png_data = driver.get_screenshot_as_png()
    img = Image.open(io.BytesIO(png_data))
    
    # 如果原图是RGBA（带透明度），转换为RGB以便保存为JPEG
    if img.mode in ('RGBA', 'LA'):
        background = Image.new('RGB', img.size, (255, 255, 255))
        background.paste(img, mask=img.split()[-1]) # 使用alpha通道作为掩码
        img = background
    elif img.mode != 'RGB':
        img = img.convert('RGB')
    
    # 将图片保存到内存中的字节流，而不是直接保存文件，便于后续拼接
    img_byte_arr = io.BytesIO()
    img.save(img_byte_arr, format='JPEG', quality=quality, optimize=True)
    img_byte_arr.seek(0) # 将指针移回开头
    # 返回一个可以从字节流读取的Image对象，以及字节流本身（如果需要）
    optimized_img = Image.open(img_byte_arr)
    return optimized_img

在最终的 stitch_images 函数中，我们可以对拼接后的 final_image 同样进行格式转换和压缩，再保存到磁盘，这对于生成需要邮件发送或网络传输的报告非常有用。

5.3 应对反爬机制与异常处理

一些网站会检测Selenium的自动化特征。虽然无头模式本身有一定隐蔽性，但我们可以通过额外选项来进一步伪装。

chrome_options.add_argument('--disable-blink-features=AutomationControlled')
chrome_options.add_experimental_option("excludeSwitches", ["enable-automation"])
chrome_options.add_experimental_option('useAutomationExtension', False)
# 覆盖 navigator.webdriver 属性
driver.execute_cdp_cmd('Page.addScriptToEvaluateOnNewDocument', {
    'source': '''
        Object.defineProperty(navigator, 'webdriver', {
            get: () => undefined
        });
    '''
})

健壮的异常处理 是生产级脚本的必备。网络超时、元素未找到、脚本执行错误都可能发生。

from selenium.common.exceptions import TimeoutException, WebDriverException

def robust_fullpage_screenshot(url, driver, max_retries=2):
    """带有重试机制的全页面截图函数。"""
    for attempt in range(max_retries + 1):
        try:
            driver.get(url)
            # 等待页面主要元素加载，增加成功率
            WebDriverWait(driver, 15).until(
                EC.presence_of_element_located((By.TAG_NAME, "body"))
            )
            screenshot = take_fullpage_screenshot(driver)
            return screenshot
        except TimeoutException as e:
            print(f"第{attempt+1}次尝试，页面加载超时: {e}")
            if attempt == max_retries:
                raise
        except WebDriverException as e:
            print(f"第{attempt+1}次尝试，WebDriver异常: {e}")
            if attempt == max_retries:
                raise
            # 可以尝试重启driver
            driver.quit()
            driver = create_headless_chrome_driver(driver_path)
        except Exception as e:
            print(f"第{attempt+1}次尝试，未知异常: {e}")
            if attempt == max_retries:
                raise
    return None

6. 完整实战代码示例与部署建议

将上述所有模块整合起来，我们就得到了一个功能相对完整的滚动截图工具。下面是一个可以直接运行或作为模块引用的示例。

#!/usr/bin/env python3
"""
全页面滚动截图工具 - 完整示例
"""
import os
import time
import io
import argparse
from PIL import Image
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

class FullPageScreenshotter:
    def __init__(self, chromedriver_path, headless=True):
        self.driver = self._init_driver(chromedriver_path, headless)

    def _init_driver(self, driver_path, headless):
        chrome_options = Options()
        if headless:
            chrome_options.add_argument('--headless=new')
        chrome_options.add_argument('--disable-gpu')
        chrome_options.add_argument('--no-sandbox')
        chrome_options.add_argument('--remote-debugging-port=0')
        chrome_options.add_argument('--disable-dev-shm-usage')
        chrome_options.add_argument('--window-size=1920,1080')
        # 反自动化检测
        chrome_options.add_argument('--disable-blink-features=AutomationControlled')
        chrome_options.add_experimental_option("excludeSwitches", ["enable-automation"])
        chrome_options.add_experimental_option('useAutomationExtension', False)

        service = Service(executable_path=driver_path)
        driver = webdriver.Chrome(service=service, options=chrome_options)
        # 覆盖 webdriver 属性
        driver.execute_cdp_cmd('Page.addScriptToEvaluateOnNewDocument', {
            'source': 'Object.defineProperty(navigator, "webdriver", {get: () => undefined})'
        })
        driver.set_page_load_timeout(30)
        driver.set_script_timeout(30)
        return driver

    def _get_page_dimensions(self):
        total_height = self.driver.execute_script("return document.documentElement.scrollHeight")
        viewport_height = self.driver.execute_script("return window.innerHeight")
        return total_height, viewport_height

    def _scroll_and_capture(self, total_height, viewport_height, scroll_wait=0.5):
        total_scrolls = (total_height + viewport_height - 1) // viewport_height
        screenshots = []

        for i in range(total_scrolls):
            scroll_y = i * viewport_height
            self.driver.execute_script(f"window.scrollTo(0, {scroll_y});")
            time.sleep(scroll_wait)  # 等待稳定

            # 截图并转换为PIL Image
            png_data = self.driver.get_screenshot_as_png()
            img = Image.open(io.BytesIO(png_data))
            screenshots.append(img)
            print(f"[进度] {i+1}/{total_scrolls}")

        return screenshots

    def _stitch_images(self, images, total_height):
        if not images:
            return None
        width = images[0].width
        # 按实际截图总高度创建画布
        actual_total_height = sum(img.height for img in images)
        stitched = Image.new('RGB', (width, actual_total_height), (255,255,255))
        y_offset = 0
        for img in images:
            stitched.paste(img, (0, y_offset))
            y_offset += img.height
        return stitched

    def capture(self, url, save_path, scroll_wait=0.5):
        """主捕获函数"""
        print(f"正在访问: {url}")
        self.driver.get(url)
        # 等待页面基础内容加载
        WebDriverWait(self.driver, 15).until(
            EC.presence_of_element_located((By.TAG_NAME, "body"))
        )
        # 可选：隐藏固定定位元素
        # self.driver.execute_script("document.querySelectorAll('header, .fixed-nav').forEach(el => el.style.visibility='hidden');")

        print("正在计算页面尺寸...")
        total_height, viewport_height = self._get_page_dimensions()
        print(f"页面总高: {total_height}px, 视窗高: {viewport_height}px")

        print("开始滚动截图...")
        screenshots = self._scroll_and_capture(total_height, viewport_height, scroll_wait)

        print("正在拼接图片...")
        full_image = self._stitch_images(screenshots, total_height)

        if full_image:
            # 确保目录存在
            os.makedirs(os.path.dirname(os.path.abspath(save_path)), exist_ok=True)
            full_image.save(save_path, 'PNG', optimize=True)
            print(f"✅ 截图成功保存至: {save_path}")
            return True
        else:
            print("❌ 截图失败，未生成图片。")
            return False

    def close(self):
        if self.driver:
            self.driver.quit()

def main():
    parser = argparse.ArgumentParser(description='无头Chrome全页面滚动截图工具')
    parser.add_argument('url', help='要截图的网页URL')
    parser.add_argument('-o', '--output', default='./screenshot.png', help='输出图片路径 (默认: ./screenshot.png)')
    parser.add_argument('-c', '--chromedriver', required=True, help='ChromeDriver可执行文件路径')
    parser.add_argument('-w', '--wait', type=float, default=0.5, help='每次滚动后的等待时间（秒） (默认: 0.5)')
    args = parser.parse_args()

    screenshotter = None
    try:
        screenshotter = FullPageScreenshotter(args.chromedriver)
        success = screenshotter.capture(args.url, args.output, args.wait)
        exit(0 if success else 1)
    except Exception as e:
        print(f"程序运行出错: {e}")
        exit(1)
    finally:
        if screenshotter:
            screenshotter.close()

if __name__ == '__main__':
    main()

部署建议：

1. 服务器环境 ：在Linux服务器上部署时，除了安装Chrome和ChromeDriver，还需要安装一些依赖库，例如：

   # Ubuntu/Debian 示例
   sudo apt-get update
   sudo apt-get install -y wget unzip
   # 安装Chrome
   wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
   sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list'
   sudo apt-get update
   sudo apt-get install -y google-chrome-stable
   # 安装Python3和PIL（Pillow）
   sudo apt-get install -y python3 python3-pip
   pip3 install selenium Pillow
   

2. Docker化 ：这是最推荐的方式。可以基于官方的 selenium/standalone-chrome 镜像构建自己的镜像，将Python脚本和依赖打包进去。这样可以完美解决环境一致性问题。
3. 性能与资源 ：无头Chrome仍然消耗内存和CPU。在并发处理多个截图任务时，需要考虑使用队列（如Redis + RQ或Celery）来控制同时运行的浏览器实例数量，避免服务器过载。每个实例完成后，务必调用 driver.quit() 来彻底释放资源。

7. 常见问题排查与调试技巧

即使按照上述步骤操作，在实际运行中你还是可能会遇到各种问题。这里我整理了一份常见问题速查表，以及我个人的调试心得。

我的调试工具箱：

1. 临时禁用无头模式 ：在开发阶段，先将 --headless=new 参数注释掉，让浏览器窗口显示出来。这样你可以直观地看到页面加载、滚动是否正常，是定位问题最快的方法。
2. 保存中间状态 ：在关键步骤（如每次滚动后）保存当前视窗的截图，并命名为 debug_part_{i}.png 。当最终拼接图出错时，查看这些中间图能立刻知道是哪一步出了问题（例如，哪次滚动后页面内容没加载）。
3. 打印关键信息 ：在脚本中大量使用 print 语句，输出如页面高度、视窗高度、滚动位置、当前URL等信息。这些日志对于在服务器上排查问题至关重要。
4. 使用 execute_script 探查 ：当你怀疑页面状态时，可以通过 driver.execute_script(“return document.readyState”) 查看文档状态，或者 driver.execute_script(“return window.pageYOffset”) 查看实际滚动位置，与你的计算值进行比对。

最后，记住自动化脚本没有一劳永逸的银弹。不同的网站结构千差万别，你可能需要针对特定的网站微调等待时间、滚动策略甚至元素选择器。这套方案提供了一个坚实、可扩展的框架，能解决90%的滚动截图需求，剩下的10%则需要你根据实际情况，运用这些调试技巧和原理知识去灵活应对。