Nginx gzip静态资源预压缩的实现方案详解

http {
    # 1️⃣ 全局启用 gzip_static（必须！否则 location 内无效）
    gzip_static on;

    # 2️⃣ 显式声明支持的编码格式（关键！否则不匹配 accept-encoding）
    gzip_vary on;           # 发送 vary: accept-encoding，确保 cdn 正确缓存变体
    gzip_http_version 1.1;  # 兼容 http/1.0 客户端（虽已淘汰，但部分 iot 设备仍用）

    # 3️⃣ 精准控制 mime 类型（避免压缩图片/视频等二进制文件）
    gzip_types
        text/plain
        text/css
        text/javascript
        text/xml
        text/vcard
        application/javascript
        application/x-javascript
        application/json
        application/xml
        application/rss+xml
        application/atom+xml
        application/vnd.api+json
        image/svg+xml
        font/woff2
        font/woff
        font/ttf;

    # 4️⃣ 设置最小压缩阈值（防小文件越压越大）
    gzip_min_length 256;

    # 5️⃣ 关键：禁用实时 gzip！防止 fallback 时二次压缩
    gzip off;  # ⚠️ 必须关闭！否则当 .gz 文件缺失时，nginx 会 fallback 到实时压缩，失去预压缩意义

    server {
        listen 80;
        server_name example.com;

        # 6️⃣ 静态资源根目录（务必使用绝对路径）
        root /var/www/static;

        # 7️⃣ 最佳实践：显式声明 index 文件并禁止目录遍历
        location / {
            try_files $uri $uri/ =404;
        }

        # 8️⃣ 专用于静态资源的 location（推荐分离配置）
        location ~ ^/(js|css|fonts|images|assets)/ {
            # 启用预压缩
            gzip_static on;

            # 强制缓存（cdn 和浏览器）
            expires 1y;
            add_header cache-control "public, immutable";

            # 防盗链（可选）
            valid_referers none blocked server_names *.example.com;
            if ($invalid_referer) {
                return 403;
            }
        }

        # 9️⃣ 安全加固：禁止访问敏感文件
        location ~ /\.(htaccess|htpasswd|env|log|ini|bak|swp|git|svn) {
            deny all;
        }
    }
}

package com.example.build;
import org.apache.maven.plugin.abstractmojo;
import org.apache.maven.plugin.mojoexecutionexception;
import org.apache.maven.plugin.mojofailureexception;
import org.apache.maven.plugins.annotations.lifecyclephase;
import org.apache.maven.plugins.annotations.mojo;
import org.apache.maven.plugins.annotations.parameter;
import org.apache.maven.project.mavenproject;
import java.io.*;
import java.nio.file.*;
import java.nio.file.attribute.basicfileattributes;
import java.util.*;
import java.util.concurrent.*;
import java.util.function.predicate;
import java.util.zip.gzipoutputstream;
/**
 * maven plugin to pre-compress static assets to .gz files.
 * supports multi-threading, custom compression level, and timestamp preservation.
 * ⚡ optimized for build-time use (no runtime dependency).
 */
