Yii::$app->response->sendFile()在NGINX环境下无法触发文件下载

这个问题我之前帮朋友排查过，确实是Nginx和Yii的响应头传递配合出了点小问题，别着急，咱们一步步来解决：

第一步：先确认Yii代码的调用是否正确 #

虽然Apache下正常，但还是先确保sendFile()的参数没踩坑：

• 明确设置inline为false（默认值是false，但显式设置更稳妥），这个参数直接控制文件是直接显示还是触发下载
• 可以强制指定Content-Type为application/octet-stream，让浏览器明确识别这是二进制文件，应该触发下载而非直接展示

示例代码：

return Yii::$app->response->sendFile(
    '/path/to/your/protected/file', // 不可直接访问的文件路径
    'user-friendly-filename.ext',   // 用户下载时看到的文件名
    [
        'inline' => false,
        'Content-Type' => 'application/octet-stream'
    ]
);

第二步：调整Nginx的FastCGI配置 #

这是最常见的问题根源——Nginx默认可能不会把Yii生成的Content-Disposition响应头传递给客户端。你需要在处理PHP请求的location块里添加关键配置：

# 在你的PHP处理location中添加这一行，确保响应头能正常传递
fastcgi_pass_header Content-Disposition;

完整的PHP请求location示例（根据你的实际PHP-FPM地址调整）：

location / {
    try_files $uri $uri/ /index.php?$args;
}

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php8.1-fpm.sock; # 换成你的PHP-FPM路径或端口
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    # 关键：传递Content-Disposition头
    fastcgi_pass_header Content-Disposition;
}

第三步：排查其他可能干扰的Nginx配置 #

1. 禁用特定文件类型的Gzip压缩：如果你的文件是文本类（如txt、csv），Nginx的Gzip压缩可能会干扰响应头逻辑。可以在server块里添加：

# 全局禁用Gzip（或者针对特定类型禁用）
gzip off;
# 或者只禁用文本类：
# gzip_types !text/plain !text/csv !text/html;

2. 避免静态文件规则拦截请求：确保你的下载请求是通过PHP处理的，而不是被Nginx的静态文件location拦截。比如如果有类似location ~* \.(pdf|txt)$的规则，要确保它不会匹配到你的下载路由（或者调整路由避开这些后缀）。

最后验证 #

修改Nginx配置后，记得执行sudo nginx -s reload重启服务，然后测试下载功能。如果还是有问题，可以打开浏览器的开发者工具，查看响应头里是否存在Content-Disposition: attachment; filename="xxx.ext"——只要这个头存在，浏览器就应该触发下载了。

内容的提问来源于stack exchange，提问作者Isan Rodriguez Trimiño