如何使用 Webpack 持久化缓存大幅提升构建性能？

// webpack.config.js — 最简配置，一行即可获得巨大性能提升
module.exports = {
    // ...
    cache: {
        type: 'filesystem'   // ← 核心开关
    },
    // ...
};

basehash = Hash(
    config 内容 hash      // 由 buildDependencies.config 决定
  + webpack/lib 内容 hash  // Webpack 核心代码 hash
  + cache.version 字符串   // 用户自定义版本标识
)

// webpack.config.js — 基础生产就绪版
const path = require('path');

module.exports = {
    mode: 'production',

    cache: {
        type: 'filesystem',

        // === 身份配置 ===
        name: 'AppProductionCache',
        version: '1.0.0',              // 配置重大变更时递增此值

        // === 存储路径 ===
        cacheDirectory: path.resolve(__dirname, 'node_modules/.cache/webpack'),

        // === 失效控制（必须！）===
        buildDependencies: {
            config: [__filename],       // ← 关键！配置文件变更时缓存自动失效
        },

        // === 性能调优 ===
        compression: 'gzip',           // 生产环境启用 gzip 压缩缓存文件
        maxAge: 5184000000,            // 缓存有效期 60 天
        maxMemoryGenerations: Infinity, // 生产环境无限期保留内存缓存

        // === 调试 ===
        profile: false,                 // 设为 true 可查看详细缓存日志
    },

    // ... 其他配置
};

// webpack.config.js — 进阶高性能版
const path = require('path');

module.exports = {
    mode: process.env.NODE_ENV || 'development',

    cache: {
        type: 'filesystem',

        // === 多环境隔离 ===
        name: `AppCache-${process.env.NODE_ENV}`,
        version: '2.0.0',

        // === 自定义存储路径 ===
        cacheLocation: path.resolve(__dirname, `.webpack-cache/${process.env.NODE_ENV}`),

        // === 精细失效控制 ===
        buildDependencies: {
            config: [
                __filename,                                    // 主配置
                path.join(__dirname, 'webpack.base.config.js'), // 继承的基础配置
                path.join(__dirname, '.babelrc.json'),         // Babel 配置
                path.join(__dirname, '.eslintrc.js'),          // ESLint 配置
                path.join(__dirname, 'tsconfig.json'),         // TypeScript 配置
            ],
            // 自定义构建依赖（如共享配置包）
            // sharedConfig: [path.join(__dirname, 'packages/shared-config')],
        },

        // === 高级存储策略 ===
        compression: process.env.NODE_ENV === 'production' ? 'brotli' : false,
        // brotli 比 gzip 压缩率更高，但压缩/解压稍慢

        maxAge: 60 * 24 * 60 * 60 * 1000,     // 60 天
        maxMemoryGenerations: process.env.NODE_ENV === 'development' ? 10 : Infinity,
        // 开发环境限制内存代数，避免 OOM；生产环境不限

        // === 写入时机精细控制 ===
        idleTimeout: 10000,                      // 10s 空闲后写盘（开发环境更快反馈）
        idleTimeoutAfterLargeChanges: 500,       // 大变更后 500ms 快速写盘
        idleTimeoutForInitialStore: 2000,        // 首次写入延迟缩短至 2s

        // === 实验性特性 ===
        allowCollectingMemory: true,             // 开发环境允许 GC 回收
        profile: process.env.CACHE_PROFILE === 'true',
    },

    // 实验性特性开关
    experiments: {
        cacheUnaffected: true,                   // 启用未变更模块缓存
    },
};

// 开发环境额外启用 memoryCacheUnaffected
if (process.env.NODE_ENV === 'development') {
    module.exports.cache.memoryCacheUnaffected = true;
}

// webpack.config.ci.js — CI/CD 专用版
const path = require('path');
const isCI = !!process.env.CI;

