React / 系统课时
配置 Nginx 与 HTTPS
配置 Nginx 与 HTTPS
本课把已经构建好的 React 前端、运行在本机端口的后端接口和公网域名接入同一个 Nginx 站点。完成后,静态资源可直接访问,/api/ 请求会转发到后端,前端刷新深层路由不会出现 404,并且所有 HTTP 请求都会跳转到 HTTPS。
学习目标
- 部署 React 构建产物并配置静态资源缓存
- 配置接口反向代理与前端路由回退
- 申请 HTTPS 证书并完成上线验证
明确部署结构与前置条件
生产请求先到达 Nginx。Nginx 直接返回 React 的静态文件;遇到 /api/ 前缀时,再把请求转发给只监听本机地址的 Node.js 服务。这样浏览器只访问一个域名,不需要暴露后端端口,也能避免前后端跨域配置。

开始前确认域名 app.example.com 已解析到服务器公网 IP,后端可通过 127.0.0.1:3000 访问,并且项目执行 npm run build 后会生成 dist 目录。示例使用 Ubuntu 或 Debian 系发行版,其他系统只需调整软件安装命令和目录。
先构建前端并复制静态文件:
# 构建完成后只同步 dist 内容,避免把源码放进站点目录。
npm ci
npm run build
sudo mkdir -p /var/www/react-app
sudo rsync -av --delete dist/ /var/www/react-app/
test -f /var/www/react-app/index.html && echo "static files ready"预期输出:
static files ready构建日志、文件大小和耗时会因项目而异;验收重点是 /var/www/react-app/index.html 存在。
配置静态资源、代理与路由回退
创建 /etc/nginx/conf.d/app.example.com.conf。其中 try_files $uri $uri/ /index.html 会在真实文件不存在时返回入口页,让 React Router 接管浏览器中的深层路由;proxy_pass 则把 /api/ 请求交给后端处理。Nginx 官方文档分别给出了 try_files 与反向代理的处理规则。:contentReference[oaicite:0]{index=0}
server {
listen 80;
server_name app.example.com;
root /var/www/react-app;
index index.html;
# API 请求保留 /api/ 前缀并转发到本机后端。
location /api/ {
proxy_pass http://127.0.0.1:3000;
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_set_header X-Trace-Id $request_id;
}
location /assets/ {
try_files $uri =404;
expires 1y;
add_header Cache-Control "public, immutable";
}
# 只有页面路由回退到入口文件,静态资源缺失仍返回 404。
location / {
try_files $uri $uri/ /index.html;
}
}预期结果:真实静态文件由 Nginx 返回,缺失的静态文件直接得到 404,只有页面路由回退到 index.html。后端必须实际提供与 /api/ 对应的接口路径;如果后端不保留该前缀,需要单独调整 proxy_pass 的路径规则。
先检查语法,再平滑重载。nginx -t 会校验配置语法并尝试打开配置引用的文件。:contentReference[oaicite:1]{index=1}
# 只有语法检查通过才执行平滑重载。
sudo nginx -t
sudo systemctl reload nginx
curl -I http://app.example.com/dashboard预期输出:
nginx: configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
HTTP/1.1 200 OK响应头中的日期、服务器版本和内容长度可能不同。若 /dashboard 返回 200,说明前端路由回退已经工作;若接口返回 502,应先直接检查 127.0.0.1:3000 上的后端是否存活。
申请证书并强制 HTTPS
安装 Certbot 的 Nginx 插件,然后让它完成域名校验、证书安装和 HTTP 跳转。执行前必须保证 80 端口可从公网访问,且域名解析已经生效。
# --redirect 让 Certbot 同时配置 HTTP 到 HTTPS 跳转。
sudo apt update
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d app.example.com --redirect预期输出:
<CERTBOT_SUCCESS_MESSAGE>实际成功提示会随 Certbot 版本变化,命令应以退出码 0 结束,并显示证书保存位置、部署域名和 HTTPS 重定向已配置。
Certbot 的实际提示文本会随版本和交互选项变化,但成功结果应包含证书已保存、已安装到 Nginx,并启用重定向。Certbot 的 Nginx 插件会把证书和私钥路径写入站点配置。:contentReference[oaicite:2]{index=2}
证书安装后,站点配置的关键结构应等价于下面的完整形式。证书路径中的域名必须与实际申请的域名一致:
server {
listen 80;
server_name app.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name app.example.com;
ssl_certificate /etc/letsencrypt/live/app.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
root /var/www/react-app;
index index.html;
# API 请求保留 /api/ 前缀并转发到本机后端。
location /api/ {
proxy_pass http://127.0.0.1:3000;
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_set_header X-Trace-Id $request_id;
}
location /assets/ {
try_files $uri =404;
expires 1y;
add_header Cache-Control "public, immutable";
}
# 只有页面路由回退到入口文件,静态资源缺失仍返回 404。
location / {
try_files $uri $uri/ /index.html;
}
}预期结果:80 端口统一返回 301,443 端口加载证书并提供静态资源和接口代理。Nginx 的 HTTPS 配置使用 listen 443 ssl、ssl_certificate 与 ssl_certificate_key 指定 TLS 监听和证书文件。:contentReference[oaicite:3]{index=3}
验证与典型故障处理
上线后同时验证重定向、证书、页面路由、接口代理和证书续期,避免只检查首页。
# 同时覆盖重定向、深层路由、接口代理和证书续期。
curl -I http://app.example.com
curl -I https://app.example.com/dashboard
curl -i https://app.example.com/api/health/live
sudo certbot renew --dry-run预期结果:
HTTP 请求返回 301,Location 指向 https://app.example.com/
HTTPS 深层路由返回 200
健康检查接口返回 200 和后端定义的存活响应体
证书模拟续期成功出现 403 时检查 /var/www/react-app 及其父目录是否允许 Nginx 用户读取;出现 404 时区分“页面路由”与“真实静态文件”,不要把所有缺失资源都回退到入口页;出现 502 时检查后端进程、监听地址和端口;证书申请失败时优先检查 DNS、80 端口、防火墙和同名站点配置。