简介这套工具包面向需要处理复杂网页数据的 Python 爬虫开发者围绕 pycurl、pyspider 与 PhantomJS 三款组件重点解决静态页面抓取、动态内容渲染以及爬虫任务调度协同等常见问题。压缩包共 52 个文件整体约 28.71MB包含 2 个可直接安装的 whl 包、无头浏览器可执行程序与 45 个 JavaScript 示例脚本并附有说明文档、更新日志和第三方许可文件从安装、验证到二次开发文件结构清晰便于快速上手。已有 328 人学习下载适合具备一定 Python 基础、希望掌握爬虫框架与无头浏览器配合作战的开发者。通过其中的示例脚本可以练习协议级请求配置、可视化任务编排以及依赖 JavaScript 渲染页面的抓取处理三个组件在项目中相互配合为复杂网页数据采集提供了可直接运行的环境与参考样例。1. pycurlpyspiderphantomjs 这一组合到底在解决什么pycurl、pyspider、phantomjs 这组组合适合页面里一半静态、一半靠 JS 渲染的抓取场景。我在某公司维护过一个资讯聚合爬虫列表页的数据要等 JS 跑完才出现详情页却是普通静态 HTML还有几十 MB 的附件需要下载。如果只上 requests列表就抓空只上 pyspider大文件会吃爆内存只上 phantomjs调度和断点又得自己写。标题里的三个工具正好拆成三层pycurl 管可控 HTTP 下载pyspider 管任务调度、去重和失败重试phantomjs标题里 phabtomjs 是它的手误写法管渲染。下面是这“下载 调度 渲染”三层怎么接到一起、参数怎么调、坑在哪的完整拆解按可复现的方式讲适合正在做抓取链路、想少踩坑的从业者。2. 先划清三个工具的职责边界下载、调度、渲染各自管什么2.1 pycurl 的角色不是爬虫框架是“可控 HTTP 下载器”很多读者会把 pycurl 和 requests 摆在一起选型这是个误区。pycurl 的本质是 libcurl 的 Python 绑定它提供的不是get()这种封装好的方法而是一堆setopt让你直接控制 curl 的底层行为。这意味着它在“爬虫”这个事情上其实没有框架概念真正的价值在于网络会话的可控性。我实际使用中pycurl 主要在四个场景里不可替代。第一是大文件下载WRITEDATA可以直接指向一个文件对象边下载边落盘内存占用恒定而 requests 默认把整个响应读进内存几十 MB 的文件一来就容易把 worker 打垮。第二是断点续传setopt(pycurl.RESUME_FROM, offset)一行就能从指定字节继续下载requests 要自己拼 Range 头。第三是限速MAX_RECV_SPEED可以直接限制下载速度做多任务并发时防止把出口带宽打满。第四是 HTTPS 握手的细节控制指定 CA 包、关闭或开启证书校验、自定义 DNS、绑定出口 IP 等。诉求pycurl 的做法用 requests 的体验大文件写盘WRITEDATA 指向 file 对象边下边写读入内存再落盘内存压力大断点续传RESUME_FROM 指定偏移量手动拼 Range 头还得处理状态码限速MAX_RECV_SPEED 单行开启需要自定义 stream 循环代码量大HTTPS 细节setopt 直接控制 SSL_VERIFYPEER、CAINFOsession 配置散落行为不直观所以我的结论是pycurl 是“下载层”的工具不是“抓取逻辑层”的工具。在本文的实战场景里它专门负责详情页大附件的下载不参与列表页和详情页的 HTML 抓取那些交给 pyspider 默认机制更合适。2.2 pyspider 解决的不是“发请求”而是“任务生命周期”pyspider 的设计核心是“每一个 URL 就是一条任务”任务有自己的状态机active等待抓取、success抓取回调正常结束、failed回调异常或网络失败。调度器负责决定任务何时被 worker 取走同一个 URL 会不会重复调度失败后是否重试以及多久之后允许重新抓同一地址。这些特性是我选它的直接原因。我之前自己写过调度循环用 dict 存 URL 状态进程一重启全部归零断点续爬完全靠运气。pyspider 把任务状态持久化到 taskdb 里重启以后任务还在失败任务也可以从 WebUI 手动重新执行这份能力不便宜。另一个值得说的是去重self.crawl(url)同一个 url 只会生成一条任务后续重复调用会复用旧任务避免同一页面反复被抓。和一个常见的误解区分开pyspider 不是什么“性能怪兽”它单机吞吐并不夸张但它把“任务去重、过期重抓、断点恢复、结果回收”这一整套索引机制替你写好了。爬虫最烧时间的从来不是抓取本身而是任务管理和恢复pyspider 解决的是这部分。2.3 phantomjs 的作用域只在“JS 渲染”这一环出手phantomjs 是一个基于 QtWebKit 的无头浏览器能像一个真实浏览器那样加载页面、执行 JS、等待异步请求返回再把渲染后的 DOM 交给你。在 pyspider 里它通过一个常驻的 phantomjs_fetcher 进程对外提供渲染服务调度器遇到fetch_typejs的任务时会把 URL 发给这个渲染进程而不是发给普通的下载器。什么时候需要 phantomjs判断标准只有一个页面数据在静态 HTML 里是否存在。我用一个笨办法验证直接 curl 拉 URL 后用 grep 找关键字段找不到就说明数据靠 JS 生成的这时候再考虑渲染。常见的需要渲染的场景有三种列表数据由 AJAX 接口在浏览器端填进 DOM、页面存在懒加载导致滚动后才加载更多内容、分页按钮依赖 JS 事件绑定而不是普通 href。需要提醒的是phantomjs 是重型工具每个渲染任务会占一个独立的浏览器上下文并发越高内存涨得越快。所以它只适合处理“必须渲染”的那部分页面纯静态的 URL 千万不要往渲染通道里塞。2.4 三者如何接在一起架构一句话说清整体架构在实战项目里是这样串的pyspider 作为主框架接收全部抓取请求其中需要 JS 渲染的任务通过fetch_typejs派发给 phantomjs_fetcher渲染完成后的 HTML 和脚本返回值原样回流到 pyspider 的 workerworker 解析出的附件下载链接则交给 pycurl 直接处理避免大文件进入任务队列。这样分工有一个额外好处三层可以独立替换。phantomjs 挂了只需重启渲染进程pyspider 的任务状态不受影响pycurl 下载失败也只是下载层失败列表和详情抓取逻辑无需改动。抓取链路拆得越独立排障边界就越清晰这是我把这套组合用于生产环境的主要原因。3. 本地跑通三件套环境安装、最小脚本、phantomjs 配置3.1 环境安装pycurl 的编译依赖和 phantomjs 的二进制先把环境装好这一步最容易翻车。pyspider 对运行环境比较挑建议直接用独立的 Python 3.7 虚拟环境能省掉大量不兼容问题。Python 3.8 以上的版本跑 pyspider 会遇到语法兼容问题虽然能 patch但没必要在生产环境冒险。# 建议用 python3.7 或 python3.6 python3.7 -m venv ~/venvs/spider source ~/venvs/spider/bin/activate pip install --upgrade pip # 先装 pycurllibcurl 开发头不足时会编译失败 pip install pycurl # 再装 pyspider pip install pyspiderpycurl 在 Linux 上需要系统的 libcurl 开发头常见发行版一般用包管理器安装比如libcurl4-openssl-dev。装完以后可以用一段极简代码验证是否可用注意pycurl.curl_info()能打印 libcurl 版本如果提示找不到 libcurl.so 之类的错误说明编译时没找到动态库需要重新安装或设置环境变量指定路径。phantomjs 单独下载二进制即可不需要 pip。去 phantomjs 官方页面拿到对应操作系统的压缩包解压后确保phantomjs --version能跑出版本号。pyspider 的 phantomjs_fetcher 本质就是用这个二进制去执行一个 JS 文件所以 phantomjs 本身必须能独立运行。3.2 最小脚本先让 pyspider 跑通一个静态页装完环境先不要碰 JS把 pyspider 最小任务脚本跑起来。下面这个脚本的逻辑很简单入口on_start发起对某站首页的请求回调index_page从页面里提取所有外链再交给detail_page解析标题。from pyspider.libs.base_handler import * class Handler(BaseHandler): def on_start(self): # 入口方法启动时会被调度器调用一次 self.crawl( https://example.com/, callbackself.index_page ) def index_page(self, response): # response.doc 是 pyquery 对象选择器和 jquery 风格一致 for link in response.doc(a[href^http]).items(): self.crawl( link.attr.href, callbackself.detail_page ) def detail_page(self, response): # 返回值会进入 on_result这一步存的就是你要的结构化数据 return { url: response.url, title: response.doc(title).text(), }self.crawl是 pyspider 最核心的调用第一个参数是目标 URLcallback指定处理函数。response.doc返回 pyquery 对象用类似 jQuery 的语法做选择器。detail_page返回的字典会被 pyspider 自动收集经on_result方法写入 resultdb。然后启动项目。开发阶段直接跑一体式命令pyspider allpyspider all会把 scheduler、worker、webui 全部拉在同一个进程里启动端口默认 5000。打开http://127.0.0.1:5000/就能看到任务面板点运行按钮触发on_start然后观察任务从 active 变成 successfailed 则表示回调或网络层出错。3.3 挂上 phantomjs配置渲染服务和第一个 js 任务跑通静态页之后把渲染服务挂上。pyspider 需要一份配置文件告诉 scheduler 怎么联系 phantomjs 渲染进程。我一般单独建一个config.json{ phantomjs_fetcher: http://127.0.0.1:25544, phantomjs_fetcher_port: 25544, phantomjs_fetcher_timeout: 15000 }然后手动启动渲染进程用哪个 phantomjs 二进制、加载哪些 cookie、是否加载图片都在这一步控制phantomjs --load-imagesno --cookies-file/tmp/pjs_cookies.txt \ /path/to/pyspider/phantomjs_fetcher.js--load-imagesno表示不加载图片渲染速度提升非常明显也能避免部分图片资源阻塞页面加载。phantomjs_fetcher.js 在 pyspider 安装目录的 phantomjs 文件夹里自己找到绝对路径填进去即可。启动完访问http://127.0.0.1:25544/能看到服务响应说明成功。再写一个带渲染的抓取任务关键参数是fetch_typejs和js_scriptfrom pyspider.libs.base_handler import * class Handler(BaseHandler): def on_start(self): self.crawl( https://example.com/dynamic, fetch_typejs, js_script function() { var node document.querySelector(.main-content); return node ? node.innerText : ; } , callbackself.dynamic_page ) def dynamic_page(self, response): return { url: response.url, content: response.js_script_result, }fetch_typejs是切换渲染通道的开关一旦设置pyspider 会把这个 URL 交给 phantomjs_fetcher而不是普通下载器。js_script里的函数会在页面加载完成后于浏览器上下文执行返回值经过 JSON 序列化传回最终能从response.js_script_result取到。这里建议脚本里做好空值判断渲染失败或节点加载慢时返回空字符串而不是抛异常。4. 实战组合场景JS 渲染列表页 静态详情页 大文件下载4.1 先画页面关系图再动手写代码这个实战场景我做过很多次某个资料站点的列表页由 JS 动态生成条目详情页是服务端渲染的普通 HTML详情页底部还有一个几十 MB 的附件下载链接。如果只靠 pyspider 默认下载器列表页抓回来是空的附件会撑爆内存。用三件套的分工方式页面关系梳理成四条链列表页URL 结构为/list?page1内容由 JS 填充需要 phantomjs 渲染。详情页URL 为/detail/123.html静态 HTMLpyspider 直接抓。附件详情页解析出的下载链接交给 pycurl 流式落盘。结果每条详情页解析出的字段统一回收到 MySQL。画清楚页面关系后handler 的职责边界就非常明确了。不要在一个回调函数里既做渲染又做下载那样排障时你分不清到底是页面变了、脚本挂了还是下载失败。每层独立日志里才能快速定位。4.2 主 handler 代码列表页渲染、详情页解析、附件下载完整代码按职责拆成四个方法on_start入口、list_page处理渲染结果、detail_page解析详情并触发下载、以及一个静态方法做 pycurl 附件下载。import os import pycurl from pyspider.libs.base_handler import * class Handler(BaseHandler): crawl_config { headers: {User-Agent: Mozilla/5.0}, timeout: 20, retries: 3, } def on_start(self): # 列表页必须走 phantomjs 渲染js_script 提取条目 URL 和标题 self.crawl( https://example.com/list?page1, fetch_typejs, js_script function() { var arr []; var nodes document.querySelectorAll(.product-item); for (var i 0; i nodes.length; i) { var node nodes[i]; var a node.querySelector(a.item-link); if (!a) continue; arr.push({ url: a.href, title: node.querySelector(.title).innerText }); } return arr; } , callbackself.list_page ) def list_page(self, response): # phantomjs 渲染后返回的结构化结果直接可用 items response.js_script_result or [] for item in items: self.crawl( item[url], callbackself.detail_page, save{title: item[title]} ) def detail_page(self, response): # 静态详情页可以直接用 response.doc 解析 price response.doc(.price).text() file_node response.doc(.download-btn a) result { url: response.url, title: response.save.get(title), price: price, local_path: None, } if file_node: file_url file_node.attr.href local_path self.download_file(file_url) result[local_path] local_path return result staticmethod def download_file(file_url): # 大文件用 pycurl 流式写盘不进内存避免 worker 被撑爆 dest_dir /data/files os.makedirs(dest_dir, exist_okTrue) file_name file_url.split(/)[-1] dest os.path.join(dest_dir, file_name) with open(dest, wb) as f: curl pycurl.Curl() try: curl.setopt(pycurl.URL, file_url) curl.setopt(pycurl.WRITEDATA, f) curl.setopt(pycurl.FOLLOWLOCATION, 1) curl.setopt(pycurl.CONNECTTIMEOUT, 15) curl.setopt(pycurl.TIMEOUT, 300) curl.setopt(pycurl.NOSIGNAL, 1) curl.setopt(pycurl.USERAGENT, Mozilla/5.0) curl.perform() except pycurl.error as exc: # 这里只记录日志不抛异常避免影响详情页任务状态 import logging logging.error(download failed: %s, url%s, exc, file_url) return None finally: curl.close() return destlocal_path为 None 时就说明附件下载失败业务上可以后续重放而不是让整个详情页任务失败。crawl_config里的超时和重试是全局默认值个别 URL 需要覆盖时可以在self.crawl里再传一遍timeout、retries。4.3 结果落库on_result 与基于 URL 的幂等写入detail_page 返回的结构化数据会被 pyspider 统一交给on_result方法。这里我建议落 MySQL用 URL 做主键天然去重。CREATE TABLE IF NOT EXISTS items ( url VARCHAR(512) PRIMARY KEY, title VARCHAR(255), price VARCHAR(50), local_path VARCHAR(512), create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, update_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;on_result 里的写入逻辑def on_result(self, result): if not result: return sql INSERT INTO items (url, title, price, local_path) VALUES (%s, %s, %s, %s) ON DUPLICATE KEY UPDATE title VALUES(title), price VALUES(price), local_path VALUES(local_path) params ( result[url], result[title], result.get(price, ), result.get(local_path), ) self.mysql.execute(sql, params)用 URL 做主键的价值在于pyspider 的任务去重是针对 URL 的但数据库写入是另一套逻辑两者不一定对齐。赶上任务重放pyspider 会再次回调 detail_page再次进入 on_resultURL 主键加上ON DUPLICATE KEY UPDATE可以保证重复抓取时更新而不是插入新行这也是我踩过一次重复数据后养成的习惯。5. 避坑与排查phantomjs 白屏、pycurl 段错误、任务卡死5.1 phantomjs 渲染结果白屏或字段为空现象任务显示 success但js_script_result是空字符串或空数组点开任务详情查看抓回的 HTML页面里面空空荡荡只有htmlhead/headbody/body/html。原因多半有两个一是页面本身有懒加载数据是滚动或点击后通过 AJAX 追加的phantomjs 加载完立即执行脚本时数据还没到位二是--load-imagesno在某些站点上把判断脚本执行时机的机制改变了渲染进程返回得过早。解决方法是把 js_script 改成轮询等待模式而不是一次性提取。常见做法是在脚本里用定时器反复检查目标节点是否存在最多等一个窗口期超时就返回当前状态。这个窗口期一般给 10 到 15 秒太久会拖慢整个队列。function() { var deadline Date.now() 10000; function getData() { var nodes document.querySelectorAll(.product-item); if (nodes.length 0 || Date.now() deadline) { return Array.prototype.map.call(nodes, function(node) { return node.innerText; }); } setTimeout(getData, 500); } return getData(); }注意这里的返回值不能立刻拿到因为setTimeout是异步的实际项目中更稳妥的做法是在 pyspider 侧把phantomjs_fetcher_timeout调大配合js_run_atdocument-end让脚本在文档加载完成后执行。先加超时再调脚本不要一上来就调大并发。5.2 pycurl 在抓取过程中直接段错误现象任务跑起来的前几分钟正常过一会儿 worker 进程直接崩溃看日志发现是 Segmentation fault没有 Python traceback。原因pycurl 的 Curl 句柄本质上是 libcurl 的 easy handle这个句柄不是线程安全的。pyspider 的 worker 是多线程模型如果为了提高下载效率在代码里复用了同一个 Curl 对象或者把一个 Header List 反复绑定到多个句柄上多个线程同时perform时就可能触发 libcurl 底层的竞争条件。解决pycurl.Curl() 实例每次都新建用完立刻 close绝不做全局复用的“优化”。另外一定要打开NOSIGNAL选项它会让 libcurl 不用信号处理超时避免在多线程环境下因为信号机制打断系统调用导致崩溃。curl pycurl.Curl() curl.setopt(pycurl.NOSIGNAL, 1) # ... 其他 setopt curl.perform() curl.close()如果你发现崩溃出现在perform之后而不是之前检查是否在多个 Curl 实例之间共享了HTTPHEADER列表。每个 Curl 实例都应该独立构造 header 列表这是容易忽略的隐蔽点。5.3 任务永远停在 active不 success 也不 failed现象WebUI 里某个任务始终是 active 状态调度器、worker 都重启了也没变化任务既没有进入 success也没有变成 failed。原因这个通常不是回调异常而是请求在 phantomjs_fetcher 那边一直没有返回。渲染进程被某个超长加载页面卡住后任务就悬挂在 active。pyspider 的 active 状态代表“调度器已经派出但结果还没回来”如果 phantomjs 进程本身僵死这个状态会一直维持。解决先看 phantomjs_fetcher 的进程 CPU 和内存如果内存持续上涨直接重启渲染进程再把phantomjs_fetcher_timeout调小一些让超时的任务快速失败而不是无限等待。生产环境里我给渲染进程配了守护脚本每两小时检测一次内存占用超过阈值就自动重启。phantomjs 本身有不可避免的内存增长不要指望一个进程能长期稳定。5.4 同一个 URL 重新抓取后数据库出现重复记录现象跑了一段时间发现库里同一 URL 对应多条记录数据出现重复排查后发现不是任务重复调度而是任务重放时生成了新的写入。原因pyspider 对 URL 的去重是任务级别的同一 URL 只会有一个任务但任务可以被手动重放或者因为 age 过期重新抓取。重新抓取后回调会再次执行on_result再次触发如果数据库侧没有唯一约束一条记录就变成了两条。解决数据库表加 URL 唯一主键写入用ON DUPLICATE KEY UPDATE也就是 4.3 里写的模式。更进一步的写法是用 URL 参数指纹做联合唯一这样即使同一地址对应不同查询参数也不会漏掉。这个坑在抓取量小的时候根本感觉不到等跑两周之后看数据质量才会发现越早加约束越好。6. 进阶技巧把吞吐量和稳定性一起拉上去三件套跑通只是开始抓到后期真正的瓶颈通常在 phantomjs 渲染速度和 pyspider 单 worker 的并发能力。我的习惯是做一个“最小渲染面”原则列表页尽量让 js_script 在 phantomjs 内部完成数据提取只把结构化结果返回而不是把整个渲染后 HTML 都传回 pyspider。这样既减少网络传输也减少了 worker 的解析时间。吞吐量上一个有效手段是给 phantomjs 做实例池。pyspider 允许配置多个 phantomjs_fetcher 地址把 URL 按任务 hash 分发到不同渲染进程。实操时我先起两个渲染进程分别占 25544 和 25545 端口观察一段时间后按单进程每秒能处理的渲染任务数决定是否需要扩容。phantomjs 实例池最关键的是每个实例的 cookie 目录要分开共用 cookie 文件会导致 session 串号这是我在某次登录态混乱时踩出来的教训。pycurl 也可以配合带宽控制做并发下载。给每批下载任务设置MAX_RECV_SPEED比如限制在 2MB/s这样 10 个附件并发下载时总带宽会被压到 20MB/s不至于把业务站点的网络出口占满。这个参数在 pycurl 里就是一行 setopt但价值很大尤其在服务器带宽不富裕、还要同时跑列表页任务的场景。还有一个容易被忽略的稳定性技巧回调函数里不要抛异常。detail_page 如果因为解析字段报错任务会直接 failed但 failed 任务太多会影响你对整体运行状况的判断。更稳妥的是在关键解析处做空值兜底字段缺失时返回 None 或空字符串把异常记录到日志里而不是让任务失败。这样日志里能看到真实情况WebUI 上一片 success 也不会掩盖数据质量问题。我现在做一个抓取项目第一件事不是写 handler而是先确定哪些页面必须走 phantomjs、哪些可以直接静态抓、哪些文件要 pycurl 落盘。抓取任务不是写功能是写容错。每批代码发布前我都会用几百条样本跑一轮观察 success 和 failed 的比例、附件下载成功率再决定放量。这套“先分层、再落盘、后调参”的顺序帮我省下的调试时间远比写代码的时间多。希望帮到你。本文还有配套的精品资源点击获取