企业官网建设流程全解析

做 Scrapy 爬虫的人十有八九都遇到过同一个尴尬：别的 Python 脚本在 PyCharm 里右键 Debug 就能下断点，唯独 Scrapy 项目，要么按运行按钮直接报 “Not a Scrapy project”，要么爬虫哗哗跑完了，你明明在 parse 方法里打的断点一个都没亮。问题基本不在你的代码质量，而在于启动方式——Scrapy 的默认入口是命令行，PyCharm 的调试器默认只跟踪你右键的那个 Python 脚本，两者压根没接上。下面是我整理出来的两种亲测可用的实现方式，一种是把命令行调用“翻译”成 Python 脚本，另一种是用 Scrapy 官方 API 驱动爬虫。两种方式都不用装额外插件、不用改 Scrapy 源码，能让断点在 parse、middleware、pipeline、extension 里稳稳命中。适合被断点问题困扰的 Scrapy 新手，也适合想把手动启动逻辑做进调试脚本的老手参考。

1. 为什么你的断点在 Scrapy 里打不中：先搞清楚调试器到底在调试谁

1.1 Scrapy 的启动方式和普通脚本差在哪

普通 Python 脚本的流程很简单：你运行python main.py，解释器加载 main.py 这个模块，逐行执行，PyCharm 的调试器通过sys.settrace挂钩每一个执行帧，所以你在哪一行打断点，执行到那一行就必然命中。但 Scrapy 不一样，爬虫项目的“入口”并不是某个.py文件，而是命令行命令scrapy crawl myspider。安装 Scrapy 之后，你会获得一个scrapy可执行程序（Windows 上是 scrapy.exe，在 Python 安装目录的 Scripts 下），它本质上是 console_scripts 生成的一个包装，真正逻辑在scrapy/cmdline.py的execute()函数里，这个函数负责解析参数、加载项目配置、创建 CrawlerProcess、启动 Twisted reactor 事件循环。

所以当你在 PyCharm 里新建一个运行配置指向 spider 文件，然后点 Debug，会发生什么？PyCharm 老老实实把那个 spider 文件当普通 Python 脚本执行。结果 spider 文件顶部 import 了一堆东西，执行完之后整个进程就结束了，它根本不会去启动 Scrapy 的调度器、下载器，因为事件循环根本没被拉起来。就算你在 spider 文件的 import 之后手动加上execute(["scrapy", "crawl", ...])，如果你只在 parse 方法里打断点，断点一样不会亮——调试器已经进入 execute 内部的事件循环后，parse 方法作为回调函数，只有在 Twisted 的事件循环跑起来、并且有 response 返回时才被调用。事件循环都没启动，自然无从命中。

还有一点容易被忽略：scrapy shell也不是给断点调试用的。它是交互式终端，适合快速测试 selector 和提取规则，但如果你要验证的是一整套爬虫流程，比如请求头生成、cookie 携带、pipeline 存储、中间件加代理，shell 根本覆盖不了。这类问题必须在真实的爬虫运行环境里打断点观察。

1.2 核心目标：把 Scrapy 塞进 PyCharm 的调试入口

明确了问题，解法就很清晰：凡是能让“当前 Python 解释器”启动爬虫的代码，都能作为 PyCharm 的调试入口。下面两种方式本质上都是“用 Python 脚本代替命令行启动”，区别只是调用的 API 不同。只要能命中这个入口，后续 Scrapy 内部所有 Python 代码都在 PyCharm 调试器的跟踪范围内，事件循环跑到哪，断点就跟到哪。

这里必须先强调 Working directory（工作目录）的问题。Scrapy 查找项目配置是通过检查scrapy.cfg文件，从当前工作目录向上逐级查找。PyCharm 的默认工作目录通常是你打开项目时所在的根目录，但如果你把脚本放在某个子目录下，或者从别的位置打开了项目，工作目录就可能不对，导致scrapy.cfg找不到。很多人调了半天断点不亮，甚至直接报错Not a Scrapy project，根本原因就在这里。保险的做法是在调试脚本开头强制切到scrapy.cfg所在目录，我在下面的示例代码里都会带上这一步。

2. 方式一：cmdline.execute，把命令行参数搬进脚本里

2.1 最小脚本 + PyCharm 运行配置

在项目根目录（和scrapy.cfg同级）新建一个run_debug.py：

