Nginx 备忘录

发布时间: 2025-12-04

代理 WebSocket #

WebSocket 和 HTTP 使用相同端口

 location /api {
		# WebSocket 后端地址（替换为你的真实 WebSocket 地址）
		proxy_pass http://127.0.0.1:8080;  # 注意：WebSocket 地址无需加 /（根据后端配置调整）
		proxy_http_version 1.1;  # WebSocket 必须使用 HTTP/1.1

		# 关键：转发 WebSocket 握手升级头
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "upgrade";  # 固定为 "upgrade"
		proxy_set_header Host $host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

		# WebSocket 心跳保活（防止连接被断开）
		proxy_read_timeout 3600s;  # 长连接超时（1 小时，根据需求调整）
		proxy_send_timeout 3600s;
		proxy_set_header Origin "";  # 解决部分后端 Origin 校验问题（可选）
}

前端页面打包使用 Gzip #

前端页面如果使用 Gzip 压缩文件，代理不配置 Gzip 无法正常访问网页

http {
	gzip on;				# 开启 Gzip 压缩功能	
	gzip_min_length 1024;   # 触发压缩的最小文件 / 响应大小（单位：字节）	
	gzip_comp_level 5;  	# Gzip 压缩级别（1-9）	
	gzip_buffers 32 4k; 	# 压缩时使用的缓冲区大小
	server {
		
        listen       80;

        location / {
            root /www/example.com/web;
			index index.html index.htm;
            gzip_static on; # 启用 “预压缩文件优先” 功能	
		}
	}
}

请求体限制、缓冲区、高效文件传输 #

Nginx 413 错误 ,client_max_body_size 允许上传大小限制问题

http {
	client_max_body_size 100m; 	# 限制客户端请求体的最大大小（即上传文件 / POST 数据的最大体积）
	proxy_buffer_size 4k;    	# Nginx 接收客户端请求体时的内存缓冲区大小
	proxy_buffers 4 32k;  		# 代理请求时，Nginx 接收后端响应头的缓冲区大小
	sendfile on; 				# 代理请求时，Nginx 接收后端响应体的缓冲区配置	
	tcp_nopush on;				# 启用 sendfile 系统调用，优化静态文件传输性能	
								# 配合 sendfile 使用，优化 TCP 数据包发送策略	
	server {
		
        listen 80;

        location / {
            root /www/example.com/web;
			index index.html index.htm;
            gzip_static on; 
		}
	}
}

配置 SSL 证书 + 跨域处理 #

server {
    listen 443 ssl;
    server_name example.com;
    # ssl证书配置保留
    ssl_certificate example.crt;
    ssl_certificate_key example.key;

    # 普通GET/POST请求跨域头（带always）
    add_header Access-Control-Allow-Origin '*' always;
    add_header Access-Control-Allow-Methods 'GET,POST,OPTIONS,PUT,DELETE' always;
    add_header Access-Control-Allow-Headers 'DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,X-Access-Token' always;

    location / {
        if ($request_method = 'OPTIONS') {
            # 预检请求必须在这里完整重写所有跨域头，缺一不可
            add_header Access-Control-Allow-Origin '*' ;
            add_header Access-Control-Allow-Methods 'GET,POST,OPTIONS,PUT,DELETE' always;
            add_header Access-Control-Allow-Headers 'DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,X-Access-Token' always;
            add_header Access-Control-Max-Age 1728000 always;
            return 204;
        }

        proxy_pass http://后端地址;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

验证

curl -I -X OPTIONS -H "Origin: http://localhost:8080" https://example.com

正常返回

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,POST,OPTIONS,PUT,DELETE
Access-Control-Allow-Headers: DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization,X-Access-Token
Access-Control-Max-Age: 1728000