async def main(): async with GoogleImageCrawler() as crawler: # 搜索图片 results = await crawler.search("cute cats", num_images=10)

    # 打印结果
    for result in results:
        print(f"URL: {result.url}")
        print(f"Size: {result.width}x{result.height}")
    
    # 下载图片
    downloaded = await crawler.download_images(
        results,
        output_dir="./downloads"
    )

asyncio.run(main())


### 同步 API（快速调用）

```python
from crawler import search_images_sync

# 一行代码搜索图片
results = search_images_sync("mountain landscape", num_images=5)
for r in results:
    print(r.url)

核心功能

1. 图片搜索 (GoogleImageCrawler.search)

使用 Playwright 自动化 Google 图片搜索，提取原始高清图片 URL。

results = await crawler.search(
    keyword="search term",      # 搜索关键词
    num_images=10,              # 获取数量
    safe_search=True,           # 安全搜索
    min_width=None,             # 最小宽度过滤
    min_height=None             # 最小高度过滤
)

2. 图片下载 (GoogleImageCrawler.download_images)

异步批量下载图片，支持并发控制。

downloaded = await crawler.download_images(
    results=results,            # 搜索结果列表
    output_dir="./images",      # 输出目录
    concurrency=3               # 并发数
)

3. 独立下载模块 (ImageDownloader)

更强大的下载功能，支持线程池并发和进度显示。

from downloader import ImageDownloader

downloader = ImageDownloader(
    output_dir="./downloads",
    concurrent=5,
    max_retries=3
)

results = downloader.download_batch(urls)

4. 命令行工具

# 从文件下载
python cli.py -f urls.txt -o ./images

# 带参数下载
python cli.py -f urls.txt -c 10 -t 60 -o ./images

# 下载单张图片
python cli.py -u "https://example.com/image.jpg" -o ./images

使用示例

示例 1: 基础搜索

import asyncio
from crawler import GoogleImageCrawler

async def basic_search():
    async with GoogleImageCrawler(headless=True) as crawler:
        results = await crawler.search("sunset beach", num_images=5)
        
        print(f"找到 {len(results)} 张图片:")
        for i, result in enumerate(results, 1):
            print(f"{i}. {result.title[:40] if result.title else 'No title'}")
            print(f"   URL: {result.url[:70]}...")
            print(f"   尺寸: {result.width}x{result.height}")

asyncio.run(basic_search())

示例 2: HD 壁纸搜索（带尺寸过滤）

async def hd_wallpaper_search():
    async with GoogleImageCrawler() as crawler:
        results = await crawler.search(
            "4k wallpaper",
            num_images=5,
            min_width=1920,
            min_height=1080
        )
        
        print(f"找到 {len(results)} 张高清图片:")
        for result in results:
            print(f"✓ {result.width}x{result.height} - {result.url[:60]}...")

asyncio.run(hd_wallpaper_search())

示例 3: 搜索并下载

async def search_and_download():
    async with GoogleImageCrawler() as crawler:
        # 搜索
        results = await crawler.search("puppy", num_images=10)
        print(f"搜索完成，准备下载 {len(results)} 张图片...")
        
        # 下载
        downloaded = await crawler.download_images(
            results,
            output_dir="./downloads",
            concurrency=2
        )
        print(f"下载成功: {len(downloaded)} 张")
        for path in downloaded:
            print(f"  → {path}")

asyncio.run(search_and_download())

示例 4: 使用独立下载模块

from downloader import ImageDownloader

# 单独使用下载模块
downloader = ImageDownloader(
    output_dir="./downloads",
    concurrent=5,
    timeout=30,
    max_retries=3
)

# 从 URL 列表下载
urls = [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
]

results = downloader.download_batch(urls)

# 统计结果
success = len(results['success'])
failed = len(results['failed'])
print(f"成功: {success}, 失败: {failed}")

示例 5: 组合使用（推荐）

import asyncio
from crawler import GoogleImageCrawler
from downloader import ImageDownloader

async def combined_workflow():
    # 1. 爬取图片 URL
    async with GoogleImageCrawler() as crawler:
        results = await crawler.search("mountain", num_images=20)
        urls = [r.url for r in results]
    
    # 2. 使用 Downloader 下载（支持更多功能）
    downloader = ImageDownloader(
        output_dir="./mountain_images",
        concurrent=5,
        max_retries=3
    )
    
    with downloader:
        results = downloader.download_batch(urls)
        
        # 统计结果
        success = len(results['success'])
        failed = len(results['failed'])
        print(f"成功: {success}/{success + failed}")

asyncio.run(combined_workflow())

参数说明

GoogleImageCrawler 初始化参数

参数	类型	默认值	说明
`headless`	bool	True	无头模式（不显示浏览器窗口）
`timeout`	int	30	页面加载超时（秒）
`scroll_pause`	float	1.5	滚动间隔（秒）
`max_retries`	int	3	最大重试次数
`proxy`	str	None	代理服务器地址 (e.g., "http://proxy:8080")

search() 方法参数

参数	类型	默认值	说明
`keyword`	str	必填	搜索关键词
`num_images`	int	10	需要获取的图片数量
`safe_search`	bool	True	是否开启安全搜索
`min_width`	int	None	图片最小宽度过滤
`min_height`	int	None	图片最小高度过滤

ImageResult 属性

属性	类型	说明
`url`	str	原始高清图片 URL
`thumbnail_url`	str	缩略图 URL
`title`	str	图片标题
`source_url`	str	来源网页 URL
`width`	int	图片宽度
`height`	int	图片高度

ImageDownloader 初始化参数

参数	类型	默认值	说明
`output_dir`	str	"./downloads"	输出目录
`timeout`	int	30	请求超时（秒）
`max_retries`	int	3	最大重试次数
`concurrent`	int	5	并发下载数
`headers`	dict	None	自定义请求头

CLI 参数

参数	简写	说明
`--file`	`-f`	URL 列表文件路径
`--url`	`-u`	单个图片 URL
`--output`	`-o`	输出目录
`--concurrent`	`-c`	并发下载数
`--timeout`	`-t`	超时时间（秒）
`--retries`	`-r`	最大重试次数
`--limit`	`-l`	限制下载数量
`--proxy`		代理服务器地址

错误处理

常见错误及解决方案

1. 浏览器初始化失败

# 错误: BrowserInitError 或 playwright 相关错误
# 解决方案: 确保已安装浏览器

# 运行安装命令
# playwright install chromium

2. 搜索超时或页面加载失败

# 错误: TimeoutError 或页面加载失败
# 解决方案: 增加超时时间或使用代理

async with GoogleImageCrawler(timeout=60) as crawler:
    results = await crawler.search("keyword", num_images=10)

3. 图片下载失败

# 错误: DownloadError 或 HTTP 错误
# 解决方案: 增加重试次数或使用独立下载模块

downloader = ImageDownloader(max_retries=5, timeout=60)
results = downloader.download_batch(urls)

4. IP 被限制

# 错误: 频繁出现连接被拒绝或验证码
# 解决方案: 使用代理和增加滚动间隔

async with GoogleImageCrawler(
    proxy="http://proxy:8080",
    scroll_pause=3.0  # 增加间隔
) as crawler:
    results = await crawler.search("keyword", num_images=10)

异常处理示例

import asyncio
from crawler import GoogleImageCrawler

async def safe_search():
    try:
        async with GoogleImageCrawler() as crawler:
            results = await crawler.search("keyword", num_images=10)
            return results
    except Exception as e:
        print(f"搜索失败: {e}")
        return []

async def safe_download(crawler, results):
    try:
        downloaded = await crawler.download_images(
            results,
            output_dir="./downloads",
            concurrency=2
        )
        return downloaded
    except Exception as e:
        print(f"下载失败: {e}")
        return []

# 使用
asyncio.run(safe_search())

技术细节

原图 URL 提取原理

Google 图片搜索结果的每个图片都包含一个 /imgres 链接：

/imgres?imgurl=https://example.com/original.jpg&imgrefurl=...

爬虫通过解析 imgurl 参数获取原图地址。

反爬策略

使用正常用户 User-Agent
设置合理视口大小（1920x1080）
自动处理 Cookie 同意弹窗
滚动间隔模拟人工操作（1.5秒）
指数退避重试机制

文件结构

google-image-crawler/
├── crawler.py          # 爬虫核心模块 (Playwright + 异步)
├── downloader.py       # 图片下载模块 (Requests + 线程池)
├── config.py           # 配置管理
├── cli.py              # 命令行工具
├── example.py          # 使用示例
└── docs/               # 文档
    ├── architecture.md # 架构设计
    ├── api-reference.md # API 参考
    └── examples.md     # 更多示例

依赖

playwright: 浏览器自动化
aiohttp: 异步 HTTP 客户端
requests: 同步 HTTP 请求
tqdm: 进度条显示

注意事项

遵守服务条款: 请遵守 Google 服务条款和目标网站的 robots.txt
控制频率: 避免过于频繁的请求，建议设置合理的 scroll_pause
版权合规: 商业使用请确认图片版权
使用代理: 大量爬取时建议使用代理避免 IP 限制
资源释放: 使用 async with 上下文管理器确保浏览器正确关闭

License

MIT

google-image-crawler

Google Image Crawler

快速开始

安装依赖

基础使用