Nginx 缓存层配置的模块化管理-Nginx-PHP中文网

模块化管理是让nginx缓存配置清晰、可维护、易复用的关键，通过按功能拆分、include动态加载、location分层匹配、代理与客户端缓存分离、环境变量隔离实现。

nginx 缓存层配置的模块化管理

模块化管理是让 Nginx 缓存配置清晰、可维护、易复用的关键。它不是把所有指令堆在 nginx.conf 里，而是按功能拆分、按场景组织，通过 include 指令动态加载，类似“插件式”结构。

参考 server-configs-nginx 项目的成熟结构：

h5bp/web_performance/cache-control.conf：专注 Cache-Control 响应头的精细化控制，用 map 指令为不同 MIME 类型（如 text/html、application/javascript）分配专属策略
h5bp/web_performance/cache_expiration.conf：定义 expires 指令逻辑，同样基于 $sent_http_content_type 映射过期时间，比如 HTML 设为 epoch（立即过期），静态资源设为 1y
nginx.conf 主文件只保留全局框架和 include 调用，不写具体缓存规则

在 server 块内，用 location 匹配不同后缀或路径，再分别引入对应缓存策略：

律社

律社是一款面向法律从业者的AI法律工作台。

下载

匹配带哈希的 JS/CSS：location ~* \.[a-f0-9]{8,}\.(js|css)$ → 加载长期缓存配置，启用 immutable
匹配通用图片：location ~* \.(png|jpg|webp|svg)$ → 启用 1 年缓存 + public
匹配 HTML 入口：location ~* \.html$ → 单独设置 private, no-cache, must-revalidate，避免 CDN 错缓存

两者目标不同，必须分开配置：

客户端缓存（Browser Caching）：靠 add_header 或 expires 控制浏览器行为，放在 location 或 server 级别
代理缓存（Proxy Caching）：靠 proxy_cache_path、proxy_cache_key、proxy_cache_valid 等指令实现，通常定义在 http 块，并在 location 中启用
避免混用：例如不要在 proxy 缓存配置里写 add_header Cache-Control，除非你明确需要同时影响中间代理和终端浏览器

通过变量和条件判断，让同一套模块适配多环境：

用 map 定义环境变量：map $host $cache_zone { ~dev\. example\.com dev_cache; ~staging\. example\.com staging_cache; default prod_cache; }
在 location 中引用：proxy_cache $cache_zone;，实现开发/预发/生产使用不同缓存区
对敏感路径（如 /admin、/api/user）强制跳过缓存：proxy_cache_bypass 1; 或 proxy_no_cache 1;