命令行工具

Scrapy 通过 scrapy 命令行工具进行控制，为了与子命令（我们简称为“命令”或“Scrapy 命令”）区分开来，这里将其称为 “Scrapy 工具”。

Scrapy 工具提供了多个命令，用于多种用途，每个命令都接受一组不同的参数和选项。

（scrapy deploy 命令已在 1.0 版本中移除，取而代之的是独立的 scrapyd-deploy。请参阅部署您的项目。）

配置设置

Scrapy 会在标准位置的 ini 风格 scrapy.cfg 文件中查找配置参数：

/etc/scrapy.cfg 或 c:\scrapy\scrapy.cfg（系统级），
~/.config/scrapy.cfg ($XDG_CONFIG_HOME) 和 ~/.scrapy.cfg ($HOME) 用于全局（用户级）设置，以及
Scrapy 项目根目录内的 scrapy.cfg（见下一节）。

这些文件中的设置按照列出的优先级顺序进行合并：用户定义的值比系统级默认值具有更高的优先级，而项目级设置在定义时将覆盖所有其他设置。

Scrapy 还可以通过许多环境变量来理解和配置。目前这些变量包括：

SCRAPY_SETTINGS_MODULE (参见指定设置)
SCRAPY_PROJECT (参见项目间共享根目录)
SCRAPY_PYTHON_SHELL (参见 Scrapy shell)

Scrapy 项目的默认结构

在深入研究命令行工具及其子命令之前，让我们先了解一下 Scrapy 项目的目录结构。

虽然可以修改，但默认情况下所有 Scrapy 项目都具有相同的文件结构，类似于：

scrapy.cfg
myproject/
    __init__.py
    items.py
    middlewares.py
    pipelines.py
    settings.py
    spiders/
        __init__.py
        spider1.py
        spider2.py
        ...

scrapy.cfg 文件所在的目录被称为项目根目录。该文件包含定义项目设置的 python 模块名称。这是一个示例：

[settings]
default = myproject.settings

使用 `scrapy` 工具

您可以从运行不带任何参数的 Scrapy 工具开始，它将打印一些使用说明和可用命令：

Scrapy X.Y - no active project

Usage:
  scrapy <command> [options] [args]

Available commands:
  crawl         Run a spider
  fetch         Fetch a URL using the Scrapy downloader
[...]

如果您在 Scrapy 项目内，第一行将打印当前活动的项目。在本例中，它是从项目外部运行的。如果从项目内部运行，它会打印类似这样的内容：

Scrapy X.Y - project: myproject

Usage:
  scrapy <command> [options] [args]

[...]

创建项目

通常您使用 scrapy 工具做的第一件事就是创建 Scrapy 项目：

scrapy startproject myproject [project_dir]

这将在 project_dir 目录下创建一个 Scrapy 项目。如果未指定 project_dir，则 project_dir 将与 myproject 相同。

接下来，进入新的项目目录：

cd project_dir

然后您就可以从那里使用 scrapy 命令来管理和控制您的项目了。

控制项目

您可以在项目内部使用 scrapy 工具来控制和管理它们。

例如，创建一个新的 spider：

scrapy genspider mydomain mydomain.com

某些 Scrapy 命令（如 crawl）必须从 Scrapy 项目内部运行。请参阅下面的命令参考，了解有关哪些命令必须从项目内部运行、哪些不需要的更多信息。

还要记住，某些命令在从项目内部运行时可能会有略微不同的行为。例如，如果正在抓取的 url 与某个特定的 spider 相关联，fetch 命令将使用 spider 覆盖的行为（例如使用 custom_settings 属性来覆盖设置）。这是有意为之的，因为 fetch 命令旨在用于检查 spider 如何下载页面。

可用的工具命令

本节包含可用内置命令的列表，以及描述和一些使用示例。请记住，您始终可以通过运行以下命令获取有关每个命令的更多信息：

scrapy <command> -h

您可以使用以下命令查看所有可用命令：

scrapy -h

