Requests 本地部署指南：让 HTTP 请求像说话一样简单

Requests Logo

一、项目介绍

在 Python 的生态里，很少有哪个库能像 Requests 这样成为"事实上的标准"。官方 README 只用一句话概括它：Requests 是一个简单而优雅的 HTTP 库。

它的设计目标是让发送 HTTP/1.1 请求变得极其容易：你不再需要手动把查询字符串拼到 URL 后面，也不用手动对 PUT、POST 数据做表单编码——如今直接用 json= 参数即可。按照 README 给出的数据，Requests 每周下载量约 3 亿次，被超过 400 万个仓库依赖，是 Python 世界被依赖最广的包之一。

无论是调用一个 REST API、抓取网页、上传文件，还是写爬虫的底层网络部分，Requests 几乎都是第一选择。它由 Python Software Foundation（PSF）维护，文档完善、行为稳定，是学习 HTTP 协议的绝佳入口。

Requests 侧边栏

为什么一个 HTTP 库能有如此高的下载量？因为它把"发请求"这件事的心智负担降到了最低：requests.get(url) 一行代码就能拿到响应，状态码、JSON、Cookie、文件上传都有顺手的接口。Python 标准库里虽然有 urllib，但 API 繁琐、样板代码多；Requests 则把常见场景都封装成了语义清晰的方法。哪怕你只是写个小脚本调一下内部接口，也几乎不会再回去碰 urllib。

二、官方信息

项目	信息
仓库地址	github.com/psf/requests
官方文档	requests.readthedocs.io
Star 数量	约 55k
主语言	Python
Python 要求	3.10+
维护方	Python Software Foundation
最近更新	2026-10-27

本文带你把 Requests 装好、发出第一个请求，并从"脚本写法"进阶到"生产写法"，让你的网络请求在真实环境里稳得住。

三、项目结构与核心特性

Requests 之所以流行，是因为它把 HTTP 里繁杂的细节都封装成了直观的对象。发起一个请求，得到一个 Response 对象；状态码、响应头、编码、正文、JSON 都挂在这个对象上，随手可取。

官方列出的核心能力包括：

Keep-Alive 与连接池：底层自动复用 TCP 连接，高频请求时性能更好。
国际域名与 URL：正确处理中文域名与非 ASCII 路径。
带 Cookie 持久化的 Session：requests.Session() 自动跨请求保留 Cookie，适合模拟登录。
浏览器式 TLS/SSL 验证：默认安全校验证书。
Basic 与 Digest 认证：一行代码带上账号密码。
类字典的 Cookies：读写像普通字典一样直观。
自动解压与解码：gzip、deflate 响应自动解包。
多部分文件上传（multipart）：files= 参数即可上传文件。
SOCKS 代理支持：配合 PySocks 可走 SOCKS5 代理。
连接超时、流式下载、分块请求：长接口与大文件都能稳妥处理。
自动遵守 .netrc：命令行工具场景下免去重复传凭证。

Requests 标识

适用场景

Requests 几乎是所有需要联网的 Python 程序的底座。写爬虫时它负责发请求拿页面；调内部 API 时它负责带鉴权发 JSON；微服务之间通信时它是客户端；自动化脚本用它下载文件、上传报表。它不追求异步与极致性能，而是把"同步、可靠、好用"做到了极致。日常 90% 的网络请求场景，用 Requests 都能优雅解决；只有当你需要并发几百上千个请求时，才需要切换到异步客户端。理解 Requests，也就理解了 HTTP 客户端该有的样子。

与同类工具对比

和 Python 标准库的 urllib 相比，Requests 的 API 简洁太多——几行代码搞定的事，urllib 要写样板代码。和 httpx 相比，Requests 是同步生态的事实标准、文档与资源最丰富；httpx 的优势是自带异步与 HTTP/2。和 aiohttp 相比，Requests 不追求并发，但写起来最省心。日常脚本、服务端同步调用，Requests 仍是首选；只有需要高并发异步时才换 httpx 或 aiohttp。

四、环境与版本要求

Python 3.10 及以上（README 明确写出的受支持版本）。
没有系统级依赖，pip 安装即可用。
如需 SOCKS 代理，需额外安装 PySocks。
克隆源码时，README 提醒可能需要加 -c fetch.fsck.badTimezone=ignore 以避免某个历史提交时间戳导致的报错。

提示：Requests 只负责 HTTP 客户端，不包含异步能力。如果你需要高并发异步请求，社区常用 httpx 或 aiohttp；但绝大多数脚本与服务端场景，Requests 完全够用。

五、本地部署步骤

1. 安装

Requests 发布在 PyPI，安装命令：

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

python -m pip install requests

官方建议用 python -m pip 的形式调用，以确保安装到当前激活的解释器环境中。

2. 验证安装

python -c "import requests; print(requests.__version__)"

