nginx中文件下载指定保存文件名怎么配置

# nginx中文件下载指定保存文件名怎么配置

## 前言

在Web服务中，文件下载是常见的功能需求。默认情况下，浏览器会根据URL的最后一部分作为下载文件名，但有时我们需要动态指定更友好的文件名。本文将详细介绍如何在nginx中通过配置实现下载文件时指定保存文件名。

---

## 一、默认下载行为分析

当用户访问 `http://example.com/files/document.pdf` 时：
1. 浏览器会自动将文件名保存为 `document.pdf`
2. 若URL不含文件名（如通过API接口返回文件），则可能保存为无意义的随机字符串

---

## 二、核心配置指令：`add_header Content-Disposition`

通过设置HTTP响应头的 `Content-Disposition` 字段可以控制下载行为：

```nginx
location /download/ {
    add_header Content-Disposition 'attachment; filename="custom_name.pdf"';
}

参数说明：

• attachment：强制浏览器下载而非直接打开
• filename：指定客户端保存时使用的文件名

三、动态文件名配置方案

方案1：使用变量（推荐）

location ~ ^/download/(.*)$ {
    add_header Content-Disposition 'attachment; filename="$1"';
    alias /var/files/;
}

当访问 /download/report2023.xlsx 时： - 实际文件路径：/var/files/report2023.xlsx - 下载保存名：report2023.xlsx

方案2：rewrite+变量组合

location /download {
    rewrite ^/download/(.*)$ /real_files/$1;
    add_header Content-Disposition 'attachment; filename="$1"';
}

方案3：通过请求参数指定

location /api/download {
    if ($arg_filename) {
        add_header Content-Disposition 'attachment; filename="$arg_filename"';
    }
    alias /var/files/;
}

访问URL示例：/api/download?file=data.db&filename=backup.db

四、中文文件名处理

问题现象：

直接使用中文会出现乱码：

add_header Content-Disposition 'attachment; filename="中文文件.txt"';

解决方案：

使用RFC 5987编码：

add_header Content-Disposition 'attachment; filename*=UTF-8''%E4%B8%AD%E6%96%87%E6%96%87%E4%BB%B6.txt';

五、完整配置示例

server {
    listen 80;
    server_name example.com;

    # 静态文件下载
    location /static/ {
        alias /data/files/;
        add_header Content-Disposition 'attachment; filename="$uri"';
    }

    # 动态生成文件下载
    location /export {
        fastcgi_pass backend;
        add_header Content-Disposition 'attachment; filename="export_data.csv"';
    }

    # 带参数的文件下载
    location /download {
        if ($arg_fname) {
            add_header Content-Disposition 'attachment; filename="$arg_fname"';
        }
        alias /data/archives/;
    }
}

六、注意事项

1. 安全限制：确保文件名参数经过过滤，防止目录遍历攻击

   if ($arg_filename ~* "\.\.") { return 403; }
   

2. MIME类型：建议同时配置正确的Content-Type

   types { application/octet-stream .bin; }
   

3. 浏览器兼容性：

   • 新版浏览器支持RFC 5987编码
   • 旧版IE可能需要额外兼容处理

4. 性能影响：大量小文件下载时建议开启sendfile

   sendfile on;
   

结语

通过合理配置 Content-Disposition 响应头，nginx可以灵活控制文件下载时的保存文件名。实际部署时建议结合业务场景选择静态配置或动态方案，并注意做好安全防护。对于更复杂的需求，还可以考虑结合Lua脚本等扩展实现。 “`