命令有两种：一种只能从 Scrapy 项目内部运行（项目专用命令），另一种在没有活动 Scrapy 项目的情况下也能运行（全局命令），尽管它们从项目内部运行时行为可能略有不同（因为它们会使用项目覆盖的设置）。

全局命令

startproject
genspider
settings
runspider
shell
fetch
view
version

仅限项目的命令

crawl
check
list
edit
parse
bench

startproject

语法：scrapy startproject <project_name> [project_dir]
需要项目：否

在 project_dir 目录下创建一个名为 project_name 的新 Scrapy 项目。如果未指定 project_dir，则 project_dir 将与 project_name 相同。

使用示例

$ scrapy startproject myproject

genspider

语法：scrapy genspider [-t template] <name> <domain or URL>
需要项目：否

在当前文件夹中或在当前项目的 spiders 文件夹中（如果从项目内部调用）创建一个新的 spider。<name> 参数被设置为 spider 的 name，而 <domain or URL> 用于生成 spider 的 allowed_domains 和 start_urls 属性。

使用示例

$ scrapy genspider -l
Available templates:
  basic
  crawl
  csvfeed
  xmlfeed

$ scrapy genspider example example.com
Created spider 'example' using template 'basic'

$ scrapy genspider -t crawl scrapyorg scrapy.org
Created spider 'scrapyorg' using template 'crawl'

这只是一个基于预定义模板创建 spider 的便捷快捷命令，但绝不是创建 spider 的唯一方法。您可以自己创建 spider 源代码文件，而不必使用此命令。

crawl

语法：scrapy crawl <spider>
需要项目：是

使用 spider 开始抓取。

支持的选项

-h, --help：显示帮助消息并退出
-a NAME=VALUE：设置 spider 参数（可以重复）
--output FILE 或 -o FILE：将抓取到的项目追加到 FILE 末尾（使用 - 表示标准输出）。要定义输出格式，请在输出 URI 末尾设置冒号（即 -o FILE:FORMAT）
--overwrite-output FILE 或 -O FILE：将抓取到的项目转储到 FILE 中，覆盖任何现有文件。要定义输出格式，请在输出 URI 末尾设置冒号（即 -O FILE:FORMAT）

使用示例

$ scrapy crawl myspider
[ ... myspider starts crawling ... ]

$ scrapy crawl -o myfile:csv myspider
[ ... myspider starts crawling and appends the result to the file myfile in csv format ... ]

$ scrapy crawl -O myfile:json myspider
[ ... myspider starts crawling and saves the result in myfile in json format overwriting the original content... ]

check

语法：scrapy check [-l] <spider>
需要项目：是

运行合约 (contract) 检查。

使用示例

$ scrapy check -l
first_spider
  * parse
  * parse_item
second_spider
  * parse
  * parse_item

$ scrapy check
[FAILED] first_spider:parse_item
>>> 'RetailPricex' field is missing

[FAILED] first_spider:parse
>>> Returned 92 requests, expected 0..4

list

语法：scrapy list
需要项目：是

列出当前项目中所有可用的 spider。输出为每行一个 spider。

使用示例

$ scrapy list
spider1
spider2

edit

语法：scrapy edit <spider>
需要项目：是

使用 EDITOR 环境变量或（如果未设置）EDITOR 设置中定义的编辑器来编辑给定的 spider。

此命令仅作为最常见情况的便捷快捷方式提供，开发人员当然可以自由选择任何工具或 IDE 来编写和调试 spider。

使用示例

$ scrapy edit spider1

fetch

语法：scrapy fetch <url>
需要项目：否

使用 Scrapy 下载器下载给定的 URL，并将内容写入标准输出。

此命令的有趣之处在于它抓取页面的方式与 spider 下载页面的方式完全相同。例如，如果 spider 具有覆盖 User Agent 的 USER_AGENT 属性，它将使用该属性。

因此，此命令可用于“查看”您的 spider 将如何抓取某个页面。

如果在项目外部使用，则不会应用任何特定的针对 spider 的行为，它将仅使用默认的 Scrapy 下载器设置。

支持的选项

