proxy_store 是按需落盘的镜像模式，非缓存机制：首次请求从源站拉取并保存至本地，后续直接读取文件返回；需同时配置 proxy_store on、root 路径、proxy_store_access 权限、if (!-e $request_filename) 判断及 proxy_pass 回源。
Nginx 的 proxy_store 指令不是缓存机制，而是“按需落盘 + 本地服务”的镜像模式：首次请求时从源站拉取文件并保存到指定路径，后续请求直接由 Nginx 读取本地文件返回，不走 upstream。它轻量、无需额外模块、适合静态资源（如图片、CSS、JS）的简单镜像分发。
核心配置要点
要让 proxy_store 正常工作，必须同时满足以下条件：
-
启用存储：设置
proxy_store on; -
声明根目录：用
root指令指定本地文件系统路径，该路径将作为 URL 路径的映射基点（例如请求/img/logo.png，Nginx 会尝试读取root_path/img/logo.png） -
权限到位：Nginx 工作进程需对
root目录有读写权限，推荐配置proxy_store_access user:rw group:rw all:rw;，再配合chmod -R a+rw /your/root/path -
触发回源逻辑：必须用
if (!-e $request_filename)判断本地文件是否存在，仅当不存在时才执行proxy_pass向源站拉取
典型 location 配置示例
以下适用于只镜像图片类资源（避免对 HTML 或 API 接口误用）：
location ~* \.(gif|jpg|jpeg|png|bmp|webp|ico|svg)$ {
expires 7d;
add_header X-Cached-By "proxy_store";
<pre class="brush:php;toolbar:false;">root /data/mirror;
proxy_store on;
proxy_store_access user:rw group:rw all:rw;
if (!-e $request_filename) {
proxy_pass http://origin.example.com;
proxy_set_header Host $host;
proxy_set_header User-Agent "nginx-mirror";
}
}
说明：
– root /data/mirror 是本地存储根目录，$request_filename 会自动拼接为完整绝对路径（如 /data/mirror/img/bg.jpg）；
– proxy_pass 必须指向源站完整协议+域名（支持端口，如 http://192.168.1.10:8080）；
– 不建议在 location / 下全局启用，易导致动态请求被错误落盘或覆盖。
与 proxy_cache 的关键区别
很多人混淆 proxy_store 和 proxy_cache，它们本质不同：
- proxy_store：文件落地为真实磁盘文件，路径与 URL 严格对应，可被其他程序直接访问或 rsync 同步，无内存元数据管理，不支持 purge、不校验过期，适合长期稳定静态资源
-
proxy_cache：基于 key 哈希存储在私有目录结构中，依赖
keys_zone管理元数据，支持inactive、max_size、purge等精细控制，适合需要 TTL、多级缓存策略的场景
若需清理 proxy_store 内容，直接 rm -rf /data/mirror/* 即可，无需调用任何接口。
常见问题处理
遇到请求失败或始终回源，优先检查：
-
路径权限：确认
root目录属主为 Nginx 运行用户（如www-data或nginx），且有写权限 -
if 语句位置：
if必须在location块内，且不能嵌套在proxy_pass后；Nginx 官方不推荐在 location 中使用 if，但此处是proxy_store唯一可靠方案 -
源站响应头干扰：某些源站返回
Cache-Control: no-store或Content-Disposition可能影响落盘，可加proxy_ignore_headers Cache-Control Expires Set-Cookie;屏蔽 -
目录层级缺失：Nginx 不自动创建多级子目录（如
/a/b/c.jpg），需确保/data/mirror/a/b/存在，或改用proxy_temp_path配合脚本预建目录（不推荐）
