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();