配置文件结构

这一课你将能做到

1. 说出 main → events / http → server → location 的层级，并指出指令大致写在哪一层
2. 对照 deploy/nginx/prod.conf.example，标出 upstream、80 跳转、443 主站、admin 静态各自属于什么块
3. 用「最长前缀 / 修饰符」解释为何 /api/ 会压过 /，并写一条 location = /nginx-health

为什么要学

Nginx 不是「一堆平铺 key=value」。块的嵌套决定继承与作用域；location 匹配顺序决定流量进 Spring 还是 Next。
读不懂结构时，人会把指令贴错层（例如在 location 里写只能放 http 的东西），或改错 server 导致只影响了一个域名。
本课把树状结构与匹配规则讲透，后面静态、反代、SSL 都是在这棵树上挂叶子。

先建立图像

main（全局：user、worker_processes 等）
├── events { worker_connections … }
└── http {
        # 共享：mime、gzip、upstream、log 格式…
        upstream coderoadmap_backend  { server 127.0.0.1:8080; … }
        upstream coderoadmap_platform { server 127.0.0.1:3000; … }

        server { listen 80;  … }           # 跳转到 HTTPS
        server { listen 443; server_name www…; location … }
        server { listen 443; server_name admin…; root … }
    }

人话：http 是整栋商业楼的物业规章；每个 server 是一间按域名区分的铺面；location 是铺面里「哪条走廊通向哪扇门」。

层级	典型内容
main	进程用户、worker 数
events	连接数等事件模型参数
http	上游、压缩、日志、多个 server
server	listen、server_name、SSL、该站 location
location	root / proxy_pass / 精确健康检查

跟着做

步骤 1：读官方「配置文件」概念

打开 Directory structure / Configuring nginx 中配置相关段落，记下：配置由指令组成，许多指令放在上下文（块）里。
用中文写：「指令必须出现在允许的上下文，否则 -t 报错。」

步骤 2：在笔记复述 prod 骨架

打开 deploy/nginx/prod.conf.example，按出现顺序编号：

1. 两个 upstream（在 http 级，与 server 平级）
2. listen 80 → 301 到 www HTTPS
3. listen 443 + server_name coderoadmap.cn → 301 到 www
4. www 主站：/api/ + /
5. admin：root + /api/ + try_files

应看到：同一份文件可含多个 server，靠 server_name / listen 区分。

步骤 3：手写最小可读示例（带中文注释）

在练习机建临时文件（或本地笔记）：

events {
    # 每个 worker 允许的最大连接数（示意）
    worker_connections 1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    # 命名上游：后面 location 用名字引用，便于改 IP
    upstream coderoadmap_backend {
        server 127.0.0.1:8080;
    }

    server {
        listen 80;
        server_name localhost;

        # 前缀匹配：以 /api/ 开头的请求
        location /api/ {
            # 末尾带 / ：去掉 /api/ 前缀再转发（细节见反代课）
            proxy_pass http://coderoadmap_backend/;
        }

        location / {
            return 200 "platform placeholder\n";
        }
    }
}

跑 nginx -t（路径按你放置位置调整）。应 syntax is ok。

步骤 4：location 匹配优先级（简表 + 实验思维）

修饰符	含义	示例
=	精确匹配	location = /nginx-health
^~	优先前缀，若命中则通常不再走正则	静态前缀加速
~ / ~*	正则 / 忽略大小写	`.(js
无修饰	普通前缀，最长者优先	/api/ 长于 /

CodeRoadMap：/api/ 比 / 更长，REST 进 Java；其余进 Next。
练习：在笔记写一条精确健康检查：

location = /nginx-health {
    access_log off;
    default_type text/plain;
    return 200 "ok\n";
}

步骤 5：理解 include 与拆分

生产建议：

• 全局 nginx.conf 少动
• conf.d/coderoadmap-upstreams.conf、coderoadmap-www.conf 等按职责拆
• SSL 证书路径变更时，尽量不动反代 location

与 Spring application.yml 分层类似：全局默认 + 环境/站点覆盖。

步骤 6：对照「改错层」的后果

在笔记列三例：

1. 把 proxy_pass 写在 http 外层且无 server → 非法或无意义
2. 只在 admin 的 server 加安全头 → www 不受影响
3. upstream 写在某个 server 里 → 通常应提升到 http

应看到：先问「这条指令属于哪一层」，再粘贴。

讲清楚要点

1. 因为配置是树状上下文，所以指令必须放在允许的块内——否则 -t 失败。
2. 因为一个 http 可含多个 server，所以靠 listen + server_name 选站——www 与 admin 互不影响。
3. 因为普通前缀按最长匹配，所以 /api/ 能压过 /——这是双栈分流的根基。
4. 因为 upstream 在 http 级命名，所以多个 server 可共用同一后端池——admin 与 www 都可打 /api/。
5. 因为 include 拼接最终配置，所以拆文件不等于拆逻辑树——加载后仍是同一棵 http 树。
6. 因为精确 = 匹配最优先，所以健康检查适合用 location =——避免被宽前缀吃掉。
7. 因为 proxy_pass 是否带尾斜杠会改写 URI，所以结构课要先知道「有这回事」，细节在反代课钉死——先结构，后语义。

你可能会懵的地方

• upstream 为什么不写在 server 里？
  上游是可复用的后端池，属于 http 上下文。多个 server（www、admin）共享同一 coderoadmap_backend。

• 正则 location 会不会打乱 /api/？
  可能。若你加了抢夺性的 location ~，可能改变选择结果。本站主路径用清晰前缀；加正则前先查官方 location 选择规则。

• server_name 写错会怎样？
  请求可能落入「默认 server」（同 listen 下第一个或标了 default_server 的）。表现为打开了错误站点或奇怪证书。联调时先确认 Host。

• events 块可以省略吗？
  发行版默认 nginx.conf 通常已有。教学最小示例可保留一行 worker_connections；不要在站点片段里重复写 events。

错法对照

错法	问题	正解
只写一个 location / 反代到 Next	/api 也被 Next 吃掉，Java 404	单独 location /api/ 且优先
把 SSL 指令贴进 location	上下文错误	SSL 在 server
复制片段却未 include	配置不生效	放入 conf.d 或显式 include
用正则覆盖所有路径「图省事」	匹配难推理、易误伤	主路径用前缀；正则局部用
改 admin 的 root 以为能修主站	改错 server	先认 server_name

自测三问

1. upstream、server、location 三者谁嵌在谁里面？
2. 为什么 CodeRoadMap 的 /api/ 能压过 /？
3. 写一条精确匹配 /nginx-health 返回 200 纯文本的 location 要点是什么？

小结一句话

配置是树：http 包 server，server 包 location；匹配顺序决定流量进 8080 还是 3000。

官方延伸

• Beginner’s Guide
• ngx_http_core_module — location