1.2 安装与环境配置

1.2 安装与环境配置

本节摘要：Scrapy 依赖 Twisted 异步引擎与一批底层库，安装的坑几乎全出在"编译依赖"与"多环境错位"上。本节给出虚拟环境隔离下的标准安装流程、三类典型故障的排查路径，以及一份确认环境健康的验证清单。

上一节看完了整条铁路的地图，这一节把设备通电。环境问题最消耗新手耐心——报错信息里满是编译器和链接器的术语。把本节的排查清单收好，后面能省下至少一小时。

为什么推荐虚拟环境隔离

Scrapy 及其依赖会被全局 site-packages 吸收，而 Twisted 对其他网络库有版本要求。直接装进系统 Python，迟早和别的项目打架。标准做法是每个采集工程一个虚拟环境：

# Windows：创建并激活虚拟环境（Linux/macOS 用 source venv/bin/activate）
python -m venv venv
venv\Scripts\activate
python -m pip install --upgrade pip
​

激活后命令行前缀会出现环境名，此后安装的一切只进这个环境。确认 Python 版本在支持范围内：

python --version
# Python 3.11.4    （3.9 及以上均可，过旧的 3.7 会被新版依赖拒绝）
pip --version
# pip 24.0 from ...venv\lib\site-packages\pip (python 3.11)
​

输出里 venv 字样说明 pip 确实落在虚拟环境里——这是新手最容易漏验的一步：装了半天发现装进了系统 Python。

标准安装与验证

pip install scrapy
# Successfully installed Scrapy-2.11 Twisted-23.10.0 lxml-4.9.3 ...
​

装完先做三件事验证，而不是急着创建工程：

scrapy version -v
# Scrapy    : 2.11.0
# lxml      : 4.9.3.0
# libxml2   : 2.10.3
# cssselect : 1.2.0
# parsel    : 1.8.1
# w3lib     : 2.1.2
# Twisted   : 23.10.0
# Python    : 3.11.4 (CPython)
​

这条命令一次报出整条依赖链的版本。排障时把它贴出来求助，比一句"装不上"有用得多。再跑一个冒烟测试：

# 在交互式解释器里执行：确认核心组件能正常实例化
import scrapy
from scrapy.crawler import CrawlerProcess

class SmokeSpider(scrapy.Spider):
    name = "smoke"
    start_urls = ["https://httpbin.example.org/html"]   # 任意稳定测试页均可

    def parse(self, response):
        print("状态码:", response.status)      # 期望输出: 状态码: 200
        print("标题:", response.css("title::text").get())

process = CrawlerProcess(settings={"LOG_LEVEL": "INFO"})
process.crawl(SmokeSpider)
process.start()
​

控制台出现 状态码: 200 且日志以 Spider closed (finished) 收尾，说明从引擎到下载器的整条链路都通了。

三类典型安装故障

第一类：Twisted 装不上，报编译错误。 老版本 Twisted 在部分平台需要 C 编译器。解法按序尝试：升级 pip 让它拿到预编译轮子；仍失败则安装系统编译工具链（Windows 装 Build Tools，Debian 系装 build-essential）；再不行明确指定有轮子的版本号。

pip install --upgrade pip setuptools wheel   # 先升级工具链，多数编译错误就此消失
pip install Twisted==23.10.0                 # 指定带预编译包的版本兜底
​

第二类：装好了，命令找不到。 scrapy 命令依赖 Python 脚本目录在系统 PATH 里。报"不是内部或外部命令"时，先确认虚拟环境是否激活（前缀丢了就要重新激活），再确认用的是 pip 对应的那个 Python。

第三类：跑起来就报事件循环冲突。 在 Jupyter 或异步框架里嵌 Scrapy 会撞上"事件循环已存在"。新手阶段别在笔记本环境里跑爬虫，写进工程用命令行执行；确需嵌入时使用专门的桥接方案，那是进阶话题。

环境健康清单

交付前对着勾一遍：

• 虚拟环境激活，pip 指向 venv 内部；
• scrapy version -v 报出完整依赖链且无红色报错；
• 冒烟 Spider 能拿到 200 响应并打印标题；
• 系统时钟准确——TLS 证书校验对时间敏感，时钟偏差会造成一片"证书验证失败"假故障；
• 若在代理网络内，已设置 HTTP_PROXY 环境变量，否则下载器会莫名超时。

版本升级与冻结：环境的长期维护

环境不是装完就完。Scrapy 半年一个大版本，升级能拿到新特性，也可能带来行为变化——升级决策要有依据，而不是看到新版就手痒。

pip show scrapy | findstr Version    # 查当前版本
# Version: 2.11.0
pip install "scrapy==2.11.*"         # 冻结在大版本内升级补丁：稳
​

三条维护纪律：其一，requirements 文件里写明确的版本范围而不是不写版本——不写版本的安装等于把环境交给运气；其二，升级前在另一个虚拟环境里装新版，把现有工程跑一遍冒烟测试再切换，正式工程不做"原地升级"；其三，记录每次升级的动机与结果，一行字即可，下次回溯能省半天。

# 升级核对清单（示例记录）
2026-03-12  2.10 → 2.11  动机：需要新的接口签名特性  结果：全部测试通过，未回退
2026-06-02  2.11 → 2.12  动机：安全通告              结果：中间件顺序行为变化，已适配
​

还有一个跨项目场景值得交代：同一台机器上维护多个采集工程时，各自独立虚拟环境是底线。若两个工程必须共享一套环境（磁盘紧张的嵌入式场景等），把两个工程的依赖放一起跑一次 pip check，冲突会在部署前而不是运行中暴露。

pip check
# No broken requirements found.   或列出冲突的依赖对
​

⚠️ 常见坑：别用 root 或管理员权限直接 pip install。权限污染出的环境问题往往数周后才在别的项目里爆发，且极难追溯。

本节要点回顾

• 虚拟环境先行：每个采集工程独立隔离，安装前先验 pip 落点；
• 验证看依赖链：一条版本命令报出 Twisted、lxml 等全家版本，是排障的第一手材料；
• 冒烟测试连通：一个最小 Spider 跑通引擎到下载器全链路，才算环境就绪；
• 三类故障：编译错误升工具链、命令缺失查 PATH、事件循环冲突换执行方式。

设备通电了，下一节把车间的房间隔出来——创建工程、认认每个文件是干什么的。