nginx的include指令用于嵌入外部配置文件以提升可维护性，必须置于http、server等配置块内，支持绝对路径与通配符，需注意上下文合法性、路径明确性及重载生效。

Nginx 的 include 指令用于将外部配置文件的内容“嵌入”到当前配置上下文中，常用于拆分大型配置、复用通用设置（如 SSL 参数、缓存规则、访问控制等），提升可维护性。

include 的基本用法和位置限制

include 不是全局指令，它必须出现在能容纳其他指令的配置块内，比如 http、server、location、upstream 等块中。不能直接写在配置文件最外层（即不在任何块内）。

语法很简单：

include /path/to/file.conf;

路径支持通配符，例如：

include /etc/nginx/conf.d/*.conf;

常见使用场景和建议目录结构

典型做法是把不同功能的配置分离出来，例如：

Nginx Config Creator

创建 Nginx/OpenResty 反向代理配置文件并重载服务器。包含安全检查和环境感知功能。主要参数：服务名、域名、端口。

下载

• /etc/nginx/common/ssl.conf：统一的 TLS 设置（ssl_protocols、ssl_ciphers 等）
• /etc/nginx/common/cache.conf：静态资源缓存策略（expires、add_header）
• /etc/nginx/sites-available/example.com：某个站点的 server 块
• /etc/nginx/conf.d/ 目录下放多个 *.conf，由主配置 include conf.d/*.conf; 统一加载

注意事项和易错点

使用 include 时需注意以下几点：

• 路径必须是绝对路径，或相对于 Nginx 启动时工作目录的相对路径（但强烈建议用绝对路径，避免歧义）
• 被包含的文件内容必须语法合法，且符合所在上下文——比如在 location 块里 include 的文件不能出现 server 指令
• 如果通配符匹配不到任何文件，Nginx 不报错也不警告（静默跳过），容易导致配置未生效却难以察觉
• 修改被包含的文件后，必须执行 nginx -t 测试配置，并 nginx -s reload 重载，才能生效

一个实用示例

假设你有如下结构：

/etc/nginx/common/auth.conf

auth_basic "Restricted Area";
auth_basic_user_file /etc/nginx/.htpasswd;

在某个 location 中引用它：

location /admin {
  include /etc/nginx/common/auth.conf;
  proxy_pass http://backend;
}

这样就把认证逻辑抽离出来，多处复用更清晰，也方便统一更新。