Browsershot 禁用 HTTP 重定向：disableRedirects() 的用法、原理与安全实践

导读：在 Browsershot 中用 url() 抓取网页生成截图或 PDF 时，目标站点可能基于地域、Cookie、登录态等因素发生 301/302 跳转，将请求带到你并不希望访问的域名，既可能触发内网/外网访问限制，也存在安全隐患。本文围绕 Browsershot 提供的 disableRedirects() 方法，讲解其用法、底层拦截原理、行为边界，并结合源码与测试用例给出可直接落地的完整示例。

为什么需要禁用重定向

Browsershot 基于无头 Chromium（通过 Node 脚本 bin/browser.cjs 驱动）渲染 URL。默认情况下浏览器会完整跟随 HTTP 重定向链，直到拿到最终页面。这在大多数场景下符合直觉，但在两类场景中会成为问题：

• 环境访问受限：你的运行环境（如 CI、内网沙箱、无外网权限的服务器）不允许访问重定向后的目标域名，跟随跳转会导致请求失败或访问被拒；
• 安全隔离：目标页面可能在服务端根据来源、设备或 Cookie 将请求 302 到钓鱼页、广告域名或恶意站点，出于安全审查需要禁止一切跳转。

官方文档对此的表述非常明确："To avoid redirects to domains that are not allowed in your environment, or for security reasons you can disable HTTP redirects."（为避免跳转到环境中不允许的域名，或出于安全原因，可以禁用 HTTP 重定向）。

基本用法：一行链式调用

disableRedirects() 是一个零参数、返回 static（支持链式调用）的公开方法，与 save()、setScreenshotType()、setOption() 等方法一样可以随时插入调用链：

use Spatie\Browsershot\Browsershot;

Browsershot::url('http://www.spatie.be')
   ->disableRedirects()
   ->save($pathToPdf);

该方法内部只是把选项写入配置集合：

public function disableRedirects(): static
{
    return $this->setOption('disableRedirects', true);
}

（见 src/Browsershot.php）

由于它是通用选项，同时作用于 PDF、截图、HTML 抓取等所有渲染动作，并且可以与其他链式方法自由组合，例如：

Browsershot::url('https://example.com/login')
    ->disableRedirects()
    ->waitUntilNetworkIdle()
    ->setScreenshotType('png')
    ->save('login.png');

底层原理：选项如何传递到 Chromium

要理解 disableRedirects() 究竟做了什么，需要先看清 Browsershot 的选项传递链路：

1. setOption('disableRedirects', true) 通过 arraySet()（支持 key.subkey 点号嵌套）写入 $this->additionalOptions，见 arraySet 实现；
2. createCommand() 在构建渲染命令时，会把 additionalOptions 递归合并进命令的 options 字段，见 createCommand；
3. 最终由 getFullCommand() 将整份命令 JSON 序列化后交给 Node 脚本执行，见 getFullCommand。

在 Node 侧（bin/browser.cjs），disableRedirects 是触发请求拦截（request interception）的条件之一。从源码可以看到，只要设置了 disableRedirects，页面就会开启 CDP 请求拦截，并注册一条专门的重定向拦截规则：

const blockRedirect = (req) => {
    if (!options.disableRedirects) return false;
    if (!req.isNavigationRequest() || !req.redirectChain().length) return false;
    req.abort();
    return true;
};

（见 bin/browser.cjs）

这段逻辑可以拆解为三个关键判断：

• !options.disableRedirects —— 未开启该选项时直接放行，零开销；
• !req.isNavigationRequest() —— 只拦截页面级导航请求，图片、XHR、脚本等子资源请求不受影响；
• !req.redirectChain().length —— 只有重定向链非空（即该请求本身经历了至少一次跳转）才会被终止。

也就是说，disableRedirects 的精确语义是：当一个导航请求已经发生过重定向时，立即 abort() 它，禁止继续跟进到跳转目标；而直接返回 200 OK 的正常导航请求不会被误伤。

另外值得注意，请求拦截仅在“确实需要”时才开启。bin/browser.cjs 中的 needsInterception 判断了 disableImages、blockDomains、blockUrls、disableRedirects、额外请求头、自定义页面内容、POST 参数等多个条件，任一命中才开启拦截。这样既能支持重定向禁用，又避免无条件拦截给页面加载引入时序干扰（源码注释中也明确提到无条件拦截可能被反爬系统探测到）。

行为边界：什么会被拦，什么不会

结合仓库测试可以精确验证 disableRedirects 的两个行为边界（见 tests/BrowsershotTest.php）：

场景一：重定向页面 → 渲染失败并抛异常

it('no redirects - will not follow redirects', function () {
    $targetPath = __DIR__.'/temp/redirect_fail.pdf';

    Browsershot::url('http://www.spatie.be')
        ->disableRedirects()
        ->save($targetPath);

    expect($targetPath)->not->toBeFile();
})->throws(ProcessFailedException::class);

访问 http://www.spatie.be 时，站点会 301 跳转到 https:// 版本。开启 disableRedirects 后导航请求被 abort，页面无法完成加载，save() 最终抛出 ProcessFailedException，目标文件不会生成。这说明在实际使用中要为这种情况做好异常捕获，例如重试或回退到最终直链。

场景二：直接 200 OK → 正常渲染

