Nginx 如何使用 include 配置按模块功能切分主配置文件结构

Nginx模块化配置需按作用域规则将同类指令集中到专用文件并在对应上下文精准include：upstream和log_format放http{}开头，ssl和安全头等按需引入server内，路径用绝对路径或规范相对路径，修改后必须nginx -t验证。

用 include 按模块功能切分 Nginx 主配置，核心是把同类指令集中到独立文件，再在对应上下文里引入——不是随便拆，而是按 Nginx 的作用域规则，让每类配置只出现在它合法的位置。

按功能类型建专用配置文件

把跨站点复用的配置抽出来，统一管理，避免重复和不一致：

1. upstream.conf：只放 upstream 块，必须放在 http{} 最顶层（server 块外），路径如 /etc/nginx/upstreams/api.conf
2. log_formats.conf：定义 log_format，同样在 http{} 内提前加载，后续所有 server 都可直接引用名称
3. ssl.conf：含证书路径、TLS 版本、加密套件等，专供 HTTPS 站点复用，不写在单个 server 里
4. security-headers.conf：存放 add_header 类安全头，可被多个 server 或 location 引入

在主配置中按上下文精准 include

include 的位置决定能加载什么内容，不能乱放：

1. 在 http{} 块开头（server{} 之前）引入 upstream 和 log_format 文件
2. 在 http{} 块中间引入通用设置，如 gzip、map、limit_req_zone
3. 在某个 server{} 块内引入 security-headers.conf 或 rewrites.conf，只影响该站点
4. 绝对不要在 events{} 或全局块里引入 server 或 http 块——语法直接报错

目录结构与路径写法要稳

路径不是相对当前文件，而是以 Nginx 配置根目录（通常是 /etc/nginx/）为基准：

1. 推荐用绝对路径：include /etc/nginx/upstreams/*.conf;
2. 若用相对路径，省略 ./，直接写 include snippets/ssl-params.conf;
3. 含空格或特殊字符的文件名必须加引号：include "my app.conf";
4. 通配符不递归，conf.d/**/*.conf 无效；多级目录需显式写明，如 include conf.d/v2/*.conf;

验证与避坑要点

模块化后更易出错，每次修改都要验证：

1. 改完任一被 include 的文件，都必须运行 nginx -t —— 它会检查所有嵌套文件的语法
2. 避免同名重复定义：比如两个文件都写了 log_format main，Nginx 启动失败
3. 通配符按字母序加载，01-api.conf 会比 99-admin.conf 先读入，影响 server_name 匹配优先级
4. 被 include 的文件里不能混入非法指令，例如在 server{} 文件里写 upstream，就会报 “directive is not allowed here”