pyspider 快速上手:从安装、第一个爬虫脚本到在 WebUI 中运行

原创2026-09-20 12:28:351,628 阅读
文章标签:网页爬虫后端任务调度分布式训练

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 是否正确地提取并提交了链接。

run one step

正式启动

  1. 保存你的脚本;
  2. 回到 dashboard 找到你的项目;
  3. 将项目 status 改为 DEBUG 或 RUNNING;
  4. 点击 run 按钮。

index demo

此时脚本已开始运行。项目状态说明(详见 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 可以对照验证。
登录后查看全文
pyspider