离线部署Pyppeteer全攻略：手动下载与配置Chromium的终极方案
当你在内网环境或网络受限的场景下使用Pyppeteer时，自动下载Chromium的步骤往往会成为拦路虎。本文将带你彻底解决这个痛点，通过手动下载和配置Chromium，让你在任何环境下都能顺利运行Pyppeteer。
1. 理解Pyppeteer与Chromium的关系
Pyppeteer本质上是一个Python版的Puppeteer，它需要依赖Chromium浏览器来执行实际的页面渲染和操作。默认情况下，Pyppeteer会尝试从Google的服务器自动下载匹配版本的Chromium，但这在国内网络环境下常常会遇到问题。
关键概念：
PYPPETEER_CHROMIUM_REVISION：指定Chromium的版本号PYPPETEER_DOWNLOAD_HOST：设置下载源地址chromium_executable()：获取Chromium可执行文件路径
2. 准备工作：确定正确的Chromium版本
在手动下载前，首先需要确定与当前Pyppeteer版本匹配的Chromium版本号。
from pyppeteer import __chromium_revision__ print(f"当前Pyppeteer需要的Chromium版本: {__chromium_revision__}")版本匹配表：
| Pyppeteer版本 | Chromium版本范围 | 备注 |
|---|---|---|
| 0.2.5及以下 | r588429 | 较旧版本 |
| 1.0.0以上 | r756035+ | 较新版本 |
提示：建议使用
pip show pyppeteer查看已安装的Pyppeteer版本，确保下载的Chromium版本完全匹配。
3. 手动下载Chromium
3.1 选择合适的下载源
国内推荐使用以下镜像源：
- npmmirror：
https://registry.npmmirror.com/-/binary/chromium-browser-snapshots - 腾讯云镜像：
https://mirrors.cloud.tencent.com/chromium-browser-snapshots
下载URL结构：
{镜像源地址}/{平台}/{版本号}/chrome-{平台标识}.zip例如Linux平台的下载URL示例：
https://registry.npmmirror.com/-/binary/chromium-browser-snapshots/Linux_x64/756035/chrome-linux.zip3.2 下载对应平台的Chromium
根据你的操作系统下载正确的压缩包：
Windows：
- 32位：Win/版本号/chrome-win.zip
- 64位：Win_x64/版本号/chrome-win.zip
Linux：
- Linux_x64/版本号/chrome-linux.zip
MacOS：
- Mac/版本号/chrome-mac.zip
4. 配置Pyppeteer使用本地Chromium
4.1 环境变量配置法
# 设置Chromium版本 export PYPPETEER_CHROMIUM_REVISION="你的版本号" # 设置Chromium可执行文件路径 export PYPPETEER_EXECUTABLE_PATH="/path/to/chrome"4.2 代码中直接指定
import asyncio from pyppeteer import launch async def main(): browser = await launch( executablePath='/path/to/chrome', headless=True ) page = await browser.newPage() await page.goto('https://example.com') await browser.close() asyncio.get_event_loop().run_until_complete(main())4.3 修改Pyppeteer源码（终极方案）
找到Pyppeteer安装目录下的chromium_downloader.py，修改以下部分：
# 修改下载源 DOWNLOAD_HOST = 'https://registry.npmmirror.com' # 修改版本号 REVISION = '你的Chromium版本号'5. 验证安装
编写一个简单的测试脚本确认一切工作正常：
import asyncio from pyppeteer import launch async def test_chromium(): try: browser = await launch() page = await browser.newPage() await page.goto('about:blank') print("Chromium运行正常!") await browser.close() except Exception as e: print(f"运行失败: {str(e)}") asyncio.get_event_loop().run_until_complete(test_chromium())6. 常见问题解决
6.1 版本不匹配错误
症状：BrowserError: Browser closed unexpectedly...
解决方案：
- 确认Pyppeteer和Chromium版本完全匹配
- 清除旧版本缓存：
rm -rf ~/.local/share/pyppeteer
6.2 权限问题
症状：Permission denied错误
解决方案：
chmod +x /path/to/chrome6.3 缺少依赖库
Linux系统常见依赖：
- libX11
- libXcomposite
- libXcursor
- libXdamage
- libXext
- libXi
- libXtst
- cups
- libxss
- libXrandr
- alsa-lib
- pango
安装命令（Ubuntu为例）：
sudo apt-get install -y libx11-dev libxcomposite-dev libxcursor-dev libxdamage-dev libxext-dev libxi-dev libxtst-dev libxss-dev libxrandr-dev alsa-lib pango7. 高级配置技巧
7.1 使用自定义缓存目录
from pyppeteer import __pyppeteer_home__ import os # 设置自定义缓存目录 os.environ['PYPPETEER_HOME'] = '/custom/cache/path'7.2 多版本Chromium管理
通过修改环境变量快速切换不同版本的Chromium：
# 版本1 export PYPPETEER_CHROMIUM_REVISION="756035" export PYPPETEER_EXECUTABLE_PATH="/path/to/chrome_v1" # 版本2 export PYPPETEER_CHROMIUM_REVISION="800000" export PYPPETEER_EXECUTABLE_PATH="/path/to/chrome_v2"7.3 离线部署完整方案
- 在有网络的环境下载所需版本的Chromium
- 将压缩包和安装脚本打包
- 在内网机器上执行以下步骤：
# 解压Chromium unzip chrome-linux.zip -d /opt/chromium # 设置环境变量 echo 'export PYPPETEER_EXECUTABLE_PATH="/opt/chromium/chrome"' >> ~/.bashrc source ~/.bashrc在实际项目中，我发现最稳妥的方式是在Docker镜像中预先打包好特定版本的Chromium，这样可以在任何环境中保证一致性。例如，以下Dockerfile片段展示了如何构建包含特定Chromium版本的环境：
FROM python:3.8-slim # 安装依赖 RUN apt-get update && apt-get install -y \ gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 \ libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 \ libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 \ libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 \ libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 \ libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation \ libappindicator1 libnss3 lsb-release xdg-utils wget # 下载并安装特定版本的Chromium RUN wget https://registry.npmmirror.com/-/binary/chromium-browser-snapshots/Linux_x64/756035/chrome-linux.zip && \ unzip chrome-linux.zip -d /opt && \ rm chrome-linux.zip # 设置环境变量 ENV PYPPETEER_EXECUTABLE_PATH="/opt/chrome-linux/chrome" # 安装Pyppeteer RUN pip install pyppeteer
