pyspider 快速上手:从安装、第一个爬虫脚本到在 WebUI 中运行
pyspider 快速上手:从安装、第一个爬虫脚本到在 WebUI 中运行
pyspider 是一个用 Python 编写爬虫脚本、通过强大 WebUI 完成任务监控与结果管理的爬虫系统。本文以官方 docs/Quickstart.md 为骨架,带你完成从环境安装、编写第一个爬虫脚本,到在 WebUI 中分步调试并正式启动的全流程;同时结合 pyspider/libs/base_handler.py 等仓库源码,讲清 self.crawl、@every、@config、crawl_config 等核心机制背后的实现原理,让你不仅会写,更知道它为什么这么跑。
环境准备与安装
pyspider 的安装非常直接,通过 pip 一行命令即可完成:
pip install pyspider
安装完成后,直接运行命令:
pyspider
然后访问 http://localhost:5000/](http://localhost:5000/) 即可打开 WebUI 控制台。需要说明的是,裸运行 pyspider 命令实际上执行的是 all 模式:scheduler、fetcher、processor、result worker 与 webui 会以线程或子进程的方式在本地一次性拉起(对应实现在 [pyspider/run.py 的 all 子命令中,可用 --fetcher-num、--processor-num、--result-worker-num、--run-in 控制组件数量与运行方式)。它适合快速体验,但生产环境请参考 Deployment 部署文档,按需拆分组件、使用独立的数据库与消息队列。
Ubuntu 系统依赖
如果你使用的是 Ubuntu,建议先用 apt 安装二进制依赖包,避免源码编译报错:
apt-get install python python-dev python-distribute python-pip \
libcurl4-openssl-dev libxml2-dev libxslt1-dev python-lxml \
libssl-dev zlib1g-dev
PhantomJS:抓取 JavaScript 渲染页面
如果目标页面由 JavaScript 动态渲染,需要额外安装 PhantomJS。注意:PhantomJS 只有在可执行文件位于 PATH 或系统环境中时才会被 pyspider 启用。安装完成后,也可以单独用 pyspider phantomjs 命令启动 PhantomJS 代理(见 Command-Line 文档)。
安全警告:务必为 WebUI 开启认证
pyspider 的 WebUI 默认对外网开放,而 WebUI 里的脚本编辑器可以执行任意命令,可能对你的系统造成危害。请务必将其运行在内网,或通过配置文件为 WebUI 开启 need-auth。完整的命令行参数说明见 Command-Line 文档,典型的配置文件(JSON)形如:
{
"taskdb": "mysql+taskdb://username:password@host:port/taskdb",
"projectdb": "mysql+projectdb://username:password@host:port/projectdb",
"resultdb": "mysql+resultdb://username:password@host:port/resultdb",
"message_queue": "amqp://username:password@host:port/%2F",
"webui": {
"username": "some_name",
"password": "some_passwd",
"need-auth": true
}
}
其中 webui 子字典对应 pyspider webui 子命令的 --username、--password、--need-auth 选项。
编写你的第一个爬虫脚本
在 WebUI 中创建一个项目后,把下面的脚本粘贴进编辑器。这是一个经典的「入口页 → 列表页 → 详情页」三阶段爬虫:
from pyspider.libs.base_handler import *
class Handler(BaseHandler):
crawl_config = {
}
@every(minutes=24 * 60)
def on_start(self):
self.crawl('http://scrapy.org/', callback=self.index_page)
@config(age=10 * 24 * 60 * 60)
def index_page(self, response):
for each in response.doc('a[href^="http"]').items():
self.crawl(each.attr.href, callback=self.detail_page)
@config(priority=2)
def detail_page(self, response):
return {
"url": response.url,
"title": response.doc('title').text(),
}
脚本的四个关键角色
def on_start(self):脚本的入口点。在 dashboard 上点击run按钮时会被调用。配合@every装饰器,调度器会周期性触发它。self.crawl(url, callback=self.index_page):最重要的 API,向系统添加一个待抓取的新任务。绝大多数抓取选项都通过self.crawl的参数指定(如回调、age、priority、method、headers、proxy等)。def index_page(self, response):接收一个Response对象。其中response.doc是一个 pyquery 对象,提供 jQuery 风格的选择器 API 来提取元素。这里用response.doc('a[href^="http"]')选中所有href以http开头的链接,逐个提交为新的抓取任务,回调指向detail_page。def detail_page(self, response):返回一个dict作为结果。默认情况下该结果会被写入resultdb;如果你需要自行管理结果,可以重写on_result(self, result)方法(其默认实现在 pyspider/libs/base_handler.py,调试模式下会pprint打印结果,非调试模式下写入result_queue)。
三个控制抓取节奏的核心机制
@every(minutes=24*60, seconds=0):周期任务
@every 告诉调度器「这个方法每隔多久调用一次」。例如 @every(minutes=24 * 60) 表示 on_start 每天被调用一次。参数 minutes 与 seconds 可以单独或组合使用。
从源码看,@every 的实现(pyspider/libs/base_handler.py)会给函数打上 is_cronjob=True 标记并计算 tick(统一换算成秒,tick = minutes * 60 + seconds)。元类 BaseHandlerMeta(pyspider/libs/base_handler.py)会收集所有 cronjob 函数,并计算它们间隔的最大公约数 min_tick;调度器以 min_tick 为最小周期下发 _on_cronjob 触发任务,再由 _on_cronjob 方法(pyspider/libs/base_handler.py)按 tick 取模判断本次是否真正执行某个 cronjob。这样做的目的是减少调度器下发的任务数量。
注意 @every 与 age 的相互作用:如果 @every 的周期比 age 短,抓取请求仍可能被丢弃。例如每天触发一次 on_start,但回调 index_page 设置了 @config(age=10 * 24 * 60 * 60),那么该页面被判定为「10 天内未变化」,实际仍然只会每 10 天重新抓取一次(详见 docs/apis/@every.md)。
@config(**kwargs):按回调设置默认参数
@config(age=10 * 24 * 60 * 60) 为以该方法作为 callback 的 self.crawl 设置默认参数。例如上面的脚本中,index_page 通过 self.crawl(each.attr.href, callback=self.detail_page) 提交的每个详情页任务,都会继承 detail_page 上 @config(priority=2) 的配置。
@config 的源码实现(pyspider/libs/base_handler.py)只是把 kwargs 存到函数的 _config 属性上;真正生效是在 _crawl 中:当通过 self.crawl 传入回调时,_crawl 会把 func._config 中的键值合并进请求参数(pyspider/libs/base_handler.py)。参数优先级从高到低为:self.crawl(url, age=...) 显式指定 > @config(age=...) 回调配置 > crawl_config 项目配置。
Handler.crawl_config = {}:项目级全局配置
crawl_config 是整个项目的默认参数。_crawl 实现(pyspider/libs/base_handler.py)会按 schedule_fields、fetch_fields、process_fields 三组字段把 kwargs 拆包进任务的 schedule / fetch / process 子字典;其中调度相关字段(priority、retries、exetime、age、itag、force_update、auto_recrawl、cancel)在任务创建时即从 crawl_config 取默认值,而 fetcher 与 processor 相关字段在任务执行时才合并(task_join_crawl_config,见 pyspider/libs/base_handler.py),因此你可以利用这个机制在运行中动态调整抓取配置(如 cookies)。
常见用法——为整个项目设置统一的 User-Agent 或代理:
class Handler(BaseHandler):
crawl_config = {
'headers': {
'User-Agent': 'GoogleBot',
}
}
另一个高频场景是利用 itag 强制重启全部任务(详见下文)。
self.crawl 关键参数详解
self.crawl(url, **kwargs) 是告诉 pyspider「哪些 URL 需要被抓取」的主接口,其中 url 可以是单个 URL 或 URL 列表,callback 默认取 __call__。下面列出最常用的参数(默认值与语义参考 docs/apis/self.crawl.md):
| 参数 | 默认值 | 说明 |
|---|---|---|
age |
-1(永不重爬) |
任务的有效期,期间内页面视为未变化,重复提交会被丢弃。age=10*24*60*60 表示 10 天内不重复抓取 |
priority |
0 |
调度优先级,越大越先抓。可借此实现类似 BFS 的抓取顺序,减少队列中的任务数 |
exetime |
0(立即) |
任务的执行时间(Unix 时间戳),如 exetime=time.time()+30*60 表示 30 分钟后抓取 |
retries |
3 |
失败重试次数 |
itag |
None |
变化标记,与上次值比较,变化才重爬。常用页面上的「更新时间」字段作为 itag |
auto_recrawl |
False |
开启后每经过 age 时间自动重爬 |
method |
GET |
HTTP 方法;data 为 dict 时自动转为 POST |
params |
— | URL 参数字典,等价于直接拼在 URL 后 |
data |
— | 请求体,dict 会做 form 编码;配合 files 时要求为 dict |
files |
— | {field: {filename: 'content'}} 形式的 multipart 文件上传 |
user_agent |
— | 请求 User-Agent,会写入 headers |
headers |
— | 请求头字典 |
cookies |
— | 附加的 cookie 字典 |
connect_timeout |
20 |
建立连接超时(秒) |
timeout |
120 |
抓取页面的最大耗时(秒) |
allow_redirects |
True |
是否跟随 30x 重定向 |
validate_cert |
True |
HTTPS 是否校验服务器证书 |
proxy |
— | 代理,格式 username:password@hostname:port,目前仅支持 http 代理 |
etag / last_modified |
True |
是否利用 HTTP Etag / Last-Modified 机制在内容未变时跳过处理 |
fetch_type |
None |
设为 js 启用 JavaScript 抓取 |
js_script |
— | 页面加载前后执行的 JS,需包成 function() {...} 形式,返回值可通过 Response.js_script_result 获取 |
js_run_at |
document-end |
js_script 在 document-start 或 document-end 执行 |
js_viewport_width/height |
— | JavaScript 抓取的视口尺寸 |
load_images |
False |
JavaScript 抓取时是否加载图片 |
save |
— | 传给回调方法的任意对象,回调中通过 response.save 读取 |
taskid |
URL 的 MD5 | 任务唯一标识,可通过重写 def get_taskid(self, task) 自定义(默认实现见 pyspider/libs/base_handler.py) |
force_update |
— | 即使任务处于 ACTIVE 状态也强制更新任务参数 |
cancel |
— | 取消任务,需配合 force_update 使用;取消 auto_recrawl 任务时还需同时设置 auto_recrawl=False |
用 cURL 命令直接构造请求
self.crawl 还支持把 Chrome DevTools 的 Network 面板里「Copy as cURL」复制出来的命令直接作为第一个参数传入,它会自动解析命令并按 curl 的方式发起请求。这一解析逻辑位于 pyspider/libs/base_handler.py,底层由 pyspider/libs/url.py 的 curl_to_arguments 完成。
在 WebUI 中分步调试并启动爬虫
单步调试
点击绿色的 run 按钮,可以一步一步测试你的脚本:先执行 on_start 提交首批任务,然后切换到 follows 面板,点击播放按钮继续执行下一步回调,观察 index_page 是否正确地提取并提交了链接。
正式启动
- 保存你的脚本;
- 回到 dashboard 找到你的项目;
- 将项目
status改为DEBUG或RUNNING; - 点击
run按钮。
此时脚本已开始运行。项目状态说明(详见 About-Projects 文档):TODO 表示脚本待编写;STOP 表示停止;CHECKING 是运行中的项目被修改后自动进入的状态,用于防止不完整修改生效;DEBUG 与 RUNNING 对爬虫本身没有区别,建议首次运行时标记为 DEBUG,验证通过后再改为 RUNNING。抓取速率由 rate(每秒请求数)与 burst(突发容量)通过令牌桶算法控制,例如 rate/burst = 0.1/3 表示平时每 10 秒抓 1 页,但发现 3 个新任务时可以先突发抓完这 3 个,第 4 个任务才需要等待。
常见坑位与进阶提示
为什么改了代码却不重新抓取?
pyspider 默认不会重复抓取同一个 URL(永久丢弃),即使你修改了代码再跑第二次,也不会再抓——这是新手最常见的困惑。解决办法是使用 itag:把它理解成「页面版本号」,值变化才重新抓取。如果你想让修改后的脚本重新抓一遍全部任务,可以把版本号放进 crawl_config:
class Handler(BaseHandler):
crawl_config = {
'itag': 'v223'
}
改完脚本后修改 itag 的值并再次点击 run 即可(之前未设置过也没关系)。
非 200 响应不会进入回调
默认情况下,非 200 状态码的响应会被视为抓取失败,不会传给回调函数。这一行为在 pyspider/libs/base_handler.py 的 _run_task 中体现:回调前会调用 response.raise_for_status()。如果你确实需要处理 4xx/5xx 响应,可以用 @catch_status_code_error 装饰器覆盖该行为(详见 docs/apis/@catch_status_code_error.md):
@catch_status_code_error
def callback(self, response):
...
Response 对象速查
回调中拿到的 Response 对象(完整属性见 docs/apis/Response.md)常用成员包括:url(最终 URL)、orig_url(重定向前你提交的 URL)、text(unicode 文本,编码自动猜测,可手动覆盖)、content(原始字节)、doc(pyquery 对象,链接已默认转为绝对地址)、etree(lxml 对象)、json(JSON 解析结果)、status_code、headers(大小写不敏感的字典)、cookies、save(self.crawl 传入的保存对象)、ok(200 且无错误时为 True)等。
更多进阶方向
- 生产部署:参考 Deployment 文档 与 Command-Line 文档,按
scheduler/fetcher/processor/result_worker/webui子命令拆分组件,并通过--taskdb、--projectdb、--resultdb、--message-queue接入 MySQL、MongoDB、Redis、RabbitMQ 等后端。 - 脚本环境与结果处理:脚本可用的方法、环境变量见 Script-Environment 文档;结果入库、导出的进阶用法见 Working-with-Results 文档。
- 抓取完成回调:可重写
on_finished,在任务队列清空时触发(注意:存在auto_recrawl任务时时间队列永远不会为 0,on_finished不会触发;而带@every方法的项目会在每次新提交任务跑完时触发一次)。 - 源码延伸阅读:本文涉及的全部调度字段(
schedule_fields)、抓取字段(fetch_fields)、处理字段(process_fields)定义及任务拆包逻辑,均可直接阅读 pyspider/libs/base_handler.py 源码;task_join_crawl_config的合并行为也有对应单元测试 tests/test_base_handler.py 可以对照验证。