--spider=SPIDER：绕过 spider 自动检测，强制使用特定的 spider
--headers：打印响应的 HTTP 标头，而不是响应正文
--no-redirect：不要遵循 HTTP 3xx 重定向（默认是遵循它们）

使用示例

$ scrapy fetch --nolog http://www.example.com/some/page.html
[ ... html content here ... ]

$ scrapy fetch --nolog --headers http://www.example.com/
{'Accept-Ranges': ['bytes'],
 'Age': ['1263   '],
 'Connection': ['close     '],
 'Content-Length': ['596'],
 'Content-Type': ['text/html; charset=UTF-8'],
 'Date': ['Wed, 18 Aug 2010 23:59:46 GMT'],
 'Etag': ['"573c1-254-48c9c87349680"'],
 'Last-Modified': ['Fri, 30 Jul 2010 15:30:18 GMT'],
 'Server': ['Apache/2.2.3 (CentOS)']}

view

语法：scrapy view <url>
需要项目：否

在浏览器中打开给定的 URL，就像您的 Scrapy spider “看到”的那样。有时 spider 看到的页面与普通用户不同，因此这可以用来检查 spider “看到”了什么，并确认是否符合您的预期。

支持的选项

--spider=SPIDER：绕过 spider 自动检测，强制使用特定的 spider
--no-redirect：不要遵循 HTTP 3xx 重定向（默认是遵循它们）

使用示例

$ scrapy view http://www.example.com/some/page.html
[ ... browser starts ... ]

shell

语法：scrapy shell [url]
需要项目：否

为给定的 URL（如果已给定）启动 Scrapy shell，如果未给定 URL 则启动为空。还支持 UNIX 风格的本地文件路径，可以是带有 ./ 或 ../ 前缀的相对路径，也可以是绝对文件路径。有关更多信息，请参阅 Scrapy shell。

支持的选项

--spider=SPIDER：绕过 spider 自动检测，强制使用特定的 spider
-c code：在 shell 中执行代码，打印结果并退出
--no-redirect：不遵循 HTTP 3xx 重定向（默认是遵循它们）；这仅影响您可能作为命令行参数传递的 URL；进入 shell 后，fetch(url) 默认仍会遵循 HTTP 重定向。

使用示例

$ scrapy shell http://www.example.com/some/page.html
[ ... scrapy shell starts ... ]

$ scrapy shell --nolog http://www.example.com/ -c '(response.status, response.url)'
(200, 'http://www.example.com/')

# shell follows HTTP redirects by default
$ scrapy shell --nolog http://httpbin.org/redirect-to?url=http%3A%2F%2Fexample.com%2F -c '(response.status, response.url)'
(200, 'http://example.com/')

# you can disable this with --no-redirect
# (only for the URL passed as command line argument)
$ scrapy shell --no-redirect --nolog http://httpbin.org/redirect-to?url=http%3A%2F%2Fexample.com%2F -c '(response.status, response.url)'
(302, 'http://httpbin.org/redirect-to?url=http%3A%2F%2Fexample.com%2F')

parse

语法：scrapy parse <url> [options]
需要项目：是

抓取给定的 URL 并由处理它的 spider 进行解析，使用通过 --callback 选项传递的方法，如果未提供则使用 parse。

支持的选项

--spider=SPIDER：绕过 spider 自动检测，强制使用特定的 spider
--a NAME=VALUE：设置 spider 参数（可以重复）
--callback 或 -c：用作解析响应的回调函数的 spider 方法
--meta 或 -m：将传递给回调请求的附加请求元数据 (meta)。这必须是有效的 json 字符串。示例：--meta='{"foo" : "bar"}'
--cbkwargs：将传递给回调函数的附加关键字参数。这必须是有效的 json 字符串。示例：--cbkwargs='{"foo" : "bar"}'
--pipelines：通过管道 (pipeline) 处理项目
--rules 或 -r：使用 CrawlSpider 规则来发现用于解析响应的回调函数（即 spider 方法）
--noitems：不显示抓取到的项目
--nolinks：不显示提取的链接
--nocolour：避免使用 pygments 对输出着色
--depth 或 -d：应递归遵循请求的深度级别（默认值：1）
--verbose 或 -v：显示每个深度级别的信息
--output 或 -o：将抓取到的项目转储到文件中

