upstream必须定义在http块内，不能出现在location或server中；真正实现转发的是proxy_pass指令，需以http://upstream_name格式显式引用，否则报“unknown directive”错误。
Nginx 的 location 块内不能直接写 upstream 名称来“调用”，这是常见误解。Nginx 配置语法中，upstream 是独立的顶层块，只定义后端服务器组；真正把请求转发到 upstream 的指令是 proxy_pass（或其他类似指令如 fastcgi_pass），它必须显式出现在 location 内。
为什么直接写 upstream 名字会启动失败
如果你在 location 里写了类似这样的错误写法：
location /api/ {
my_backend; # ❌ 错误！这不是合法指令
}Nginx 会报错：unknown directive "my_backend"。因为 my_backend 是 upstream 块名，不是 Nginx 内置指令，也不能单独作为语句存在。
正确写法：用 proxy_pass 指向 upstream
必须通过 proxy_pass（或同类指令）引用 upstream 名称，且注意 URL 格式：
- 如果 upstream 名称是
backend_api，应写成：proxy_pass http://backend_api; - 协议前缀 http:// 或 https:// 不可省略，否则 Nginx 会把它当成域名或路径处理，导致 502 或配置加载失败
- 不要加尾部斜杠（除非你明确需要重写路径），例如：
proxy_pass http://backend_api/;和proxy_pass http://backend_api;行为不同
常见连带陷阱与检查点
- upstream 块必须定义在 server 或 http 块外层，不能嵌套在 location 里
- 确保 upstream 名称拼写完全一致（区分大小写），且没有多余空格
- 如果用了变量动态指定 upstream（如
proxy_pass http://$backend;），需确认变量已正确定义并赋值，且该用法要求 Nginx 版本 ≥ 1.3.13 - 检查是否遗漏了
http { ... }外层包裹 —— 所有 upstream 和 server 都必须在 http 块内
一个能跑通的最小示例
以下是一个结构完整、无语法错误的片段：
http {
upstream backend_api {
server 127.0.0.1:8000;
server 127.0.0.1:8001;
}
<pre class='brush:php;toolbar:false;'>server {
listen 80;
location /api/ {
proxy_pass http://backend_api; # ✅ 正确
proxy_set_header Host $host;
}
}}
保存后运行 nginx -t 验证语法，再 reload 即可生效。
