创建你的首个Scrapy工程 - 项目结构、配置与初始化完整指南

📂 所属阶段：第一阶段 — 初出茅庐（框架核心篇）
🔗 相关章节：Scrapy 五大核心组件 · Spider 实战

装完 Scrapy，大多数人的第一道坎，就是敲完 scrapy startproject 后面对一堆文件一脸懵，不知道从何改起。本文帮你快速理清核心结构、必改配置，并顺手生成一个能跑通的示例爬虫，把困惑一次性扫干净。

环境准备

基础要求

Python 版本：3.8 及以上（推荐 3.9/3.10，兼容性和效率最优）
操作系统：Windows / macOS / Linux 通用

安装与验证

强烈建议在虚拟环境中安装 Scrapy，方便隔离依赖：

# 创建并激活虚拟环境（Windows 用 venv\Scripts\activate）
python3 -m venv scrapy_env
source scrapy_env/bin/activate

# 安装 Scrapy
pip install scrapy

# 检查安装是否成功
scrapy version
# 输出示例：Scrapy 2.11.0

创建项目

Scrapy 提供了标准化的项目生成命令，不需要手动搭建文件夹结构：

# 1. 生成项目（项目名建议有意义，例如 news_crawler）
scrapy startproject news_crawler

# 2. 进入项目根目录
cd news_crawler

# 3. 查看生成的基础结构
ls -la       # Linux/macOS
dir          # Windows

项目结构详解

生成的项目采用了 Python 包 的架构，核心文件与目录如下：

news_crawler/
├── scrapy.cfg                 # 部署到 Scrapyd 的全局配置（开发时极少修改）
└── news_crawler/              # 项目业务代码包
    ├── __init__.py            # Python 包标识文件（空即可）
    ├── items.py               # 定义结构化数据字段（类似 ORM 模型）
    ├── middlewares.py         # 自定义请求/响应处理逻辑（中间件）
    ├── pipelines.py           # 数据清洗、去重、存储逻辑（管道）
    ├── settings.py            # 全局项目配置（核心！）
    └── spiders/               # 所有爬虫的存放目录
        ├── __init__.py        # 子包标识
        └── example.py         # 默认的示例爬虫（可删除）

核心文件优先级速览

开发初期，先把精力放在下面这几个文件上：

文件/目录	开发初期优先级	主要用途
`settings.py`	⭐⭐⭐⭐⭐	全局配置（UA、并发、延迟等）
`spiders/`	⭐⭐⭐⭐⭐	编写具体的爬取逻辑
`items.py`	⭐⭐⭐⭐	定义爬取的结构化数据
`pipelines.py`	⭐⭐⭐⭐	数据落地、清洗等
`middlewares.py`	⭐⭐⭐	高级功能：代理、UA 池等
`scrapy.cfg`	⭐	部署到线上 Scrapyd 时才需要改

配置文件详解

默认配置中的大多选项可以暂时不动，先把下面这几个改成适合自己的项目。

1. 基础标识与 User‑Agent

# settings.py
BOT_NAME = 'news_crawler'   # 项目名，一般不用改

# 必改项：指定 User-Agent（默认 UA 会被很多网站直接拦截）
USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36'

# 学习/测试阶段建议关闭 ROBOTSTXT_OBEY（生产环境请遵守协议或与网站协商）
ROBOTSTXT_OBEY = False

2. 反爬与速率限制

# settings.py
# 对同一域名的并发请求数（友善一点可设为 2~4，学习时可以 8）
CONCURRENT_REQUESTS_PER_DOMAIN = 4

# 两次请求间的固定延迟，单位秒
DOWNLOAD_DELAY = 1

# 在 DOWNLOAD_DELAY 基础上增加随机延迟（0.5~1.5 倍之间）
RANDOMIZE_DOWNLOAD_DELAY = True

3. 数据导出编码（学习测试必备）

# settings.py
FEED_EXPORT_ENCODING = 'utf-8'
# 这样导出的 JSON/CSV 文件在 Windows 和 macOS 下都不会乱码

创建第一个爬虫

使用 genspider 命令可以在 spiders/ 目录下快速生成爬虫模板：