使用示例

$ scrapy parse http://www.example.com/ -c parse_item
[ ... scrapy log lines crawling example.com spider ... ]

>>> STATUS DEPTH LEVEL 1 <<<
# Scraped Items  ------------------------------------------------------------
[{'name': 'Example item',
 'category': 'Furniture',
 'length': '12 cm'}]

# Requests  -----------------------------------------------------------------
[]

settings

语法：scrapy settings [options]
需要项目：否

获取 Scrapy 设置的值。

如果在项目内部使用，它将显示项目设置值，否则它将显示该设置的默认 Scrapy 值。

用法示例

$ scrapy settings --get BOT_NAME
scrapybot
$ scrapy settings --get DOWNLOAD_DELAY
0

runspider

语法：scrapy runspider <spider_file.py>
需要项目：否

运行包含在 Python 文件中的自包含 spider，而无需创建项目。

用法示例

$ scrapy runspider myspider.py
[ ... spider starts crawling ... ]

version

语法：scrapy version [-v]
需要项目：否

打印 Scrapy 版本。如果与 -v 一起使用，它还会打印 Python、Twisted 和平台信息，这对于错误报告很有用。

bench

语法：scrapy bench
需要项目：否

运行快速基准测试。基准测试。

运行爬取的命令

许多命令需要运行某种形式的抓取，既可以运行用户提供的 spider，也可以运行特殊的内部 spider。

bench
check
crawl
fetch
parse
runspider
shell
view

为此，它们使用 scrapy.crawler.AsyncCrawlerProcess 或 scrapy.crawler.CrawlerProcess 的内部实例。在大多数情况下，运行命令的用户无需关心此细节，但当用户需要非默认的 Twisted reactor 时，这可能很重要。

Scrapy 根据 TWISTED_REACTOR 设置的值决定使用这两个类中的哪一个。如果设置值是默认值 ('twisted.internet.asyncioreactor.AsyncioSelectorReactor')，将使用 AsyncCrawlerProcess，否则将使用 CrawlerProcess。在进行此操作时不会考虑 spider 设置，因为它们是在做出此决定后加载的。如果项目级设置被设置为 asyncio reactor（显式设置或通过使用 Scrapy 默认值），而正在运行的 spider 的设置被设置为另一个 reactor，这可能会导致错误，因为 AsyncCrawlerProcess 仅支持 asyncio reactor。在这种情况下，您应该将 FORCE_CRAWLER_PROCESS 设置为 True（在项目级别或通过命令行），以便 Scrapy 使用支持所有 reactor 的 CrawlerProcess。

自定义项目命令

您还可以通过使用 COMMANDS_MODULE 设置来添加自定义项目命令。有关如何实现命令的示例，请参阅 scrapy/commands 中的 Scrapy 命令。

COMMANDS_MODULE

默认值：''（空字符串）

用于查找自定义 Scrapy 命令的模块。这用于为您的 Scrapy 项目添加自定义命令。

示例：

COMMANDS_MODULE = "mybot.commands"

通过 setup.py 入口点注册命令

您还可以通过在库 setup.py 文件的入口点 (entry points) 中添加 scrapy.commands 部分，来添加来自外部库的 Scrapy 命令。

以下示例添加了 my_command 命令：

from setuptools import setup, find_packages

setup(
    name="scrapy-mymodule",
    entry_points={
        "scrapy.commands": [
            "my_command=my_scrapy_module.commands:MyCommand",
        ],
    },
)

命令行工具

配置设置

Scrapy 项目的默认结构

项目间共享根目录

使用 scrapy 工具

创建项目

控制项目

可用的工具命令

startproject

genspider

crawl

check

list

edit

fetch

view

shell

parse

settings

runspider

version

bench

运行爬取的命令

自定义项目命令

COMMANDS_MODULE

通过 setup.py 入口点注册命令

使用 `scrapy` 工具