周一至周五 09:00 - 18:00(UTC+08:00) 
©2026 NST LABS TECH LTD. 保留所有权利。 如何在 2026 年的 Splash 中设置代理 - 分步指南Ivy LinCommunity & Content Lead
如何在2026年设置Splash中的代理 - 分步指南
简要总结
- Splash 通过一个 HTTP 参数
proxy 代理请求,该参数接受一个代理 URL 或一个命名配置文件。 URL 格式为 [protocol://][user:password@]host[:port],协议可以是 http 或 socks5,如果省略则默认端口为 1080。
- 命名代理配置文件需要使用
--proxy-profiles-path 启动 Splash,并指向一个包含 .ini 文件的文件夹;除非请求明确传递 proxy=none,否则 default.ini 配置文件会自动应用于每个请求。
- 每个配置文件的
[proxy] 部分包含 host、port、可选的 username/password 和 type(HTTP 或 SOCKS5),而其 [rules] 部分通过 allowlist/denylist 正则模式限制代理仅适用于匹配的 URL。
- 对于每请求或每资源的代理逻辑,Splash 的 Lua API 在
splash:on_request 回调中公开 request:set_proxy{host, port, username, password, type}, 该回调在请求发送之前运行,并可以为同一页面的不同资源类型分配不同的代理。
- scrapy-splash 不改变 Splash 的 HTTP 参数,因此 的 字典可以以原始 调用的相同方式携带 。
SplashRequest
args
render.html
proxy
如 Nstproxy 这样的轮转代理提供者可以插入上述三种方法的任意一种 — 直接 URL、配置文件 .ini 或 Lua set_proxy — 因为 Splash 将代理视为普通的 host:port 加上可选的凭据,无论是谁颁发它们。
引言:在不失去方向的情况下通过 Splash 路由流量
Splash 是 Scrapinghub/Zyte 的无头、可编程浏览器渲染服务,通常通过其 HTTP API 或通过 scrapy-splash Scrapy 集成访问。它能渲染 JavaScript 密集的页面,并返回 HTML、PNG、JSON 或 HAR,但默认情况下,每个渲染请求都通过 Splash 自己的出站 IP 离开 Splash 主机。那些通过 IP 指纹识别、按 ASN 阻止或按源地址限速的网站将以相同的方式对待每个请求,无论爬虫访问多少不同的目标页面——直到在 Splash 和目标网站之间有一个代理。
Splash 提供了三种不同的方式来插入该代理:用于一次性或手动轮换代理的单个 proxy 请求参数,一个用于可重用命名配置文件的 .ini 文件文件夹 --proxy-profiles-path,以及用于每请求或每资源类型控制的 Lua request:set_proxy 调用。本指南逐一介绍这三种方法,并介绍在 Scrapy 蜘蛛中传递 proxy 值所需的 scrapy-splash 接线,最后介绍如何将轮换的住宅代理池插入上述三种方法的任意一种。
前提条件
- 一个正在运行的 Splash 实例——下面的示例使用官方的
scrapinghub/splash Docker 镜像,因为 Splash 自身的 安装文档 建议在大多数设置中使用 Docker,而不是本地 Python 安装。Splash 的源代码和问题跟踪器位于 scrapinghub/splash repository 上的 GitHub。
- 本地安装了 Docker(或可以通过 8050 端口访问的远程主机)。
- 从提供者处获得的代理凭据——主机、端口和(如果需要)用户名/密码。本文中不会打印真实凭据;每个示例使用占位符,如
YOUR_PROXY_HOST 和 YOUR_PROXY_PASSWORD。
- 安装了
scrapy 和 scrapy-splash(pip install scrapy scrapy-splash),仅适用于使用 Scrapy 的部分。
以下命令均未在本环境中执行真实的 Splash 容器——没有可用的 Docker 运行时。每个命令和参数名称都与 Splash 自身的文档和源代码(splash.readthedocs.io,github.com/scrapinghub/splash)进行检查,而不是凭空想象,并且每个代码块下方标记为 illustrative 或 config-only。
安装并启动 Splash
按照其文档推荐的方式启动 Splash,将 API 端口映射到主机。此命令符合文档中的语法;在本环境中未实时执行(没有可用的 Docker 运行时),因此将其视为 illustrative:
docker run -it -p 8050:8050 --rm scrapinghub/splash
API 可通过 http://localhost:8050 访问。在接入代理之前确认其响应:
curl 'http://localhost:8050/render.html?url=https://example.com/'
快速查看
一旦 Splash 可以直接访问目标网站,下一个失败模式通常是目标网站阻止了 Splash 自己的 IP 地址 — 像 Nstproxy 的 Residential Lite 代理这样的旋转住宅池为每个会话提供了一个新的出站 IP,而不是每个网站都可以标记的一个静态地址。
使用 proxy 请求参数配置代理
通过代理路由单个渲染调用的最快方法是 Splash 的 proxy 请求参数,可用于 render.html、render.png、render.json、execute 和其他渲染端点。它接受的代理 URL 形式为 [protocol://][user:password@]proxyhost[:port],其中协议为 http 或 socks5,如果未指定端口,默认为 1080:
curl 'http://localhost:8050/render.html?url=https://example.com/&proxy=http://YOUR_PROXY_USER:YOUR_PROXY_PASSWORD@YOUR_PROXY_HOST:YOUR_PROXY_PORT'
当脚本在请求时组装代理 URL 时,这是正确的工具 — 例如,在每次 Splash 调用之前从提供商那里提取一个新的旋转会话端点。当同一个代理需要自动应用于每个请求而无需每次重复 URL 时,这个工具就不适合;这正是代理配置文件处理的内容。
使用 .ini 文件配置可重用的代理配置文件
代理配置文件是一个命名的 .ini 文件,Splash 在启动时读取一次,然后按名称重用,而不是完整的 URL。通过使用 --proxy-profiles-path 启动 Splash,将其指向一个文件夹来启用配置文件:
python3 -m splash.server --proxy-profiles-path=/etc/splash/proxy-profiles
或者,使用 Docker,将该文件夹挂载到容器预期路径中(说明性 — 文档语法,未在此实时执行):
docker run -p 8050:8050 \
-v /local/path/to/proxy-profiles:/etc/splash/proxy-profiles \
scrapinghub/splash
每个配置文件是一个带有 [proxy] 部分和可选的 [rules] 部分的 .ini 文件(仅配置,保存为 /etc/splash/proxy-profiles/myprovider.ini):
[proxy]
host=YOUR_PROXY_HOST
port=YOUR_PROXY_PORT
username=YOUR_PROXY_USER
password=YOUR_PROXY_PASSWORD
type=HTTP
[rules]
allowlist=
.*
denylist=
.*\.(png|jpg|jpeg|gif|css|woff)$
host 和 port 是必需的;username、password 和 type 是可选的(type 默认为 HTTP,Splash 也接受 SOCKS5)。[rules] 段的 allowlist 和 denylist 是换行分隔的正则表达式:请求仅在其 URL 匹配 allowlist 且不匹配 denylist 时被代理,因此上面的示例代理除了常见静态资源扩展外的所有内容。
将文件保存为 default.ini 在配置文件夹中,以便自动应用于每个请求,而无需命名,或者将其保存为其他名称并显式引用:
curl 'http://localhost:8050/render.html?url=https://example.com/&proxy=myprovider'
在任何单个请求中传递 proxy=none,以跳过配置的 default.ini 配置文件。这个区分 — 一个静默激活的 default.ini 与一个必须指定名称的配置文件 — 是大多数关于 “我的代理未被使用” 报告的单一最常见来源:请求要么匹配了 denylist 规则,要么 default.ini 覆盖了假设没有代理设置的情况。
使用 Lua 脚本 API 按请求控制代理
Splash 的 Lua 脚本端点(execute)可以在请求发送之前检查和修改请求,使用 splash:on_request 回调和请求对象的 set_proxy 方法:
这个 Lua 脚本是 说明性 的 — 匹配文档的请求对象 API,而不是对实时 Splash 实例执行:
function main(splash, args)
splash:on_request(function(request)
if request.url:find("%.png$") or request.url:find("%.jpg$") then
request.abort()
return
end
request:set_proxy{
host = "YOUR_PROXY_HOST",
port = tonumber("YOUR_PROXY_PORT"),
username = "YOUR_PROXY_USER",
password = "YOUR_PROXY_PASSWORD",
type = "HTTP",
}
end)
assert(splash:go(args.url))
assert(splash:wait(0.5))
return splash:html()
end
set_proxy 仅在 splash:on_request 内部工作,并且只能在请求实际发送之前调用——在回调中稍后调用将没有效果。对于不需要身份验证的代理,请省略 username 和 password。设置 type = "HTTP" 仍会正确代理 HTTPS 目标,因为 Splash 使用标准的 CONNECT 方法实现该情况,而不需要单独的 HTTPS 代理类型。
此回调每个资源触发一次,而不是每个页面触发一次,因此脚本可以通过一个代理路由主文档,并跳过对同一页面上的图像、字体或分析信标的代理(或使用不同的代理)——这正是 proxy 参数或静态配置文件单独无法实现的,因为两者都仅适用于单个渲染调用的层面。
将脚本作为 lua_source 参数发送到 execute 端点:
curl 'http://localhost:8050/execute?url=https://example.com/&lua_source=...'
将 scrapy-splash 与代理集成
scrapy-splash 将 Scrapy 请求发送到一个 Splash 实例,并将 args 字典直接转发为 Splash 自身的请求参数,因此 args 内部的 proxy 键的行为与之前使用的 proxy 查询字符串参数完全相同。该软件包的 README 文档列出了确切的中间件和设置名称。
安装并配置 Scrapy 需要路由请求通过 Splash 的中间件:
pip install scrapy scrapy-splash
这个 settings.py 片段是 config-only,与 scrapy-splash 的文档 README 值匹配:
SPLASH_URL = 'http://localhost:8050'
DOWNLOADER_MIDDLEWARES = {
'scrapy_splash.SplashCookiesMiddleware': 723,
'scrapy_splash.SplashMiddleware': 725,
'scrapy.downloadermiddlewares.httpcompression.HttpCompressionMiddleware': 810,
}
SPIDER_MIDDLEWARES = {
'scrapy_splash.SplashDeduplicateArgsMiddleware': 100,
}
REQUEST_FINGERPRINTER_CLASS = 'scrapy_splash.SplashRequestFingerprinter'
然后在 SplashRequest 的 args 中传递 proxy:
这个爬虫示例是一个 prerequisite-gap —— 它并未在此环境中的实时 Splash+Scrapy 堆栈上执行,因为没有可用的 Docker/网络运行时:
from scrapy import Spider
from scrapy_splash import SplashRequest
class ProxyExampleSpider(Spider):
name = "proxy_example"
def start_requests(self):
yield SplashRequest(
url="https://example.com/",
callback=self.parse,
args={
"proxy": "http://YOUR_PROXY_USER:YOUR_PROXY_PASSWORD@YOUR_PROXY_HOST:YOUR_PROXY_PORT",
"wait": 0.5,
},
endpoint="render.html",
)
def parse(self, response):
yield {"title": response.css("title::text").get()}
args 值一一映射到 Splash 的 HTTP API 参数,因此命名代理配置文件以相同方式工作:args={"proxy": "myprovider"}。由于 SplashDeduplicateArgsMiddleware 通过其 Splash 参数指纹识别请求,在每个请求中轮换 proxy 值(而不是重用一个静态值)也防止了 Scrapy 的去重层将轮换代理请求视为彼此的重复。
通过 Splash 路由旋转代理提供商
以上三个 Splash 机制都期望关于代理的三个或四个事实:主机、端口,以及对于经过身份验证的池——用户名和密码。旋转住宅或数据中心代理提供商正好提供这些事实,通常通过一个共享的网关主机和端口在后台每个会话或请求旋转出口 IP,因此无需更改 Splash 的代理处理来使用它。
Nstproxy 提供 HTTP(S) 及 SOCKS5 兼容的代理网关,涵盖多个产品线,包括 Residential Lite Proxies,覆盖 50M+ 的住宅 IP,分布于 200 多个国家和地区,采用 预付费套餐计费模式。有关活跃计划的网关主机、端口和凭证详细信息,请在注册后查阅 Nstproxy 文档。因为 Splash 只需要标准的 host:port 以及可选的 user:pass 凭证,所以 Residential Lite 网关端点可以融入上述任何模式中——一次性调用的 proxy= URL 参数,固定默认值的配置文件 .ini 的 [proxy] 部分,或每个资源路由中的 Lua 的 request:set_proxy:
- 会话控制 — Nstproxy 的网关通常通过用户名字符串本身暴露粘性和旋转会话模式,这对于 Splash 很重要,因为配置文件
.ini 或 Lua 的 set_proxy 调用在文件或脚本的生命周期内是固定的;因此,轮换在提供商的侧面发生,每新会话进行,而不是通过编辑 Splash 的配置来实现。
- 协议匹配 — Splash的
type字段仅识别HTTP和SOCKS5;在编写配置文件之前,确认特定Nstproxy产品线网关期望的协议,因为将type值与实际网关协议不匹配会导致连接失败,这看起来像代理失败。
- 在不触碰Splash配置的情况下扩展 — 由于凭据存在于一个网关主机和端口中而不是单个代理IP的列表中,因此从一个Splash工作者扩展到多个工作者无需在这些工作者之间分发或轮换代理服务器列表。
快速了解一下
Splash的Lua和基于配置文件的代理控制仅路由流量——它们不会自行轮换IP,因此将Splash与Nstproxy的住宅网关配对,实际上是在不同出口IP之间分散渲染请求。
排查“代理未被使用”
Splash中配置错误的代理很少会大声报错——它只是静默地回退到Splash自己的IP或阻止合法请求,这是scrapinghub/splash GitHub仓库中多个开放问题背后的反复投诉模式。请按顺序检查以下内容:
- 检查静默的
default.ini。 如果代理配置文件夹中存在default.ini文件,它会自动应用于每个请求;需要明确指定proxy=none才能绕过代理的请求。
- 检查
allowlist/denylist匹配。 配置文件的[rules]部分只代理符合允许列表且不符合拒绝列表的URL——未通过任一测试的目标URL将不通过代理获取,且不产生错误。
- 确认
type与网关的实际协议匹配。 向仅支持SOCKS5的网关请求HTTP代理(或反之)会导致连接失败,而不是清晰的“错误协议”消息。
- 记住
set_proxy的时机。 只有在splash:on_request内部调用时,才会生效;在Lua脚本的其他地方调用是静默无效的。
- 检查Splash是否确实使用
--proxy-profiles-path启动。 如果没有该标志,则不会加载命名配置文件,proxy=myprovider参数没有任何解析。
诚实的限制
Splash的代理支持完全在连接层面操作:主机、端口、协议和可选的认证。它不自行管理代理轮换、健康检查或会话粘性;这些行为必须来自于配置文件或set_proxy调用指向的host:port后面的内容,无论这是一个轮换URL的脚本还是提供商内部轮换会话的网关。Splash还在每次渲染调用或每个资源上应用代理,而不是像完整的浏览器自动化框架那样将代理范围设置为跨多个页面加载的持久会话。一旦抓取项目超出单个静态网关的限制并需要跨多个池的路由规则,请查看如何使用代理管理器抓取以获取下一层。
结论
Splash为抓取器提供了三个路由代理流量的杠杆——一次性proxy URL参数、通过--proxy-profiles-path加载的可重用配置文件.ini,以及在splash:on_request内部控制每个资源的Lua request:set_proxy调用——这三者都接受轮换代理提供者发出的相同主机/端口/凭证格式。使代理路由真正生效主要是要避免两种静默失败模式:一个被忽视的default.ini配置文件和allowlist/denylist不匹配,这让请求无代理通过而不产生错误。
常见问题
Splash在proxy请求参数中支持http和socks5,在代理配置文件.ini和Lua request:set_proxy type字段中支持HTTP/SOCKS5;没有单独的HTTPS代理类型,因为HTTP类型的代理通过CONNECT方法已经处理了HTTPS目标。
问:使用代理是否需要--proxy-profiles-path?
不需要——--proxy-profiles-path仅在使用命名的、可重用的代理配置文件时必需;一次性代理可以直接作为URL在proxy请求参数中传入,而不需要任何特殊的启动标志。
问:为什么我的Splash代理在某些请求中似乎被忽略了?
最常见的原因是代理配置文件的 [rules] 部分中存在不匹配的 allowlist/denylist 模式,default.ini 默默覆盖了假定的“无代理”请求,或者 request:set_proxy 调用放置在请求发送之前的 splash:on_request 以外的位置。
问:我可以为同一页面上的不同资源使用不同的代理吗?
可以——Lua 的 splash:on_request 回调每个资源(文档、图片、脚本等)调用一次,因此在该回调内部使用不同值调用 request:set_proxy 可以在单次渲染调用中通过不同的代理路由不同类型的资源。
问:scrapy-splash 需要特别的设置来传递代理吗?
不需要额外的设置,只需标准的 scrapy-splash 中间件设置——SplashRequest 的 args 字典中的 proxy 键会像直接 HTTP 调用中的 proxy 查询字符串参数一样被转发到 Splash。
不会——Splash 仅通过它所提供的主机、端口和凭证路由请求;实际的出口 IP 轮换必须来自代理提供商的网关(例如,轮换会话模式)或来自在请求之间更改代理值的脚本。
是的——本文中的所有内容都假设在网站条款下访问公开可用的页面;通过代理路由流量并不授权绕过身份验证、付费墙或对非公开数据的访问控制。
Ivy Lin
Aug. 20th 2026
立即访问住宅、数据中心、IPv6 与 ISP 高质量代理池。