Nginx 配置(静态站与反向代理)
大约 3 分钟
Nginx 配置(静态站与反向代理)
本文记录本站 nginx 的实际配置,并给出后续要挂后端服务时的反向代理模板。
最后更新:2026-11-20
1. 目录约定
/etc/nginx/
├── nginx.conf # 主配置
├── sites-available/
│ └── my-docs # 本站站点配置(真实文件)
├── sites-enabled/
│ └── my-docs -> ../sites-available/my-docs # 软链接,启用标志
└── conf.d/ # 其他片段约定:站点真实文件放 sites-available,启用与否由 sites-enabled 里的软链接决定。禁用站点:
sudo rm -f /etc/nginx/sites-enabled/my-docs2. 本站实际配置
文件:/etc/nginx/sites-available/my-docs
# my-docs (VuePress) - static site
# root is a symlink to /var/www/my-docs/releases/<timestamp>
server {
listen 443 ssl;
listen [::]:443 ssl ipv6only=on;
server_name ouyangss.site www.ouyangss.site;
root /var/www/my-docs/dist;
index index.html;
charset utf-8;
ssl_certificate /etc/letsencrypt/live/ouyangss.site/fullchain.pem; # managed by Certbot
ssl_certificate_key /etc/letsencrypt/live/ouyangss.site/privkey.pem; # managed by Certbot
include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
location / {
try_files $uri $uri/ $uri.html /index.html;
}
location /assets/ {
expires 30d;
add_header Cache-Control "public, immutable";
try_files $uri =404;
}
location = /favicon.ico {
access_log off;
log_not_found off;
}
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_comp_level 5;
gzip_types text/plain text/css application/javascript application/json image/svg+xml application/xml;
}
server {
listen 80;
listen [::]:80;
server_name ouyangss.site www.ouyangss.site;
return 301 https://$host$request_uri; # managed by Certbot
}2.1 逐块说明
| 指令 | 作用 |
|---|---|
root /var/www/my-docs/dist | 指向软链接,发布切换后无需 reload |
index index.html | 目录请求默认取 index.html |
try_files $uri $uri/ $uri.html /index.html | 静态文件 → 目录 → xxx.html → 前端路由回退 |
location /assets/ | VuePress 构建产物带内容哈希,可放心长缓存 |
expires 30d + immutable | 浏览器 30 天不重复请求 |
try_files $uri =404 | 资源缺失时返回真 404,避免把 HTML 当 JS 返回 |
gzip_types | 文本类资源压缩,CSS 可从 125KB 压到约 25KB |
2.2 生效与校验
sudo nginx -t # 语法检查,必须先通过
sudo systemctl reload nginx # 平滑重载,不断连接
sudo systemctl restart nginx # 仅在 reload 无效时使用3. 反向代理模板(备将来挂后端)
假设要把 /api/ 转发到本机 127.0.0.1:8081 的 Java 服务:
location /api/ {
proxy_pass http://127.0.0.1:8081/;
proxy_http_version 1.1;
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 10s;
proxy_read_timeout 60s;
}要点:
proxy_pass末尾带/会剥掉匹配前缀;想保留/api就不要加- 后端要能拿到真实客户端 IP,务必传
X-Real-IP/X-Forwarded-For - 为了让后端生成正确的重定向地址,传
X-Forwarded-Proto - WebSocket 需要额外配置:
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";4. 日志
/var/log/nginx/access.log
/var/log/nginx/error.log常用排查:
tail -f /var/log/nginx/error.log
grep -c ' 404 ' /var/log/nginx/access.log
awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head日志由 logrotate 自动切割,无需手工清理。
5. 常见坑
| 现象 | 原因 | 处理 |
|---|---|---|
| 改完配置不生效 | 只改了 sites-available 没建软链接 | ln -sfn 到 sites-enabled 后 reload |
| 刷新子页面 404 | 缺 try_files ... $uri.html /index.html | 补上前端路由回退 |
| 静态资源被当 HTML 返回 | try_files 回退到了 /index.html | 资源目录用 try_files $uri =404 |
| 访问走了默认站点 | 默认站点 default 仍启用,抢占 80 | 删除 /etc/nginx/sites-enabled/default |
| 403 Forbidden | root 目录权限或文件属主不对 | chown -R www-data:www-data,目录 755 |
| 中文乱码 | 响应头缺少 UTF-8 | charset utf-8; |
| 修改证书路径后不生效 | 多个 server 块抢占同一 server_name | nginx -T | grep -n server_name 排查 |
鄂公网安备42011102006488号