import os import sys from scrapy.cmdline import execute # 切到项目根目录，确保能找到 scrapy.cfg PROJECT_DIR = os.path.dirname(os.path.abspath(__file__)) os.chdir(PROJECT_DIR) sys.path.insert(0, PROJECT_DIR) execute(['scrapy', 'crawl', 'myspider', '-O', 'debug_output.json', '-s', 'LOG_LEVEL=DEBUG'])

然后把这个文件放到 PyCharm 里，右键 -> Debug ‘run_debug’。第一次运行时，PyCharm 会创建默认运行配置，你点进去检查两件事：一是解释器，必须选你实际安装了 Scrapy 的那个解释器，很多报ModuleNotFoundError: No module named 'scrapy'的情况就是因为解释器选错了；二是 Working directory，如果脚本已经用os.chdir强制切过去了，这一步可以不管，但我还是会顺手把它设成项目根目录，省得后续脚本里少写一行就出问题。

接下来是实际调试：在myspider.py的 parse 方法第一行打一个断点，再在run_debug.py里 execute 那一行也打一个。运行后你会看到：第一次命中 execute，跳进去后 Scrapy 开始初始化，过一段时间爬到第一个 response，parse 方法里的断点就会亮起来。如果 parse 一直不命中，先看日志里请求到底发出没有，再看是不是被ROBOTSTXT_OBEY之类的规则挡住了。这一步是最容易产生误判的，我后面会在常见问题里展开讲。

2.2 原理与参数扩展

为什么这样就能调试？因为 Scrapy 的 cmdline 层本来就是 Python 函数，execute 被调起来之后，会在当前进程内完成所有事情：加载 settings、创建 crawler、启动 reactor。PyCharm 调试器只管当前 Python 进程，进程内所有代码执行都会经过调试钩子，所以断点能命中。反过来，如果你在终端跑scrapy crawl，那是另一个独立进程，PyCharm 的 Python 调试器默认不会附加到外部进程，所以打不中。这就是整个问题的本质。

execute 的 argv 参数也很好理解：第一个元素习惯写'scrapy'，它会被当作程序名；第二个是真正要执行的命令crawl；第三个是爬虫名。后面可以跟任何命令行参数，比如-O指定输出文件（覆盖模式），-s临时设置配置。这些和你在终端敲scrapy crawl myspider -O ... -s LOG_LEVEL=DEBUG完全等价，因为 execute 就是让当前 Python 进程去执行命令行解析逻辑。

传递爬虫自定义参数也有写法。如果你的 spider 构造函数需要参数，比如keyword、max_pages，可以这样：

execute(['scrapy', 'crawl', 'myspider', '-a', 'keyword=爬虫', '-a', 'max_pages=20'])

-a key=value会传给 spider，等价于命令行。如果不想每次改参数都改脚本，可以让脚本读取 PyCharm 运行配置里的参数：

if len(sys.argv) > 1: execute(['scrapy'] + sys.argv[1:]) else: execute(['scrapy', 'crawl', 'myspider', '-O', 'debug_output.json'])

这样以后在 PyCharm 运行配置的 Script parameters 里填crawl myspider -O debug.json -a keyword=python，想换参数时不用改代码，直接在配置里改。这个技巧对经常调多套参数的人非常省事。

2.3 适用场景和限制

方式一的优点是最贴近真实的生产启动路径，因为它本质上就是scrapy crawl的 Python 变体。你在命令行遇到的一切行为，包括配置优先级、日志输出、feed 导出，在调试时都会原样复现。缺点是代码里写死了爬虫名和参数，调试目标经常变的话，要么频繁改脚本，要么搭配参数转发。另一个限制是启动前的自定义逻辑不好写：比如你想先从数据库读一批种子 URL、动态构造请求，再启动爬虫，这些只能挤在 execute 之前，或者通过环境变量SCRAPY_SETTINGS_MODULE临时切换配置模块，写起来比较别扭。那种场景更适合下一节说的 CrawlerProcess 方式。

还要注意一点：execute 调用后，Scrapy 的事件循环会阻塞当前进程，直到爬虫全部跑完，后面的代码不会执行。所以 execute 之前可以做预处理，但 execute 之后不适合放“爬虫结束后的清理工作”。我一般只在调试时用它，生产环境照旧用scrapy crawl。

