docker-registry/.qoder/repowiki/zh/content/kami-spider-monorepo 模块/Playwright集成.md

Playwright集成

**本文档中引用的文件** - [Dockerfile.base](file://kami-spider-monorepo/Dockerfile.base) - [pyproject.toml](file://kami-spider-monorepo/pyproject.toml) - [uv.lock](file://kami-spider-monorepo/uv.lock) - [build-base-image.sh](file://kami-spider-monorepo/build-base-image.sh) - [README.md](file://kami-spider-monorepo/README.md)

目录

1. 简介
2. 项目结构
3. 系统级依赖详解
4. Chromium浏览器预下载机制
5. Playwright Python API使用示例
6. 环境变量控制安装行为
7. 常见问题与解决方案
8. 构建与使用说明

简介

本文档详细说明了如何在Docker镜像中集成Playwright，实现开箱即用的浏览器自动化能力。重点涵盖系统依赖安装、Chromium浏览器预加载、Playwright API使用方法、环境变量控制以及常见问题处理。

项目结构

kami-spider-monorepo目录包含构建Playwright集成Docker镜像所需的核心文件。该结构旨在提供一个完整、可复用的基础镜像，适用于需要浏览器自动化的爬虫服务。

graph TD
A[kami-spider-monorepo] --> B[Dockerfile.base]
A --> C[build-base-image.sh]
A --> D[pyproject.toml]
A --> E[uv.lock]
A --> F[README.md]

图示来源

• Dockerfile.base
• pyproject.toml

本节来源

• README.md

系统级依赖详解

Dockerfile.base中通过apt-get安装了一系列系统级依赖库，这些库对于Chromium在无头Linux容器中稳定运行至关重要。

依赖包	用途说明
libnss3	网络安全服务库，支持HTTPS/TLS加密通信
libasound2	ALSA音频支持库，防止因缺少音频设备导致的崩溃
libx11-6	X11客户端库，提供基础的图形界面通信能力
libatk-bridge2.0-0	辅助技术工具包桥接，支持无障碍功能
libdrm2	直接渲染管理器库，支持GPU加速渲染
libxkbcommon0	键盘处理公共库，处理键盘布局和输入
libxcomposite1	X复合扩展库，支持窗口合成
libxdamage1	X损伤扩展库，用于检测屏幕变化
libxrandr2	X随机访问内存库，管理显示分辨率
libgbm1	通用缓冲区管理库，支持GPU内存管理
libcups2t64	通用Unix打印系统库，防止打印相关错误
libxfixes3	X修复扩展库，修复图形渲染问题
libcairo2	2D图形绘制库，支持矢量图形渲染
libpango-1.0-0	文本布局与渲染库，支持复杂文本显示

这些依赖通过playwright install-deps chromium命令进一步验证和补充，确保Chromium所有运行时需求都被满足。

本节来源

• Dockerfile.base
• Dockerfile.base

Chromium浏览器预下载机制

为实现“开箱即用”的体验，Docker镜像在构建阶段即预下载并安装Chromium浏览器。

• 存储路径：/app/.browsers
• 环境变量：PLAYWRIGHT_BROWSERS_PATH=/app/.browsers
• 安装命令：/app/.venv/bin/playwright install chromium
• 用户权限：由非root用户appuser执行安装，确保运行时权限一致
• 权限设置：安装完成后，root用户将浏览器目录权限设为755，保证appuser可读写

此机制确保容器启动时无需额外下载浏览器，显著提升启动速度和稳定性。

sequenceDiagram
participant DockerBuild as Docker构建
participant RootUser as Root用户
participant AppUser as appuser用户
participant Playwright as Playwright CLI
DockerBuild->>RootUser : 开始构建
RootUser->>AppUser : 切换至appuser
AppUser->>Playwright : playwright install chromium
Playwright->>AppUser : 下载并安装Chromium到/app/.browsers
AppUser->>RootUser : 切换回root
RootUser->>RootUser : chmod -R 755 /app/.browsers
RootUser->>DockerBuild : 构建完成

图示来源

• Dockerfile.base
• Dockerfile.base

本节来源

• Dockerfile.base

Playwright Python API使用示例

以下代码展示了如何在容器内使用Playwright Python API进行浏览器自动化。

from playwright.sync_api import sync_playwright
import os

def main():
    with sync_playwright() as p:
        # 启动Chromium浏览器
        browser = p.chromium.launch(
            headless=True,
            args=[
                '--no-sandbox',
                '--disable-setuid-sandbox',
                '--disable-dev-shm-usage',
                '--disable-gpu'
            ]
        )
        
        page = browser.new_page()
        
        # 拦截请求示例
        def intercept_request(route, request):
            if request.resource_type in ["image", "stylesheet", "font"]:
                route.abort()
            else:
                route.continue_()
        
        page.route("**/*", intercept_request)
        
        # 处理反爬检测
        page.add_init_script("""
            Object.defineProperty(navigator, 'webdriver', {
                get: () => false,
            });
        """)
        
        page.goto("https://example.com")
        print(page.title())
        
        browser.close()

if __name__ == "__main__":
    main()

本节来源

• pyproject.toml
• uv.lock

环境变量控制安装行为

通过环境变量可灵活控制Docker镜像的构建和运行行为。

环境变量	作用	默认值	使用场景
USE_PROXY	是否使用PyPI镜像代理	0	在网络受限环境中设为1
PLAYWRIGHT_BROWSERS_PATH	浏览器安装路径	/app/.browsers	自定义浏览器存储位置
UV_LINK_MODE	UV包管理器链接模式	copy	控制依赖安装方式
PYDEVD_DISABLE	禁用PyDev调试器	1	生产环境禁用调试

例如，使用代理构建镜像：

USE_PROXY=1 ./build-base-image.sh

本节来源

• Dockerfile.base
• build-base-image.sh

常见问题与解决方案

问题：Browser closed unexpectedly

原因：

• 缺少系统依赖库
• 权限问题
• 内存不足
• 未正确设置--no-sandbox等启动参数

解决方案：

1. 确保Dockerfile.base中所有系统依赖已安装
2. 检查/app/.browsers目录权限为755
3. 增加容器内存限制
4. 启动浏览器时添加必要参数：

args=[
    '--no-sandbox',
    '--disable-setuid-sandbox',
    '--disable-dev-shm-usage',
    '--disable-gpu'
]

问题：无法加载页面或超时

解决方案：

• 检查网络连接
• 增加超时时间
• 使用wait_for_load_state("networkidle")
• 启用请求拦截减少资源加载

本节来源

• Dockerfile.base
• Dockerfile.base

构建与使用说明

使用提供的脚本可一键构建基础镜像：

# 构建基础镜像
./build-base-image.sh

# 使用代理构建
USE_PROXY=1 ./build-base-image.sh

# 推送到私有镜像仓库
DOCKER_REGISTRY=your-registry.com ./build-base-image.sh

构建完成后，镜像标记为kami-spider-base:latest，可直接用于部署需要Playwright的爬虫服务。

本节来源

• build-base-image.sh
• README.md