nginx仅支持以#开头的单行注释，必须独占一行或紧贴指令前，不可置于指令行末尾；注释应说明设计意图、参数依据及优化原因，并按配置层级分层标注上下文。

Nginx 配置文件只支持单行注释，用 # 开头，不支持多行注释语法（如 /* */ 或 //）。但通过合理组织和风格统一的单行注释，完全可以做到清晰、可维护、具备完整技术上下文的备注效果。

注释的基本规则与写法

Nginx 的注释必须紧贴指令前或单独成行，且必须以 # 开头、后跟至少一个空格，再写说明文字。注释不能出现在指令行末尾（即不能写成 worker_processes 2; # 这是错的），否则会被视为语法错误。

• ✅ 正确写法：
  # 启动 4 个 worker 进程，匹配 4 核 CPU
worker_processes 4;
• ❌ 错误写法：
  worker_processes 4; # 启动 4 个进程（Nginx 会报 invalid number of arguments 或解析失败）
• 注释内容建议用中文，避免中英文混排不齐；关键参数值、单位、依据（如“依据 ulimit -n 设置”）可一并注明

按配置层级分层添加技术备注

在不同作用域块前插入带上下文的注释，能显著提升可读性。例如：

PHP的配置文件php.ini的中文注释版

PHP的配置文件php.ini的中文注释版

下载

• 在 http 块上方说明整体用途：
  # 【HTTP 全局配置】启用 Gzip、自定义日志、MIME 类型映射、静态资源缓存策略
• 在 server 块前标注业务含义：
  # 【生产环境主站】监听 443 端口，强制 HTTPS，支持 HTTP/2，绑定域名 api.example.com
• 在 location ~ \.js$ 前注明优化意图：
  # 【JS 资源强缓存】设置 1 年过期，配合版本化文件名使用，避免 CDN 回源

用注释说明“为什么”而不仅是“是什么”

好的技术备注要解释设计决策，方便后续维护者快速理解。比如：

• # keepalive_timeout 65; # 设为 65 而非 75：与主流浏览器默认 keep-alive 超时（75s）错开 10s，减少 TIME_WAIT 占用
• # gzip_comp_level 6; # 权衡压缩率与 CPU 开销：级别 6 是压缩比/耗时比最优拐点，实测 CPU 上升
• # server_tokens off; # 关闭响应头中的 Nginx 版本号，降低指纹暴露风险，满足等保 2.0 安全基线要求

配合 include 机制做模块化注释管理

对于大型配置，推荐将注释与功能解耦：把说明性文字集中写在独立的 .conf 文件头部，再用 include 引入实际配置。例如：

• 新建 /etc/nginx/conf.d/README-security.conf：
  # 【安全加固项汇总】
# - 防止目录遍历：location 中禁用 .. 路径解析
# - 限制请求体大小：防止 DoS 攻击
# - 关闭未使用 HTTP 方法：仅允许 GET/HEAD/POST
• 再在主配置中写：
  include /etc/nginx/conf.d/README-security.conf;
include /etc/nginx/conf.d/security.conf;