3. 方式二：CrawlerProcess 驱动，更 Pythonic 的调试入口

3.1 基本写法

Scrapy 官方文档里专门有一节讲“如何在脚本中运行 Scrapy”，目的就是让你在普通 Python 脚本里启动爬虫。最简单的写法同样是建在项目根目录：

import os import sys from scrapy.crawler import CrawlerProcess from scrapy.utils.project import get_project_settings PROJECT_DIR = os.path.dirname(os.path.abspath(__file__)) os.chdir(PROJECT_DIR) sys.path.insert(0, PROJECT_DIR) settings = get_project_settings() # 在这里可以临时覆盖配置，比如把下载超时调大，避免调试过程中频繁超时 settings.set('DOWNLOAD_TIMEOUT', 60) process = CrawlerProcess(settings) process.crawl('myspider', keyword='python') process.start()

get_project_settings()负责读取scrapy.cfg对应的 settings 模块，返回一个 Settings 对象，和命令行加载的配置逻辑一致。CrawlerProcess负责管理 Twisted 反应器、排队爬虫、加载扩展、启动统计等。process.crawl('myspider')按爬虫名字加载 Spider，你也可以绕过名称解析，直接导入类：

from myproject.spiders.myspider import MySpider process.crawl(MySpider, keyword='python')

传类的优势在于：调试器在 import 阶段就能准确定位到类定义，如果 spider 类名或者模块路径写错了，导入时立刻报红；同时类上的断点在类定义阶段就会命中，而不是等真正运行到那个方法才亮。process.start()用来启动事件循环并阻塞当前线程，爬虫跑完就返回。

3.2 比方式一灵活在什么地方

首先，settings 完全可控。你可以直接settings.set('CONCURRENT_REQUESTS', 1)，把并发降为 1，方便观察请求顺序；也可以settings.set('ROBOTSTXT_OBEY', False)临时关掉 robots 规则（注意生产环境不要这样干）；甚至可以从本地 JSON 文件读一组调试参数再 set 进去。比如：

import json with open('debug_config.json', 'r', encoding='utf-8') as f: config = json.load(f) for key, value in config.items(): settings.set(key, value)

这样调试参数不污染 settings.py，一个文件搞定。其次，多爬虫批量调试非常直观：

process.crawl('spider_a', start_date='2025-01-01') process.crawl('spider_b', start_date='2025-01-01') process.start()

它们会排队依次执行，互相之间不打架。调试两个爬虫之间的数据联动、对比清洗逻辑时，这种方式比开两个终端窗口方便太多。第三，方便注册自定义扩展和中间件。比如你想调试自己写的一个 extension，断点打在注册回调函数里，CrawlerProcess 在 start 时会对每个爬虫创建 Crawler 并加载扩展，断点照样能命中。如果发现自定义扩展没生效，先检查custom_settings里的EXTENSIONS条目写没写对——这类配置问题在调试时往往一眼就能看出来。

3.3 关于 reactor 的坑和 CrawlerRunner 的补充

CrawlerProcess 在内部会创建或接管默认的 Twisted reactor。如果你在同一个 Python 进程里调用两次process.start()，就会遇到ReactorAlreadyInstalledError或类似报错，因为 reactor 一旦启动就不能重新启动。普通调试脚本每次重新跑一个全新进程，不受影响；但如果你在 Jupyter Notebook 或者交互式环境里反复执行调试代码块，就很容易撞上。

解决办法有三种：一是干脆重启内核或进程，最简单粗暴；二是用CrawlerRunner搭配reactor.callWhenRunning和reactor.run()；三是把调试代码封装成独立脚本，跑完就退出，不在 REPL 里反复跑。CrawlerRunner的写法和 CrawlerProcess 很像：

from twisted.internet import reactor from scrapy.crawler import CrawlerRunner runner = CrawlerRunner(settings) d = runner.crawl('myspider') reactor.callWhenRunning(lambda: print('spider started')) reactor.run()

这种写法对日常调试没有额外优势，但如果你已经在同一个进程里跑着其他 Twisted 服务，比如自建了 Twisted API 服务，就必须用 CrawlerRunner 而不是 CrawlerProcess，否则会跟已有 reactor 冲突。注意：不要在一个脚本里把process.start()和CrawlerRunner混用，这属于自己给自己挖坑。

3.4 方式二对调试体验的影响

