Nginx | 解决 Spring Boot 与 Nginx 中的 “413 Request Entity Too Large“ 错误

`关注：CodingTechWork`

引言

在 Web 开发中，413 Request Entity Too Large 是一种常见的 HTTP 错误，它指示客户端请求的实体（例如文件或数据）超出了服务器允许的最大大小。对于使用 Spring Boot 和 Nginx 的应用程序来说，处理和解决这一问题需要理解几个关键技术原理，包括 HTTP 协议、Spring Boot 配置、以及 Nginx 的上传限制。本文将深入探讨这一错误的原因，并提供基于 Spring Boot 和 Nginx 的解决方案。

什么是 413 Request Entity Too Large 错误？

介绍

HTTP 状态码 413 Request Entity Too Large 表示请求的主体部分（如表单数据或文件）超出了服务器允许处理的大小限制。这通常发生在以下场景：

客户端上传的文件或数据超过了服务器的最大接收限制。
客户端请求的 HTTP 请求体（包括文件和其他数据）超过了服务器的最大限制。
在开发文件上传、数据提交等功能时，遇到 413 错误较为常见，尤其是在处理大文件或批量数据时。

413 Request Entity Too Large 产生原因

413 错误通常由以下几种因素导致：

Spring Boot 应用限制： Spring Boot 默认配置了文件上传和请求体大小的限制。如果上传的文件或数据超过了这个限制，Spring Boot 会返回 413 错误。
Nginx 配置限制：当 Spring Boot 后端与 Nginx 作为反向代理共同工作时，Nginx 也可能会设置上传体积的最大限制。如果请求体超出了该限制，Nginx 会拒绝该请求并返回 413 错误。
代理或负载均衡器：如果请求经过了其他代理服务器（如 HAProxy、Cloudflare 等），它们也可能设置了上传大小的限制。

Spring Boot 中的上传限制

Spring Boot 默认对文件上传和请求体的大小进行了限制，通常会通过以下配置项来控制：

配置文件上传大小限制

在 Spring Boot 中，可以通过 application.properties 或 application.yml 来配置文件上传的大小限制：

使用 application.properties 配置

properties 复制代码

 # 限制单个文件最大为 10MB
spring.servlet.multipart.max-file-size=10MB   
 # 限制整个请求体最大为 10MB
spring.servlet.multipart.max-request-size=10MB

使用 application.yml 配置

yaml 复制代码

spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 10MB

这些配置项的含义：

max-file-size: 限制上传的单个文件大小。
max-request-size: 限制整个 HTTP 请求体的大小（如果上传多个文件，包含所有文件及其他表单数据）。

自定义上传限制

对于更复杂的场景，Spring Boot 允许开发者自定义文件上传的限制。例如，在 application.properties 中可以通过配置：

properties 复制代码

 # 启用文件上传功能
spring.servlet.multipart.enabled=true  
 # 设置临时文件存储目录
spring.servlet.multipart.location=/tmp/uploads

当上传文件时，Spring Boot 会使用 MultipartResolver 来处理文件数据，这些配置会影响文件的上传过程。

Nginx 中的上传限制

当 Spring Boot 应用部署在使用 Nginx 作为反向代理的环境中时，Nginx 会影响请求的处理。如果上传的文件或数据超过了 Nginx 的最大请求体大小，Nginx 会返回 413 Request Entity Too Large 错误。

配置 Nginx 的上传限制

Nginx 使用 client_max_body_size 配置项来限制客户端请求体的大小。默认情况下，Nginx 的限制为 1MB，这对于大多数现代应用来说往往过小。

找到 http、server 或 location 配置块，并在其中添加或修改 client_max_body_size 指令。这个指令定义了客户端可以上传的最大文件大小。例如，要允许上传最大为 100MB 的文件，可以这样设置：

nginx 复制代码

http {
    client_max_body_size 100M;  # 设置最大上传文件为 100MB
    # 其他配置...
}