# 命令格式：scrapy genspider 爬虫名 允许爬取的域名
scrapy genspider techcrunch techcrunch.com

运行后会自动生成 spiders/techcrunch.py，我们稍作修改就能爬取文章标题和链接：

# spiders/techcrunch.py
import scrapy

class TechcrunchSpider(scrapy.Spider):
    name = 'techcrunch'                              # 爬虫唯一标识
    allowed_domains = ['techcrunch.com']             # 只爬取该域名下的链接
    start_urls = ['https://techcrunch.com/category/startups/']

    def parse(self, response):
        """
        解析响应：提取文章标题、链接，并实现自动翻页
        """
        for article in response.css('article.post-block'):
            yield {
                'title': article.css('a.post-block__title__link::text').get().strip(),
                'url': article.css('a.post-block__title__link::attr(href)').get(),
            }

        # 翻页逻辑：查找下一页链接并继续跟踪
        next_page = response.css('div.wp-block-query-pagination a.next::attr(href)').get()
        if next_page:
            # follow 方法会自动拼接相对路径并检查 allowed_domains
            yield response.follow(next_page, callback=self.parse)

验证与测试

1. 运行爬虫，实时查看结果

在项目根目录下执行：

scrapy crawl techcrunch

2. 将数据导出到本地文件

# 导出为 JSONL（推荐，逐行存储便于后续处理）
scrapy crawl techcrunch -o techcrunch_startups.jsonl

# 也支持其他格式：JSON、CSV、XML 等
scrapy crawl techcrunch -o techcrunch_startups.csv

3. 用 Scrapy Shell 交互调试选择器

如果 CSS 选择器不确定是否写对，可以用 Shell 实时测试：

scrapy shell 'https://techcrunch.com/category/startups/'

进入 Shell 后尝试提取：

# 提取第一篇文章标题
response.css('a.post-block__title__link::text').get().strip()

# 调试完毕退出
exit()

常见问题排查

1. `scrapy` 命令找不到

原因：Python 的 Scripts 目录未加入系统 PATH
解决：
- 虚拟环境：先激活对应的虚拟环境再使用
- 全局安装：
  - Windows：将 C:\Users\你的用户名\AppData\Local\Programs\Python\Python3x\Scripts 添加至 PATH
  - macOS/Linux：确保 which python3 和 which pip3 指向你正在使用的 Python 环境

2. 爬虫启动后立即退出，没有输出数据

原因：大概率是 CSS/XPath 选择器写错了，无法匹配到任何内容
解决：用 Scrapy Shell 逐条验证选择器，确认能提取到内容

3. 返回 403 Forbidden 错误

原因：默认 UA 被屏蔽、缺少 Cookie、请求频率过高
解决：修改 USER_AGENT，适当增大 DOWNLOAD_DELAY，必要时考虑添加 Cookie

最佳实践建议

虚拟环境隔离：每个项目单独创建虚拟环境，避免依赖冲突
先调选择器再写代码：所有选择器都先在 Scrapy Shell 中测试通过
结构化数据：尽量使用 items.py 定义数据模型，而不是直接 yield 字典，便于后期维护和扩展
保留日志：在 settings.py 中添加 LOG_FILE = 'logs/scrapy.log'，方便回溯问题

💡 核心要点：刚上手时，把注意力集中在 settings.py 和 spiders/ 两个地方，其他文件（middlewares、pipelines）可以在真正需要时再深入，不要一开始就把自己绕晕。

#创建你的首个Scrapy工程 - 项目结构、配置与初始化完整指南

#环境准备

#基础要求

#安装与验证

#创建项目

#项目结构详解

#核心文件优先级速览

#配置文件详解

#1. 基础标识与 User‑Agent

#2. 反爬与速率限制

#3. 数据导出编码（学习测试必备）

#创建第一个爬虫

#验证与测试

#1. 运行爬虫，实时查看结果

#2. 将数据导出到本地文件

#3. 用 Scrapy Shell 交互调试选择器

#常见问题排查

#1. scrapy 命令找不到

#2. 爬虫启动后立即退出，没有输出数据

#3. 返回 403 Forbidden 错误

#最佳实践建议