用方式二调试时，如果断点打在 pipeline 的process_item里，你会发现多个 item 并发处理时，断点可能在不同线程或协程里命中。PyCharm 的 Debugger 面板顶部有线程/协程切换下拉，看到名字类似 Twisted worker 的条目不要慌。要给并发条件的断点加限制，就右键断点，在 Condition 里写判别条件，比如：

item['url'] == 'http://example.com/page/2'

只有 URL 匹配的 item 会停下来，其他 item 照常流过去。另外，Scrapy 的日志在 Debug 控制台照常输出，但如果你把LOG_LEVEL调成 WARNING，很多细节就看不到了。调试期间建议保持 DEBUG，虽然日志量大，但断点命中前你可以根据日志判断流程走到哪一步，排查效率高很多。

4. 两种方式怎么选：一张表讲透调试场景

4.1 对照速查表

4.2 不同场景的选型参考

如果你只是想快速看一眼 parse 方法里的变量、确认 CSS/XPath 选择器写没写对，优先方式一。因为它最贴近实际问题，你从命令行切到调试脚本的成本几乎为零。如果调试对象涉及 middleware、pipeline、extension，需要按多个请求依次打断点观察处理链路，或者要给爬虫批量喂参数，优先方式二。如果要在同一个进程里先跑一些 Python 预处理，比如从数据库读取待抓取清单、生成登录态、准备 cookies，用方式二干净得多。

我自己在项目里的习惯是长期保留一个run_debug.py（方式一）放根目录，用于日常快速调试；遇到某个 pipeline 或扩展出问题时，再临时写一个debug_pipeline.py（方式二）做集中检查。这两个脚本不进生产命令，也不影响打包，留着不碍事。生产环境里，常规爬虫调度一般还是交给scrapy crawl或 scrapyd 这类工具，脚本启动通常只用于调试或一次性数据任务。

4.3 把两种方式结合起来的实用技巧

方式一可以接收 PyCharm 运行配置里的参数，方式二也可以把参数全部写在crawl的 kwargs 里。无论哪种方式，配合 Request 的 meta 传值都很好用：

request = Request(url, callback=self.parse, meta={'debug': True})

然后在 parse 方法的断点 Condition 里写：

response.request.meta.get('debug') is True

这样只有带上debug标记的请求会停在断点，其余请求正常流过去。排查大量页面时，我经常用这个技巧只观察特定批次、特定来源的请求，比每条都停省心得多。

5. 实战进阶：条件断点、日志断点和动态页面调试技巧

5.1 条件断点：只放行特定 response

右键断点红点，在 Condition 一栏里填表达式，比如：

response.url.startswith('https://example.com/list/')

或者更具体一点：

'关键词' in response.text and response.status == 200

Condition 会在命中前用 Python 表达式求值，表达式里可以引用当前帧的变量，但最好只做轻量判断，不要在这里调用文件 IO 或者网络请求。如果你在循环密集的场景里用了重条件，爬虫速度会被明显拖慢，调试模式下还能忍，但没必要自己折腾自己。还有一个容易踩的小坑：Condition 里写False字符串会让断点直接失效，掉进“怎么看都不亮”的坑里。

5.2 日志断点：不打断的观察方式

长时间任务里，如果每条 item 都停下，你很快就会烦。这时可以右键断点，把 Suspend（挂起）勾选取消，只保留 Log message to console，然后填模板：

[item] {item['title']} -> {item['url']}

PyCharm 会用大括号里的表达式求值结果直接替换。这样爬虫全速运行，控制台里照样能看到关键信息。这个技巧比临时加一堆logger.info更灵活，因为断点可以随手开开关关，不用改代码。我经常在parse和process_item这两个高频函数里放这种日志断点，先观察一轮输出，确认过滤条件是否按预期工作，再决定要不要改成真正的中断断点。

5.3 步进设置：别一头扎进 Scrapy 源码