能打印版本号即安装成功。

3. 发起第一个请求

官方 README 的经典示例：

>>> import requests
>>> r = requests.get("https://httpbin.org/basic-auth/user/pass", auth=("user", "pass"))
>>> r.status_code
200
>>> r.headers["content-type"]
"application/json; charset=utf8"
>>> r.encoding
"utf-8"
>>> r.text
'{"authenticated": true, ...'
>>> r.json()
{"authenticated": True, ...}

逐行说明：

requests.get(url, auth=(...))：发起 GET 请求并带上 HTTP Basic 认证；
r.status_code：HTTP 状态码，200 表示成功；
r.headers：响应头，类字典访问；
r.encoding：响应文本编码；
r.text：按解码方式得到的字符串正文；
r.json()：直接把 JSON 响应解析成 Python 字典。

4. 写一个 GET 小脚本

新建 demo_get.py：

import requests

resp = requests.get(
    "https://api.github.com/zen",
    timeout=10,            # 强烈建议永远设置超时
)
print(resp.status_code)
print(resp.text)

运行：

python demo_get.py

能打印出一句 GitHub 的 Zen 短语，说明网络请求通畅。

排错思路

请求卡住不动，九成是没设超时——timeout 是生产代码里最重要的参数，永远显式传入。HTTPS 证书报错时，不要图省事直接 verify=False，那会引入中间人风险；正确做法是把公司根证书加入信任链或指定 verify 路径。返回 401/403 时，检查鉴权头或 auth= 参数是否正确，以及是否漏带了必要的 Cookie。

需要高频请求同一域名时，用一个全局 Session 复用连接，比每次 requests.get 新建连接快得多。调试阶段可以把 resp.request.headers 与 resp.url 打印出来，确认实际发出的请求与你以为的一致——很多"奇怪的行为"其实是 URL 编码或头字段没按预期发送。

六、API 用法与示例

带查询参数：

resp = requests.get(
    "https://httpbin.org/get",
    params={"key1": "value1", "key2": "value2"},
    timeout=10,
)
# 实际请求的 URL 会自动拼成 ?key1=value1&key2=value2
print(resp.url)

POST JSON：

resp = requests.post(
    "https://httpbin.org/post",
    json={"name": "若琳", "score": 95},   # 自动设置 Content-Type: application/json
    timeout=10,
)
print(resp.json())

上传文件：

with open("report.pdf", "rb") as f:
    resp = requests.post(
        "https://httpbin.org/post",
        files={"file": ("report.pdf", f, "application/pdf")},
        timeout=30,
    )

使用 Session 维持登录态：

s = requests.Session()
s.post("https://httpbin.org/cookies/set/sessioncookie/12345")
r = s.get("https://httpbin.org/cookies")
print(r.json())   # 能看到刚才设置的 cookie

流式下载大文件：

with requests.get("https://example.com/big.iso", stream=True, timeout=60) as r:
    r.raise_for_status()
    with open("big.iso", "wb") as f:
        for chunk in r.iter_content(chunk_size=8192):
            f.write(chunk)

完整参数表与高级用法见官方文档。

生产环境的稳健写法

在脚本里随手写的 requests.get(url) 与在生产服务里调用的代码，差别往往体现在几个细节上。第一是永远带超时：没有超时的请求在网络抖动时会永久挂起，拖垮整个 worker。建议区分连接超时与读取超时，例如 timeout=(3.05, 30)。

第二是重试。网络请求遇到 502、503、连接重置是常态，生产代码通常配合 urllib3.util.retry.Retry 与 requests.adapters.HTTPAdapter 给 Session 装上自动重试：

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()
retry = Retry(total=3, backoff_factor=1, status_forcelist=[500, 502, 503, 504])
session.mount("https://", HTTPAdapter(max_retries=retry))

resp = session.get("https://example.com/api", timeout=(3.05, 30))
resp.raise_for_status()   # 4xx/5xx 直接抛异常

第三是复用 Session。同一域名的多次请求，用同一个 Session 能复用 TCP 连接与 Cookie，性能明显更好；第四是不要随意 verify=False，这会关闭证书校验，引入中间人风险；第五是敏感信息不要写进 URL 查询参数，它们会被代理与日志记录。

七、常见问题 FAQ

Q1：请求 HTTPS 网站报 SSL 证书错误？
A：默认情况下 Requests 会严格校验证书。如果是公司自签证书环境，可指定 verify 路径；切勿为了省事在生产环境直接 verify=False，那会引入中间人风险。

Q2：请求总是超时或卡住？
A：永远给 requests.get/post 传 timeout= 参数，否则网络异常时会无限等待。连接超时与读取超时可以分别用元组形式设置，例如 timeout=(5, 30)。

