核心目标是在不暴露后端路径、不触发浏览器跳转前提下按需改写并转发请求；rewrite 必须加 break 才使 proxy_pass 生效，proxy_pass 结尾不能带路径，rewrite 后路径须以 / 开头，调试需开启 error_log notice 级别日志。
proxy_pass 和 rewrite 配合使用，核心目标是：**在不暴露后端路径、不触发浏览器跳转的前提下，把客户端请求按需改写后再转发**。关键不是“能不能一起写”，而是“怎么写才让 rewrite 真正生效、proxy_pass 不被跳过”。
rewrite 必须加 break 才能让 proxy_pass 执行
location 块里同时出现 rewrite 和 proxy_pass 时，Nginx 默认行为是：执行 rewrite 后触发内部重定向（相当于一次新请求），导致当前 location 退出，proxy_pass 被完全忽略。
- 加 break：重写 URI 后，停止本 location 内后续指令，直接执行本 location 的 proxy_pass
- 加 last：重写后立即跳出当前 location，重新匹配所有 location —— proxy_pass 不会执行
- 不加 flag 或用 redirect/permanent：强制返回 302/301，浏览器地址栏变化，这不是反向代理，是跳转
proxy_pass 结尾不能带路径（正则 location 下）
当用正则 location（如 location ~ ^/api/v(?<ver>\d+)/</ver>）提取变量时，proxy_pass 必须只写协议+主机，比如 http://127.0.0.1:3000，不能写成 http://127.0.0.1:3000/api。
- 如果 proxy_pass 含路径（如
http://backend/app/），Nginx 会自动裁剪掉 location 匹配部分，再拼接剩余路径 —— 此时 rewrite 的重写结果会被忽略或错乱 - 真正想控制转发路径，就得靠 rewrite 拼出完整目标路径，且 proxy_pass 保持“干净”
rewrite 后的路径必须以 / 开头
这是最容易出 404 的细节。rewrite 的 replacement 如果不以 / 开头（例如写成 $2 或 api/$2），Nginx 会把它当作相对路径，和 proxy_pass 的地址拼接，导致转发路径错误。
- ✅ 正确：
rewrite ^/old/(.*)$ /new/$1 break; - ❌ 错误：
rewrite ^/old/(.*)$ new/$1 break;（变成http://backend/new/xxx→ 实际发的是http://backend/old/new/xxx）
调试时打开 error_log 看实际转发路径
配置看似没问题，但返回 404 或静默失败？开启 notice 级别日志能看清每一步：
- 在 http 或 server 块中加：
error_log /var/log/nginx/debug.log notice; - 请求后查日志，你会看到类似：
"rewrite or internal redirection cycle while processing /xxx"或"proxy to http://127.0.0.1:3000/v2/users" - 这比猜配置更可靠，尤其能发现多斜杠、路径截断、循环匹配等问题