@mojo(name = "precompress", defaultphase = lifecyclephase.package)
public class gzipprecompressmojo extends abstractmojo {
    @parameter(defaultvalue = "${project}", readonly = true, required = true)
    private mavenproject project;
    /**
     * directory containing static files to compress (e.g., target/classes/static)
     */
    @parameter(property = "staticdir", defaultvalue = "${project.build.outputdirectory}/static")
    private string staticdir;
    /**
     * file extensions to compress (comma-separated, e.g., "js,css,json,svg,woff2")
     */
    @parameter(property = "extensions", defaultvalue = "js,css,json,svg,woff2,ttf,woff")
    private string extensions;
    /**
     * gzip compression level (0-9). higher = smaller size, slower. default: 9.
     */
    @parameter(property = "compressionlevel", defaultvalue = "9")
    private int compressionlevel;
    /**
     * number of threads for parallel compression. default: cpu cores.
     */
    @parameter(property = "threads", defaultvalue = "${availableprocessors}")
    private int threads;
    private final list<string> extensionlist = new arraylist<>();
    private final executorservice executor = executors.newfixedthreadpool(threads);
    @override
    public void execute() throws mojoexecutionexception, mojofailureexception {
        if (compressionlevel < 0 || compressionlevel > 9) {
            throw new mojoexecutionexception("compressionlevel must be between 0 and 9");
        }
        // parse extensions
        arrays.stream(extensions.split(","))
                .map(string::trim)
                .filter(ext -> !ext.isempty())
                .foreach(extensionlist::add);
        path dirpath = paths.get(staticdir);
        if (!files.exists(dirpath) || !files.isdirectory(dirpath)) {
            getlog().warn("static directory does not exist: " + staticdir);
            return;
        }
        getlog().info("starting pre-compression in: " + staticdir);
        getlog().info("extensions: " + extensionlist);
        getlog().info("compression level: " + compressionlevel);
        getlog().info("threads: " + threads);
        try {
            files.walk(dirpath)
                    .filter(files::isregularfile)
                    .filter(istargetfile())
                    .map(path::toabsolutepath)
                    .foreach(this::submitcompressiontask);
            // wait for all tasks
            executor.shutdown();
            if (!executor.awaittermination(5, timeunit.minutes)) {
                executor.shutdownnow();
                throw new mojoexecutionexception("compression tasks timed out after 5 minutes");
            }
            getlog().info("✅ pre-compression completed successfully.");
        } catch (ioexception | interruptedexception e) {
            throw new mojoexecutionexception("failed during pre-compression", e);
        }
    }
    private predicate<path> istargetfile() {
        return path -> {
            string name = path.getfilename().tostring();
            for (string ext : extensionlist) {
                if (name.tolowercase().endswith("." + ext.tolowercase())) {
                    return true;
                }
            }
            return false;
        };
    }
    private void submitcompressiontask(path source) {
        executor.submit(() -> {
            try {
                path gzpath = source.resolvesibling(source.getfilename() + ".gz");
                compressfile(source, gzpath);
                // preserve lastmodifiedtime from source to .gz
                files.setlastmodifiedtime(gzpath, files.getlastmodifiedtime(source));
                getlog().debug("compressed: " + source.relativize(gzpath));
            } catch (exception e) {
                getlog().error("failed to compress " + source, e);
            }
        });
    }
    private void compressfile(path source, path target) throws ioexception {
        try (inputstream is = files.newinputstream(source);
             outputstream os = files.newoutputstream(target);
             gzipoutputstream gzos = new gzipoutputstream(os, true)) {
            gzos.setlevel(compressionlevel); // set compression level before writing
            byte[] buffer = new byte[8192];
            int len;
            while ((len = is.read(buffer)) != -1) {
                gzos.write(buffer, 0, len);
            }
            gzos.finish(); // critical: flush and write gzip trailer
        }
    }
}

<plugin>
  <groupid>com.example</groupid>
  <artifactid>static-precompress-maven-plugin</artifactid>
  <version>1.0.0</version>
  <mojo>
    <goal>precompress</goal>
    <implementation>com.example.build.gzipprecompressmojo</implementation>
    <language>java</language>
    <configuration>
      <staticdir>${project.build.outputdirectory}/static</staticdir>
      <extensions>js,css,json,svg,woff2,ttf,woff</extensions>
      <compressionlevel>9</compressionlevel>
      <threads>${availableprocessors}</threads>
    </configuration>
    <requiresdependencyresolution>runtime</requiresdependencyresolution>
  </mojo>
</plugin>

<build>
  <plugins>
    <!-- your existing plugins... -->
    <!-- pre-compress static assets -->
    <plugin>
      <groupid>com.example</groupid>
      <artifactid>static-precompress-maven-plugin</artifactid>
      <version>1.0.0</version>
      <executions>
        <execution>
          <id>precompress-static</id>
          <phase>prepare-package</phase> <!-- runs before package -->
          <goals>
            <goal>precompress</goal>
          </goals>
          <configuration>
            <!-- override defaults if needed -->
            <staticdir>${project.build.outputdirectory}/static</staticdir>
            <compressionlevel>9</compressionlevel>
            <!-- for spring boot: use resources output dir -->
            <!-- <staticdir>${project.build.outputdirectory}/static</staticdir> -->
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

$ ls -la target/classes/static/js/
app.js         # original
app.js.gz      # generated ✅
vendor.js      # original
vendor.js.gz   # generated ✅

// replace gzipoutputstream with zopflioutputstream
try (inputstream is = files.newinputstream(source);
     outputstream os = files.newoutputstream(target)) {
    zopflioutputstream zos = new zopflioutputstream(os, zopflioutputstream.format.gzip);
    // ... copy bytes ...
    zos.close(); // auto-finish
}