调试 Scrapy 时最烦人的是单步下一步时，一不小心就跳进了 scrapy 包内部代码，比如 selector 或者 loader 的实现。我的做法是到 Settings -> Build, Execution, Deployment -> Python Debugger -> Stepping 里，把scrapy/**和twisted/**都加到 “Do not step into” 列表。这样单步时主要停在你自己的项目代码里，不会到处乱钻。如果特定场景下确实需要深入底层，临时按住 Alt 或 Shift 用 Force Step Into 就行。

另外建议在 Watch 窗口里固定几个常用表达式：response.url、response.status、response.request.meta，处理 item 时加dict(item)。Scrapy 的 Request/Response 对象展开后属性非常多，盯着 Debugger 面板一直翻很容易头晕，把真正关心的值放 Watch 里，效率会比反复展开对象高很多。

5.4 处理动态 iframe / playwright 页面的断点

有朋友问过 Scrapy 配 Playwright 处理动态 iframe 时怎么调试。Scrapy-Playwright 插件会把playwright_page对象挂在response.request.meta里。你想查 iframe 里的动态内容，最实用的断点还是在 parse 回调里：

def parse(self, response): page = response.request.meta.get('playwright_page') if page is None: self.logger.error('no playwright page') return iframe = page.frames[1] yield {'title': await iframe.locator('h1').inner_text()}

如果 parse 是 async 函数，调试器同样可以中断。断点命中后，直接在 Evaluate 表达式窗口输入page.frames，就能看到当前页面已经加载了哪些 frame。iframe 还没有出现，说明等待逻辑或者选择器有问题。更常用的做法是在请求 meta 里指定 Playwright 的等待动作：

yield scrapy.Request(url, meta={ 'playwright': True, 'playwright_page_methods': [ PageMethod('wait_for_selector', 'iframe#content'), ], })

然后在回调断点里检查page.frames。这个场景下，方式二更顺手，因为你可以先启动爬虫、让动态页面充分加载，再在回调里逐个检查 frame 状态。单纯靠 shell 判断动态渲染结果比较费劲，断点直观得多。

6. 常见问题排查速查与收尾经验

6.1 问题速查表

6.2 几个我反复踩过、值得单独说说的坑

第一，断点设在 spider 文件模块顶层的那几行，比如name = 'myspider'，几乎不会命中。模块是在导入时执行顶层代码的，Scrapy 的爬虫加载器会先检查模块再检查类，但调试器对已经导入过的模块很多时候不会重新逐行触发。真要看类属性或初始化逻辑，把断点打在__init__方法里，或者延迟到 parse / start_requests 里再观察。

第二，调试中间件或扩展时，断点不亮先查注册配置，别怀疑自己的断点有问题。DOWNLOADER_MIDDLEWARES、EXTENSIONS这类字典里如果路径写错、类名拼错，或者优先级数字没写对，Scrapy 会静默跳过。最省事的验证方式是在调试脚本里临时设置一个极低的优先级数字观察日志，或者直接在from_crawler方法的第一行加日志断点，看有没有进入。

第三，改了 settings.py 后调试行为没变化。这个多数情况是进程缓存了旧配置，或者环境变量SCRAPY_SETTINGS_MODULE指向了其他模块。关掉 Debug 会话重新启动一般能解决，还没变化就检查环境变量，脚本里也可以加一行print(settings.get('LOG_LEVEL'))之类的验证语句，确认当前加载的到底是不是你改的那个配置文件。

第四，调试时如果把CONCURRENT_REQUESTS调得太大，断点命中后你会发现同时有很多请求在并发执行，线程切换很频繁，容易看乱。调试阶段我一般把它设为 1，确认核心逻辑没问题后再调回去。这个习惯帮我省了非常多时间，因为单请求调试时调用链非常清晰，不会出现两个 response 同时命中 parse 的混乱情况。

6.3 一点个人体会

用 PyCharm 调试 Scrapy 这几年的感受是：只要能在一个“普通 Python 入口”里把爬虫跑起来，调试就成功了一半。两种方式我都留在项目里，工具本身并不冲突。遇到一个诡异问题时，我会先跑方式一复现，如果确认是配置或扩展层面的问题，再切方式二，一边调一边改逻辑，整个过程非常顺畅。建议把调试脚本单独放在项目根目录或tools/目录下，别混进 spiders 目录；提交到仓库时在.gitignore里把debug_output.json这类临时文件忽略掉，避免下次调试时看到一个残留文件，误以为数据是新的。

最后分享一个小习惯：每次调试前，先想清楚这次要看什么，只留最多三四个断点。断点一多，命中顺序会乱，反而容易把自己绕晕。与其一次性铺十个断点，不如先在最外层确认流程走到哪了，再逐步往下收，这种“从外到内”的方式在 Scrapy 这种异步框架里尤其好用。