或者，如果你只想为特定的站点（server）或路径（location）设置，可以这样配置：

nginx 复制代码

server {
    listen 80;
    server_name example.com;

    client_max_body_size 100M;  # 为这个站点设置最大上传文件为 100MB

    # 其他配置...
}

或者在某个特定路径下设置：

nginx 复制代码

location /upload {
    client_max_body_size 100M;  # 只针对 /upload 路径设置
}

client_max_body_size: 用于设置 Nginx 接受的最大请求体大小。如果上传的请求体超过这个限制，Nginx 会返回 413 错误。

重新加载 Nginx 配置

修改 Nginx 配置后，需要重新加载配置文件以使改动生效：

bash 复制代码

sudo nginx -t    # 测试配置文件是否正确
sudo systemctl reload nginx  # 重新加载 Nginx 配置

Spring Boot 与 Nginx 配合时的常见问题

在 Spring Boot 与 Nginx 配合时，容易遇到以下问题：

请求体大小限制不一致

如果 Nginx 和 Spring Boot 的上传限制设置不一致，可能导致请求在经过 Nginx 时被拒绝，甚至没有传递到 Spring Boot 应用程序。例如，如果 Nginx 的 client_max_body_size 限制为 10MB，而 Spring Boot 设置为 20MB，那么上传请求会在 Nginx 阶段被拦截，Spring Boot 不会收到该请求。

解决方案：确保 Nginx 和 Spring Boot 的配置一致，尤其是在文件上传大小和请求体大小方面。

Nginx 配置的 client_max_body_size 设置过小

Nginx 默认的 client_max_body_size 设置可能过小，导致上传大文件时出现问题。根据实际需求，调整该值。

文件上传过程中的性能问题

在处理大文件上传时，不仅要关注请求体大小，还需要优化文件上传的性能。比如：

在 Nginx 和 Spring Boot 中配置适当的缓冲区大小。
在 Spring Boot 中使用异步处理文件上传，避免阻塞主线程。

进一步优化和解决方案

使用分片上传（Chunked Uploads）

对于大文件上传，分片上传是解决上传限制的一种常用技术。分片上传将文件分成多个小块逐个上传，每个块的数据量较小，能够绕过服务器的上传大小限制。Spring Boot 可以与前端库（如 Resumable.js 或 Fine Uploader）配合，提供高效的分片上传支持。

使用 Nginx 的代理缓存

对于频繁上传大文件的场景，使用 Nginx 的代理缓存可以提高上传的性能。Nginx 可以缓存文件上传的请求，从而避免每次都从头开始上传。

nginx 复制代码

proxy_cache_path /tmp/nginx_cache levels=1:2 keys_zone=upload_cache:10m max_size=1g;
location /upload/ {
    proxy_cache upload_cache;
    proxy_pass http://localhost:8080;
}

设置合理的客户端文件大小验证

在客户端进行文件大小验证，避免上传超大文件，提前在用户端进行筛查，可以有效减轻服务器的负担。

javascript 复制代码

let fileInput = document.getElementById('fileInput');
fileInput.addEventListener('change', function () {
    let file = fileInput.files[0];
    // 限制文件大小为 100MB
    if (file.size > 100 * 1024 * 1024) {  
        alert("文件超过最大允许大小！");
        // 清空文件输入框
        fileInput.value = "";  
    }
});

总结

413 Request Entity Too Large 错误通常由上传大小限制引起，解决这一问题需要从多个方面入手：

调整 Spring Boot 配置：在 application.properties 或 application.yml 中设置合适的文件上传和请求体大小。
配置 Nginx：通过 client_max_body_size 设置 Nginx 的上传限制，确保与 Spring Boot 配置一致。
使用分片上传技术：对于大文件上传，考虑使用分片上传技术，避免单个请求体过大。
优化客户端验证：在客户端对文件大小进行验证，减少不必要的上传请求。