Python Playwright项目打包实战：彻底解决浏览器驱动丢失问题

当我们需要将基于Playwright的Python自动化脚本分发给没有Python环境的用户时，打包成独立的可执行文件是最直接的解决方案。然而，许多开发者在使用PyInstaller打包时会遇到浏览器驱动丢失的棘手问题。本文将深入剖析问题根源，并提供一套完整的解决方案。

1. 理解Playwright的浏览器管理机制

Playwright与其他浏览器自动化工具最大的不同在于其内置的浏览器管理方式。默认情况下，Playwright会在首次安装时下载所需的浏览器二进制文件到系统全局目录中。这些浏览器二进制文件通常位于：

• Windows: %USERPROFILE%\AppData\Local\ms-playwright
• macOS: ~/Library/Caches/ms-playwright
• Linux: ~/.cache/ms-playwright

当使用PyInstaller打包时，这些外部依赖不会被自动包含在生成的exe文件中。这就是为什么运行打包后的程序时会出现"Please run the following command to download new browsers"错误提示的根本原因。

关键点对比：

2. 项目本地化浏览器安装的正确姿势

要让Playwright的浏览器驱动能够被打包进exe文件，我们需要改变浏览器的安装位置。这就是PLAYWRIGHT_BROWSERS_PATH=0环境变量的作用所在。

2.1 本地化安装步骤

1. 首先创建一个干净的虚拟环境（强烈推荐）：

bash复制python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate  # Windows

2. 安装Playwright并指定浏览器安装位置：

bash复制pip install playwright
PLAYWRIGHT_BROWSERS_PATH=0 python -m playwright install chromium

3. 验证安装结果：

bash复制ls .playwright  # 应该能看到chromium目录

注意：PLAYWRIGHT_BROWSERS_PATH=0会让Playwright将浏览器安装在项目根目录下的.playwright文件夹中，而不是系统全局位置。

2.2 项目结构调整建议

为了保持项目整洁，建议采用以下目录结构：

code复制project/
├── .playwright/          # 浏览器二进制
├── src/
│   ├── main.py           # 主程序
│   └── utils.py          # 工具函数
├── requirements.txt      # 依赖列表
└── build/                # 打包输出目录

3. PyInstaller打包完整流程

现在我们已经将浏览器本地化，接下来是完整的打包流程。

3.1 基础打包配置

1. 安装PyInstaller：

bash复制pip install pyinstaller

2. 创建打包规范文件playwright_pkg.spec：

python复制# playwright_pkg.spec
block_cipher = None

a = Analysis(
    ['src/main.py'],
    pathex=[],
    binaries=[],
    datas=[
        ('.playwright', '.playwright')  # 关键：包含浏览器二进制
    ],
    hiddenimports=[],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=block_cipher,
    noarchive=False,
)
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)

exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.zipfiles,
    a.datas,
    [],
    name='playwright_app',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    upx_exclude=[],
    runtime_tmpdir=None,
    console=True,
    disable_windowed_traceback=False,
    argv_emulation=False,
    target_arch=None,
    codesign_identity=None,
    entitlements_file=None,
)

3. 执行打包命令：

bash复制pyinstaller playwright_pkg.spec

3.2 常见问题解决方案

问题1：打包后程序找不到浏览器

解决方案：确保在代码中正确设置浏览器路径：

python复制import os
from playwright.sync_api import sync_playwright

def get_browser_path():
    base_path = os.path.dirname(os.path.abspath(__file__))
    if getattr(sys, 'frozen', False):
        base_path = sys._MEIPASS
    return os.path.join(base_path, '.playwright')

os.environ['PLAYWRIGHT_BROWSERS_PATH'] = '0'

with sync_playwright() as p:
    browser = p.chromium.launch(
        executable_path=os.path.join(get_browser_path(), 'chromium-XXXX/chrome-win/chrome.exe'),
        headless=False
    )
    # 其余代码...

问题2：打包体积过大

优化方案：

1. 只打包必要的浏览器（如仅Chromium）
2. 使用UPX压缩：

bash复制pip install pyinstaller[encryption]
pyinstaller --upx-dir=/path/to/upx playwright_pkg.spec

4. 高级配置与优化技巧

4.1 多平台兼容处理

不同操作系统的浏览器可执行文件路径不同，需要做平台判断：

python复制def get_chrome_executable_path():
    base_path = get_browser_path()
    if sys.platform == 'win32':
        return os.path.join(base_path, 'chromium-XXXX/chrome-win/chrome.exe')
    elif sys.platform == 'darwin':
        return os.path.join(base_path, 'chromium-XXXX/chrome-mac/Chromium.app/Contents/MacOS/Chromium')
    else:
        return os.path.join(base_path, 'chromium-XXXX/chrome-linux/chrome')

4.2 自动检测浏览器版本

为了避免硬编码浏览器版本号，可以动态获取：

python复制def find_latest_browser_version():
    browser_dir = os.path.join(get_browser_path(), 'chromium-*')
    versions = glob.glob(browser_dir)
    if not versions:
        raise Exception("No browser installed. Run 'PLAYWRIGHT_BROWSERS_PATH=0 python -m playwright install chromium'")
    return os.path.basename(sorted(versions)[-1])

4.3 打包体积优化对比

5. 实际项目中的经验分享

在多个商业项目中应用这套方案后，我们发现几个值得注意的细节：

1. 版本锁定：在requirements.txt中固定Playwright版本，避免因自动更新导致兼容性问题：

code复制playwright==1.32.1

2. 自动更新机制：对于需要长期运行的系统，可以添加浏览器版本检查逻辑：

python复制def check_browser_version():
    installed_version = find_latest_browser_version()
    latest_version = subprocess.check_output([
        'python', '-m', 'playwright', 'install', '--dry-run', 'chromium'
    ]).decode().split()[-1]
    return installed_version == latest_version

3. 错误处理增强：打包后的程序应该有更友好的错误提示：

python复制try:
    browser = p.chromium.launch(executable_path=chrome_path)
except Exception as e:
    if "executable doesn't exist" in str(e):
        show_error_dialog("浏览器组件缺失，请重新安装程序")
        sys.exit(1)

4. 日志记录：打包后的程序应该将日志输出到文件，方便排查问题：

python复制import logging

logging.basicConfig(
    filename='app.log',
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)