SSR代理核心是路径重写、资源路径修正、请求头透传及前后端路径对齐；需正确配置proxy_pass（无尾斜杠）、Host/X-Forwarded头、proxy_cache off，并协同Nginx与框架base路径设置。
理解 SSR 代理的核心问题
SSR（服务端渲染）应用在 Nginx 反向代理时，常见问题不是单纯转发请求，而是路径重写、资源路径修正、Cookie/Host 头透传、以及前端路由与后端服务路径对齐。proxy_pass 本身只是转发，但 SSR 应用（如 Next.js、Nuxt、Vue SSR、Remix）通常依赖正确的 base URL、publicPath、server context 中的原始请求信息，否则静态资源 404、API 调用错位、或服务端生成的 HTML 中链接异常。
基础 proxy_pass 配置（必须项）
以 Nuxt SSR 或 Next.js 生产构建为例，假设 Node.js SSR 服务运行在 http://127.0.0.1:3000，Nginx 暴露在 /：
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection '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;
proxy_set_header X-Forwarded-Proto $scheme;
}
关键点：
-
不要加 trailing slash：写成
proxy_pass http://127.0.0.1:3000;（末尾无/），否则 Nginx 会剥离 location 匹配路径，导致 SSR 路由丢失（例如访问/about，后端收到/） -
必须透传 Host 和协议头：SSR 框架需根据
X-Forwarded-Proto和Host构建绝对 URL（如href、canonical、API 基地址） -
禁用缓存 SSR 动态响应：在 location 内加
proxy_cache off;，避免 HTML 被缓存导致首屏内容不更新
处理子路径部署（如部署在 /app/ 下）
若 SSR 应用需部署在非根路径（如 https://example.com/app/），需三处协同：
-
Nginx 重写路径：用
rewrite剥离前缀，再转发给后端 -
SSR 框架配置 base/publicPath：告知框架所有资源和路由相对
/app/ -
后端识别原始路径：通过
X-Original-URI或自定义 header 传递原始路径
示例配置：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
location ^~ /app/ {
rewrite ^/app/(.*)$ /$1 break;
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Original-URI $request_uri; # 供后端读取原始路径
proxy_cache off;
}
同时，在 Nuxt 中设 router.base = '/app/'，Next.js 中设 basePath: '/app'，并确保 assetPrefix 或 build.publicPath 匹配。
静态资源与 API 分离（推荐架构）
生产中建议将 SSR HTML 渲染与静态资源/API 分开代理，提升性能和可维护性：
-
/→ SSR 服务（动态 HTML） -
/_nuxt/或/static/→ 直接由 Nginx serve（无需 Node） -
/api/→ 代理到后端 API 服务（避免浏览器跨域）
示例：
# SSR 页面
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header ...
proxy_cache off;
}
<h1>静态资源（Nuxt/Next 打包输出目录）</h1><p>location ^~ /_next/ {
alias /var/www/myapp/.next/static/;
expires 1y;
add_header Cache-Control "public, immutable";
}</p><h1>API 代理（前端 fetch('/api/users') → 后端）</h1><p>location ^~ /api/ {
proxy_pass <a href="https://www.php.cn/link/c099034308f2a231c24281de338726c1">https://www.php.cn/link/c099034308f2a231c24281de338726c1</a>;
proxy_set_header Host $host;
}</p>注意：alias 末尾不加斜杠，且路径需真实存在；proxy_pass 到 API 时末尾加 / 表示路径替换（/api/users → /users）。
