Laravel Vapor应用API配置Cache-Control后仍无法被CloudFront缓存

架构老林

2026-7-11

CloudFront未缓存Laravel API端点响应的排查问题

我通过AWS Vapor部署了一个Laravel应用，希望某个API端点的响应能被CloudFront缓存，因此创建了如下中间件：

class CacheResponse
{
    public function handle(Request $request, Closure $next, int $maxAge): mixed
    {
        $response = $next($request);

        $response->header('Cache-Control', "public, max-age={$maxAge}");
        $response->header('Pragma', "public");

        return $response;
    }
}

随后注册该中间件：

protected $middlewareAliases = [
    ...
    'cache-response' => \App\Http\Middleware\CacheResponse::class,
];

最后将其绑定到路由：

Route::get('some/endpoint', [MyController::class, 'myMethod'])
    ->middleware('cache-response:300');

部署完成后，我多次请求该API端点，但CloudFront并未按预期缓存响应，返回的响应头如下：

Access-Control-Allow-Origin: *
Cache-Control: max-age=300, public
Content-Length: 27
Content-Type: application/json
Date: Fri, 01 Sep 2023 02:05:07 GMT
Pragma: public
Via: 1.1 55cf94331c5a848a09407c283669c546.cloudfront.net (CloudFront)
X-Amz-Apigw-Id: KjgBCG7pIAMF5uw=
X-Amz-Cf-Id:552YO9QGBl47xgpFH4XkGotHMO97dVTYkyJYhYFLtx2ofl7_0iFRJA==
X-Amz-Cf-Pop: LHR62-C2
X-Amzn-Remapped-Date: Fri, 01 Sep 2023 02:05:07 GMT
X-Amzn-Requestid: 17b394fa-83bc-4fac-a91a-0214b841a7ed
X-Amzn-Trace-Id: Root=1-64f146d3-562460c90fcd8ed06eb52c84;Sampled=0;lineage=9fbc8014:0
X-Cache: Miss from cloudfront

请问可能的原因是什么？

可能的原因分析

CloudFront缓存行为配置异常：检查CloudFront分发的缓存行为，确认针对该API路径的缓存策略是否允许缓存。默认情况下，若缓存策略设置Minimum TTL为0，或配置了“转发所有请求头”，会导致CloudFront不缓存响应；另外，若请求带有Authorization头，CloudFront默认也会跳过缓存。
请求头携带缓存禁用字段：如果请求中包含Cache-Control: no-cache或Pragma: no-cache，CloudFront会直接回源，不会缓存响应。需要检查请求头是否存在这类字段。
Laravel会话Cookie干扰：Laravel默认会给响应添加Set-Cookie头（即使API端点无需会话），而CloudFront默认不缓存带有Set-Cookie的响应。需确保该API端点未触发会话启动，例如给路由添加->withoutMiddleware(['web'])，或在缓存中间件中移除Set-Cookie头。
缓存键包含可变内容：CloudFront的缓存键默认包含请求方法、URL和查询字符串，若请求带有动态查询参数，或缓存键配置包含可变请求头（如X-Amzn-Trace-Id），会导致每个请求生成唯一缓存键，无法命中缓存。
API Gateway层的影响：AWS Vapor通过API Gateway转发请求，若API Gateway添加了额外头信息，或配置了阻止缓存的设置，会导致CloudFront无法缓存响应。需确认API Gateway是否修改了响应头或启用了相关限制。
缓存预热未完成或请求不一致：首次请求必然是Miss，后续请求需确保请求参数、头信息完全一致才会命中缓存。若每次请求存在细微差异（如不同的Date头），也会导致缓存无法复用。

内容的提问来源于stack exchange，提问作者Latheesan