Q3：克隆源码时报 badTimezone 错误？
A：这是历史提交的时间戳问题。按 README 提示执行：git clone -c fetch.fsck.badTimezone=ignore https://github.com/psf/requests.git，或全局设置 git config --global fetch.fsck.badTimezone ignore。

Q4：需要并发请求很多 URL，Requests 够吗？
A：Requests 是同步库，高并发场景下建议改用异步客户端（如 httpx + asyncio）或配合线程池。简单脚本、低频调用则完全不必引入额外依赖。

Q5：怎么自动带代理？
A：通过 proxies= 参数或环境变量 HTTP_PROXY/HTTPS_PROXY；SOCKS 代理需要先安装 PySocks，然后使用 socks5:// 协议头。

小结

Requests 的成功在于它解决了一个根本问题：让 HTTP 像调用函数一样自然。日常脚本里，requests.get 几乎是本能；但写到生产服务时，要记得把"脚本习惯"升级成"工程习惯"——带上超时、装好重试、复用 Session、妥善处理异常与代理。这些细节不显眼，却决定了你的服务在网络抖动时是优雅降级还是直接崩溃。把这几个套路养成肌肉记忆，Requests 就能稳稳承担绝大多数 HTTP 通信任务。随着项目变大，你还会用到它的事件钩子、认证插件、流式响应等进阶能力，但日常开发中，"超时 + 重试 + Session + 异常处理"这四件套已经能解决八成问题。把它们封装成自己项目里的一个 http_client 模块，所有服务调用统一走它，能让整个代码库的网络行为更一致、更可控。

部署后的日常使用

日常使用中，建议把超时、重试、异常处理封装成一个共享的请求函数，项目里所有网络调用都走它，而不是各处散落 requests.get。调试第三方接口时，把 resp.status_code、resp.url、必要的请求头打印出来，往往一眼就能看出问题出在鉴权还是参数。需要下载大文件时永远用 stream=True 配合 iter_content，避免一次性把整个文件读进内存。把这套请求封装当成项目的基础设施维护，整个代码库的网络行为都会因此稳健许多。

写在最后

Requests 的流行不是偶然，它把"发 HTTP 请求"这件事的体验打磨到了近乎完美。对 Python 开发者来说，它可能是你每天都会用到、却很少深究的库。但真正用好它——超时、重试、Session、流式、异常处理——能让你的网络代码从"能跑"变成"可靠"。把这些习惯养成，你写的每一个联网程序都会更稳。它是少数"用得越久越觉得优雅"的库——API 稳定、文档清晰、生态成熟，几乎不会让你为网络层的问题耗费过多精力。掌握它之后，再去看任何 HTTP 客户端库，你都会有自己的判断标准：超时、重试、连接管理、可读性，缺一不可。这也是为什么它能长期占据 Python HTTP 库的榜首位置——它把该做对的事都做对了，而且 API 一直保持着优雅与克制。把这一个库用熟，你日常九成的网络请求问题都会有一个可靠的解法。把它的官方文档通读一遍，你还会发现许多日常被忽略的细节，比如会话复用、认证扩展与钩子机制，这些都能在关键时刻派上用场。作为 Python 生态里最知名的 HTTP 库，Requests 几乎是每一个联网项目的默认选择，值得你花一个下午把它的官方用法真正吃透。哪怕只是把超时、Session、异常处理这三件套用熟，你的代码质量都会上一个台阶，这也是每天都会用到的基本功。把它当作你工具箱里最顺手的那把螺丝刀，久而久之你会发现，凡是涉及网络的活儿，第一反应都是先想到它。它不追求花哨，而是把"发请求"这件事做得足够可靠、足够顺手，这种朴素的设计哲学恰恰是它长久流行的根本原因。把它装进你的项目，你会立刻感受到"让 HTTP 变得人性化"这句话背后的分量。它可能是你每天都会 import、却很少认真读过文档的库，而当你真的通读一遍，收获往往超出预期。作为 Python 生态最基础也最重要的网络库之一，Requests 值得你在项目里把它用到位。超时、重试、会话、流式，这几样用熟，网络层的坑就绕过了大半。把它们封装进一个共享的客户端，整个项目的网络调用都会更稳。这就是把一个基础库用熟所能带来的长远收益，值得现在就动手实践，把它用进你的下一个项目，你会立刻感受到它的好，从此离不开它，这就是经典库真正的力量。

工程化要点小结

把 Requests 用在生产环境，核心是把"脚本习惯"升级成"工程习惯"：永远显式设置超时、对可重试的错误加上退避重试、用全局 Session 复用连接、对非预期状态码抛出明确的异常。把这些逻辑封装成项目内一个统一的请求客户端，所有服务调用都走它，而不是在各处散落 requests.get。这样做的好处是：一旦需要加日志、加埋点、加鉴权头，你只改一个地方，整个项目的网络行为都会一致。这正是把一个基础库用熟所能带来的长远收益。

Requests 本地部署指南