private void cleanupstalegzfiles(path staticdir) throws ioexception {
    files.walk(staticdir)
            .filter(files::isregularfile)
            .filter(path -> path.tostring().endswith(".gz"))
            .foreach(path -> {
                path original = path.resolvesibling(
                    path.getfilename().tostring().substring(0,
                        path.getfilename().tostring().length() - 3)
                );
                if (!files.exists(original)) {
                    try {
                        files.delete(path);
                        getlog().debug("removed stale .gz: " + path);
                    } catch (ioexception e) {
                        getlog().warn("failed to delete stale .gz: " + path, e);
                    }
                }
            });
}

// after creating .gz file
posixfilepermissions.setposixfilepermissions(
    gzpath,
    posixfilepermissions.fromstring("rw-r--r--") // 644
);

<!-- in your html template -->
<link rel="preload" href="/js/app.js" rel="external nofollow"  as="script" type="application/javascript" crossorigin>

private void generatecoveragereport(path staticdir) throws ioexception {
    long total = 0, gzcount = 0;
    map<string, double> compressionratios = new hashmap<>();
    try (stream<path> stream = files.walk(staticdir)) {
        list<path> files = stream
                .filter(files::isregularfile)
                .filter(path -> {
                    string name = path.getfilename().tostring().tolowercase();
                    return name.endswith(".js") || name.endswith(".css") || name.endswith(".json");
                })
                .collect(collectors.tolist());
        total = files.size();
        for (path f : files) {
            path gz = f.resolvesibling(f.getfilename() + ".gz");
            if (files.exists(gz)) {
                gzcount++;
                long origsize = files.size(f);
                long gzsize = files.size(gz);
                double ratio = (double) gzsize / origsize;
                compressionratios.put(f.getfilename().tostring(), ratio);
            }
        }
    }
    // write report
    path report = staticdir.resolvesibling("precompress-report.json");
    map<string, object> reportdata = map.of(
        "timestamp", system.currenttimemillis(),
        "total_assets", total,
        "gz_count", gzcount,
        "coverage_percent", total == 0 ? 100.0 : (double) gzcount / total * 100,
        "compression_ratios", compressionratios
    );
    files.writestring(report, new objectmapper().writevalueasstring(reportdata));
    getlog().info("📊 pre-compression report written to: " + report);
}

{
  "timestamp": 1717023456789,
  "total_assets": 127,
  "gz_count": 127,
  "coverage_percent": 100.0,
  "compression_ratios": {
    "app.js": 0.284,
    "styles.css": 0.211,
    "config.json": 0.412
  }
}

log_format precompress '$remote_addr - $remote_user [$time_local] '
                       '"$request" $status $body_bytes_sent '
                       '"$http_referer" "$http_user_agent" '
                       'gzip_status:$gzip_ratio '
                       'gzip_static:$sent_http_content_encoding';

access_log /var/log/nginx/access.log precompress;

# 每分钟统计 fallback 次数（即 gzip_static 为空时）
tail -f /var/log/nginx/access.log | \
  awk '{if($12=="gzip_static:") count++} end {print "fallback count:", count}'

# load ngx_brotli module first
brotli on;
brotli_static on;
gzip_static on;
# let nginx choose best encoding

location /js/ {
    mirror /mirror;
    mirror_request_body off;
    gzip_static on;
    gzip off;
}
location = /mirror {
    internal;
    proxy_pass https://shadow-cluster;
    proxy_set_header x-original-uri $request_uri;
}

# github actions / gitlab ci
- name: validate pre-compression coverage
  run: |
    coverage=$(jq -r '.coverage_percent' target/classes/static/precompress-report.json)
    if (( $(echo "$coverage < 95" | bc -l) )); then
      echo "❌ pre-compression coverage too low: ${coverage}%"
      exit 1
    fi

# 编译安装 ngx_brotli 后
brotli on;
brotli_comp_level 11;     # brotli 支持 0-11，11 为最高
brotli_static on;         # 启用预压缩 .br 文件
brotli_types
    text/plain
    text/css
    text/javascript
    application/javascript
    application/json
    application/xml
    image/svg+xml
    font/woff2;

# 与 gzip 共存（自动协商）
gzip_static on;
gzip off;

<dependency>
  <groupid>org.brotli</groupid>
  <artifactid>dec</artifactid>
  <version>0.1.2</version>
</dependency>

// in compressfile()
brotlioutputstream bos = new brotlioutputstream(os, 
    new parameters().setquality(11).setlargewindow(true));
// ... write bytes ...
bos.close();