it('no redirects - will still render direct 200 OKs', function () {
    $targetPath = __DIR__.'/temp/redirect_success.pdf';

    Browsershot::url('https://spatie.be/')
        ->disableRedirects()
        ->save($targetPath);

    expect($targetPath)->toBeFile();
});

访问本就返回 200 OK 的 https://spatie.be/，即使开启了 disableRedirects 也一切正常，页面照常渲染、文件照常生成。

这两个测试共同证明：disableRedirects 不是"禁止访问所有会跳转的站点"，而是"禁止跟随已经发生的跳转"。如果目标 URL 本身就是最终地址（无跳转），功能完全不受影响；只有存在重定向时，渲染才会被中断。

进阶组合：用 redirectHistory() 定位跳转来源

当页面渲染结果与预期不一致（例如截图内容和浏览器里看到的不一样），往往就是重定向链在"作祟"——站点可能根据地域、Cookie、设备等返回不同的跳转目标。Browsershot 提供了配套的 redirectHistory() 方法来还原整个跳转过程（见 读取重定向历史文档）：

$redirects = Browsershot::url('https://www.spatie.be')
    ->redirectHistory();

foreach ($redirects as $redirect) {
    print $redirect['url'] . PHP_EOL;
    print $redirect['status'] . PHP_EOL;
    print $redirect['reason'] . PHP_EOL;
    foreach ($redirect['headers'] as $name => $value) {
      print $name . ' : ' . $value . PHP_EOL;
    }
    print PHP_EOL;
}

它记录的不只是 HTTP 重定向，还包括 JavaScript 跳转与 HTML 层面的跳转。返回的每条记录包含：

• url：跳转请求的目标地址；
• status：HTTP 状态码（如 301、302）；
• reason：状态文本（如 Moved Permanently）；
• headers：响应头（可从中看到 Location 等关键跳转信息）。

从源码看，redirectHistory() 在底层会构造一个 action = 'redirectHistory' 的命令（见 createRedirectHistoryCommand），Node 侧则通过监听主框架导航请求的 response 事件逐条收集记录（见 bin/browser.cjs），最终由 ChromiumResult 统一解析返回（见 src/ChromiumResult.php）。

实战中推荐的工作流是：先用 redirectHistory() 还原跳转链，确认目标 URL 的真实最终地址；再决定是直接改用最终地址渲染，还是用 disableRedirects() 强制中断跳转。

与其他选项的配合

disableRedirects() 可以和同属"请求管控"家族的选项组合使用，形成更精细的访问策略：

• blockDomains($array) / blockUrls($array)：按域名或 URL 片段直接拒绝请求（abort），实现"白名单式"访问控制（见 src/Browsershot.php）；
• preventUnsuccessfulResponses()：当最终响应不成功时抛出自定义异常（对应 prevent-unsuccessful-responses 文档），可与 disableRedirects 配合把"被中断的跳转"显式转化为可捕获的业务异常；
• writeOptionsToFile()：把整份渲染命令 JSON 写入临时文件再交给 Node 执行（见 writing-options-to-file 文档），调试选项传递问题时非常有用——启用后可以直观地看到 disableRedirects: true 是否被正确序列化进了命令。

完整实战示例

下面是一个"先诊断、再拦截"的完整示例：先读取重定向历史判断站点行为，再对需要严格控制的站点禁用重定向并妥善处理失败：

use Spatie\Browsershot\Browsershot;
use Symfony\Component\Process\Exception\ProcessFailedException;

// 1. 诊断：查看目标站点的跳转链
$redirects = Browsershot::url('https://example.com')
    ->redirectHistory();

foreach ($redirects as $redirect) {
    printf(
        "%d %s -> %s%n",
        $redirect['status'],
        $redirect['reason'],
        $redirect['url']
    );
}

// 2. 管控：禁止跟随跳转，并将失败转化为可处理的异常
try {
    Browsershot::url('http://www.spatie.be')
        ->disableRedirects()
        ->timeout(30)
        ->save('snapshot.pdf');
} catch (ProcessFailedException $e) {
    // 页面存在重定向且被禁用，渲染中断
    // 这里可改为回退到 redirectHistory 返回的最终 URL 重试
    report($e);
}

注意事项与限制

• 渲染中断是预期行为：一旦发生重定向，页面会被强制 abort()，对应 save() 会抛出 ProcessFailedException（测试用例已证实），调用方必须捕获或接受该异常，不能指望"跳过跳转继续渲染原页面"；
• 只作用于导航请求：JS 发起的 XHR/fetch 请求以及图片、脚本等子资源不受 disableRedirects 影响；
• 与 redirectHistory() 的语义互补：前者是"禁止跳转"，后者是"记录跳转"，二者都是围绕重定向这一主题的诊断/管控手段，建议搭配阅读相关文档；
• 适用版本以当前仓库为准：上述源码路径与行为均基于本仓库当前实现（src/Browsershot.php、bin/browser.cjs），如升级依赖请以对应版本的实际源码为准。

综上，disableRedirects() 是 Browsershot 面向"重定向管控"提供的一个小而精的选项：一行代码即可切断导航重定向链，配合 redirectHistory() 可以完成"诊断 → 决策 → 管控"的完整闭环，适合对访问域有严格限制或安全敏感的场景。