Nginx 配置详解（静态 HTML、下载目录、API 反向代理三套场景）

Nginx 配置详解（静态HTML、下载目录、API反向代理三套场景）

基础文件结构：一般主配置 nginx.conf，业务配置放到 conf.d/ 下，比如 site.conf，下面全部写在 conf.d/site.conf 里，方便管理。

核心区分：

html：静态网页，直接返回文件

download：文件下载目录（支持断点、目录浏览可选）

api：反向代理转发后端接口（Java/Python等服务）

一、最简完整示例（可直接复制）

nginx 复制代码

server {
    listen       80;
    server_name  localhost; # 换成你的域名/IP

    # 1、静态HTML站点 【根路径 / 访问网页】
    location / {
        root   /usr/share/nginx/html; # html文件目录
        index  index.html index.htm;
        try_files $uri $uri/ /index.html; # SPA单页应用必备（vue/react）
        charset utf-8;
    }

    # 2、文件下载目录 访问地址：http://xxx/download/
    location /download/ {
        alias /data/files/download/; # 注意末尾 / ，和上面路径对应
        autoindex on;        # 开启目录浏览（不需要就off）
        autoindex_exact_size off; # 文件大小显示MB/KB，不显示字节
        autoindex_localtime on;   # 使用本地时间
        # 断点续传
        add_header Accept-Ranges bytes;
    }

    # 3、API代理 访问地址：http://xxx/api/xxx 转发到后端服务
    location /api/ {
        proxy_pass [http://127.0.0.1:8080/](http://127.0.0.1:8080/); # 后端地址，末尾斜杠很关键！
        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;

        # 超时配置
        proxy_connect_timeout 300s;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

二、分模块详细讲解

✅ 1、静态HTML（location /）

nginx 复制代码

location / {
    root   /usr/share/nginx/html;
    index  index.html index.htm;
    try_files $uri $uri/ /index.html;
}

root：资源根目录，/a.html → 读取 /usr/share/nginx/html/a.html
index：默认首页文件
try_files $uri $uri/ /index.html;
- 普通静态页面可以不加；Vue/React 单页项目必须加，刷新404就是缺这一行
charset utf-8; 防止中文乱码

root 和 alias 区别（重点）

root：拼接 root路径 + location路径

alias：直接替换匹配路径，download 场景优先用 alias

✅ 2、Download 文件下载目录（location /download/）

nginx 复制代码

location /download/ {
    alias /data/files/download/;
    autoindex on;
    autoindex_exact_size off;
    autoindex_localtime on;
}

autoindex on：访问 /download/ 列出文件夹里所有文件（内网文件服务器常用，公网谨慎开启）
关闭目录浏览：autoindex off;，只能直接访问文件链接 xxx/download/1.zip
权限提醒：nginx进程用户（nginx/www）要有 /data/files/download/ 的读权限
如果要限制下载速度，加：

nginx 复制代码

limit_rate 1M; # 单文件限速1MB/s
limit_rate_after 10M; # 前10M不限速

✅ 3、API反向代理（location /api/）

nginx 复制代码

location /api/ {
    proxy_pass [http://127.0.0.1:8080/](http://127.0.0.1:8080/);
    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_pass 末尾斜杠大坑：

proxy_pass [http://127.0.0.1:8080/](http://127.0.0.1:8080/); 带 /
请求 /api/user → 转发到 [http://127.0.0.1:8080/user](http://127.0.0.1:8080/user)（去掉/api前缀）

proxy_pass [http://127.0.0.1:8080](http://127.0.0.1:8080); 不带 /
请求 /api/user → 转发到 [http://127.0.0.1:8080/api/user](http://127.0.0.1:8080/api/user)（保留/api前缀）
根据后端接口路径选择！

X-Real-IP：后端Java/Python拿真实客户端IP必备
适合后端SpringBoot、FastAPI等接口服务

三、常用附加配置（按需加）

跨域（如果前端和api跨域调试用，生产优先后端处理）

放到 /api/ location 内部：

nginx 复制代码

add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Methods GET,POST,PUT,DELETE,OPTIONS;
add_header Access-Control-Allow-Headers *;
if ($request_method = OPTIONS) {
    return 204;
}

缓存静态资源（html静态资源加速）

放到 html 的 location 里：

nginx 复制代码

location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
    root /usr/share/nginx/html;
    expires 7d; # 缓存7天
    add_header Cache-Control "public";
}

禁止访问某些后缀（安全）

nginx 复制代码

location ~* \.(sh|sql|env|conf)$ {
    deny all;
}

四、Docker版Nginx配套说明（你前面一直在用docker）

挂载目录参考：

bash 复制代码

docker run -d \
--name nginx \
-p 80:80 \
-v /data/nginx/conf.d:/etc/nginx/conf.d \
-v /data/nginx/html:/usr/share/nginx/html \
-v /data/files/download:/data/files/download \
nginx

把上面的 site.conf 放到 /data/nginx/conf.d/
html文件丢 /data/nginx/html
下载文件丢 /data/files/download

校验命令：

bash 复制代码

# 检查配置语法
nginx -t
# 重载配置（不中断服务）
nginx -s reload

五、访问路由汇总（对照上面配置）

访问地址	作用
http://ip/	静态首页 index.html
http://ip/download/	文件下载列表
http://ip/download/a.zip	直接下载文件
http://ip/api/user/list	转发给后端 8080 接口