module.exports = {
    mode: 'production',

    cache: {
        type: 'filesystem',

        // === CI 友好的固定路径 ===
        // 注意：CI 环境必须保证工作目录绝对路径一致！
        cacheDirectory: isCI
            ? '/workspace/node_modules/.cache/webpack'
            : path.resolve(__dirname, 'node_modules/.cache/webpack'),
        name: 'CIBuildCache',
        version: '1.0.0-ci',

        // === CI 失效控制 ===
        buildDependencies: {
            config: [__filename],
        },

        // === CI 优化参数 ===
        compression: 'brotli',               // 最大压缩率，节省 CI 缓存存储
        maxAge: Infinity,                     // CI 环境不过期，由 CI 工具管理清理
        maxMemoryGenerations: 0,              // CI 通常单次运行，不需要内存缓存
        // maxMemoryGenerations: 0 的含义：
        // 数据仅在内存中暂存直到序列化到磁盘，之后再次读取需从磁盘反序列化
        // 这最小化了内存使用，适合资源受限的 CI 环境

        // === CI 写入优化 ===
        idleTimeout: 0,                       // 构建完成后立即写盘，不等空闲
        idleTimeoutAfterLargeChanges: 0,
        idleTimeoutForInitialStore: 0,

        // === CI 只读模式（可选）===
        // readonly: isCI && process.env.CACHE_READONLY === 'true',
        // 当设置为只读时，webpack 只读取缓存但不写入新的缓存条目
        // 适用于：缓存预热阶段、或只希望利用缓存加速但不更新的场景

        profile: isCI,                        // CI 环境始终开启日志便于排查
    },
};

variables:
  # 兜底：当当前分支没有缓存时，使用 main 分支的缓存
  CACHE_FALLBACK_KEY: "main"

stages:
  - build
  - deploy

build-job:
  stage: build
  image: node:20-alpine
  cache:
    key: "$CI_COMMIT_REF_SLUG"        # 以分支名作为缓存键
    paths:
      - node_modules/.cache/webpack/  # ← Webpack 缓存目录
    policy: pull-push                  # 拉取 + 推送缓存
  script:
    - npm ci                            # 注意：npm ci 会清空 node_modules，必须放在「恢复缓存」之前执行
    - npx webpack --config webpack.config.ci.js
  artifacts:
    paths:
      - dist/

name: Build

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      # 注意：必须在 npm ci 之后恢复 Webpack 缓存！
      # npm ci 会清空 node_modules（含 node_modules/.cache），
      # 若先恢复缓存再执行 npm ci，缓存会被整体删除
      - name: Restore Webpack Cache
        uses: actions/cache@v3
        with:
          # Webpack 文件系统缓存路径
          path: node_modules/.cache/webpack/
          # 使用 lockfile hash 作为缓存键的一部分
          key: ${{ runner.os }}-webpack-${{ hashFiles('**/package-lock.json') }}
          # 兜底：未精确匹配时尝试恢复同 OS 的缓存
          restore-keys: |
            ${{ runner.os }}-webpack-

      - name: Build
        run: npx webpack --config webpack.config.ci.js

      - name: Upload Build Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

yarn add -D cache-loader

module.exports = {
    module: {
        rules: [{
            test: /\.js$/,
            use: ['cache-loader', 'babel-loader', 'eslint-loader']
            //     ^^^^^^^^^^^^ 必须放在 loader 数组首位
        }]
    },
};

const redis = require("redis");
const client = redis.createClient();

async function read(key, callback) {
    const result = await client.get(key);
    callback(null, result ? JSON.parse(result) : undefined);
}

async function write(key, data, callback) {
    await client.set(key, JSON.stringify(data));
    callback();
}

module.exports = {
    module: {
        rules: [{
            test: /\.js$/,
            use: [
                { loader: "cache-loader", options: { read, write } },
                "babel-loader",
            ],
        }],
    },
};

yarn add -D hard-source-webpack-plugin

const HardSourceWebpackPlugin = require("hard-source-webpack-plugin");

module.exports = {
    plugins: [new HardSourceWebpackPlugin()],
};

module.exports = {
    module: {
        rules: [{
            test: /\.m?js$/,
            loader: 'babel-loader',
            options: { cacheDirectory: true },
        }]
    },
};

const ESLintPlugin = require('eslint-webpack-plugin');
const StylelintPlugin = require('stylelint-webpack-plugin');

module.exports = {
    plugins: [
        new ESLintPlugin({ cache: true }),
        new StylelintPlugin({ files: '**/*.css', cache: true }),
    ],
};

// 开启详细日志模式
cache: {
    type: 'filesystem',
    profile: true,  // ← 开启后会输出每个缓存操作的耗时
}

// 日志输出示例（开启 profile 后）：
// [webpack.cache] restoring 1423 objects from pack took 45ms
// [webpack.cache] storing 1423 objects to pack took 120ms
// [webpack.cache] cache root: /project/node_modules/.cache/webpack/AppProductionCache
// [webpack.cache] basehash: a1b2c3d4e5f6...

// 🏆 生产环境推荐配置（复制即用）
const path = require('path');

module.exports = ({
    cache: {
        type: 'filesystem',
        buildDependencies: { config: [__filename] },  // 必须！
        compression: 'gzip',                           // 推荐
        maxMemoryGenerations: Infinity,                // 生产环境
    }
});