# 安装核心库
npm install workbox-sw
 
# 安装构建工具（根据构建系统选择其一）
# Webpack
npm install workbox-webpack-plugin --save-dev
 
# Vite（推荐第三方插件）
npm install vite-plugin-pwa --save-dev
 
# 独立构建工具
npm install workbox-build --save-dev

// webpack.config.js
const { InjectManifest } = require('workbox-webpack-plugin');
 
module.exports = {
  plugins: [
    new InjectManifest({
      swSrc: './src/sw.js',
      swDest: 'service-worker.js',
    }),
  ],
};

// vite.config.js
import { VitePWA } from 'vite-plugin-pwa';
 
export default {
  plugins: [
    VitePWA({
      registerType: 'autoUpdate',
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg}'],
      },
    }),
  ],
};

// src/sw.js - Service Worker 文件
import { precacheAndRoute } from 'workbox-precaching';
import { registerRoute } from 'workbox-routing';
import { StaleWhileRevalidate, CacheFirst } from 'workbox-strategies';
 
// 预缓存构建时生成的静态资源清单
precacheAndRoute(self.__WB_MANIFEST);
 
// 运行时缓存：HTML 页面使用 Network First
registerRoute(
  ({ request }) => request.mode === 'navigate',
  new StaleWhileRevalidate({ cacheName: 'pages' })
);
 
// 运行时缓存：静态资源使用 Cache First
registerRoute(
  ({ request }) => ['style', 'script', 'worker'].includes(request.destination),
  new CacheFirst({ cacheName: 'static-assets' })
);
 
// 运行时缓存：API 请求使用 Network First
registerRoute(
  ({ url }) => url.pathname.startsWith('/api/'),
  new StaleWhileRevalidate({ cacheName: 'api-cache' })
);

<!-- index.html - 注册 Service Worker -->
<script>
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/service-worker.js');
  }
</script>

const { GenerateSW, InjectManifest } = require('workbox-webpack-plugin');
 
// 方式 1：自动生成 Service Worker（适合简单场景）
new GenerateSW({
  clientsClaim: true,
  skipWaiting: true,
  runtimeCaching: [{
    urlPattern: /^https:\/\/api\.example\.com/,
    handler: 'NetworkFirst',
  }],
});
 
// 方式 2：注入到自定义 Service Worker（适合复杂场景）
new InjectManifest({
  swSrc: './src/sw.js',
  swDest: 'service-worker.js',
});

import { VitePWA } from 'vite-plugin-pwa';
 
VitePWA({
  registerType: 'autoUpdate',
  workbox: {
    globPatterns: ['**/*.{js,css,html,ico,png,svg}'],
    runtimeCaching: [{
      urlPattern: /^https:\/\/api\.example\.com\/.*/,
      handler: 'NetworkFirst',
      options: {
        cacheName: 'api-cache',
        expiration: {
          maxEntries: 50,
          maxAgeSeconds: 60 * 60 * 24,
        },
      },
    }],
  },
})

git clone https://github.com/GoogleChrome/workbox.git
cd workbox
npm install
npm run build     # 构建所有包
npm test          # 运行测试
npm run dev       # 开发模式

// webpack.config.js
const { InjectManifest } = require('workbox-webpack-plugin');
 
module.exports = {
  mode: 'production',
  plugins: [
    new InjectManifest({
      swSrc: './src/sw.js',
      swDest: 'service-worker.js',
      maximumFileSizeToCacheInBytes: 5 * 1024 * 1024, // 5MB
      exclude: [/\.map$/, /^manifest.*\.js$/],
    }),
  ],
};

// 使用 workbox-window 管理更新
import { Workbox } from 'workbox-window';
 
const wb = new Workbox('/service-worker.js');
 
wb.addEventListener('waiting', () => {
  if (confirm('有新版本可用，是否刷新？')) {
    wb.messageSkipWaiting();
    wb.addEventListener('controlling', () => {
      window.location.reload();
    });
  }
});
 
wb.register();

name: Build and Deploy PWA
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run build
      - run: npm test
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

import { ExpirationPlugin } from 'workbox-expiration';
 
registerRoute(
  ({ url }) => url.pathname.startsWith('/api/'),
  new StaleWhileRevalidate({
    cacheName: 'api-cache',
    plugins: [
      new ExpirationPlugin({
        maxEntries: 100,
        maxAgeSeconds: 7 * 24 * 60 * 60,
        purgeOnQuotaError: true,
      }),
    ],
  })
);

// sw.js - 推荐的生产配置
import { precacheAndRoute } from 'workbox-precaching';
import { registerRoute } from 'workbox-routing';
import { StaleWhileRevalidate, CacheFirst, NetworkFirst } from 'workbox-strategies';
import { ExpirationPlugin } from 'workbox-expiration';
import { CacheableResponsePlugin } from 'workbox-cacheable-response';
 
// 1. 预缓存静态资源
precacheAndRoute(self.__WB_MANIFEST);
 
// 2. HTML 页面 - StaleWhileRevalidate
registerRoute(
  ({ request }) => request.mode === 'navigate',
  new StaleWhileRevalidate({
    cacheName: 'pages-cache',
    plugins: [new CacheableResponsePlugin({ statuses: [200] })],
  })
);
 
// 3. 静态资源 - Cache First
registerRoute(
  ({ request }) => ['style', 'script', 'worker'].includes(request.destination),
  new CacheFirst({
    cacheName: 'static-cache',
    plugins: [
      new ExpirationPlugin({ maxEntries: 100, maxAgeSeconds: 30 * 24 * 60 * 60 }),
    ],
  })
);
 
// 4. 图片 - Cache First
registerRoute(
  ({ request }) => request.destination === 'image',
  new CacheFirst({
    cacheName: 'image-cache',
    plugins: [
      new ExpirationPlugin({ maxEntries: 50, maxAgeSeconds: 7 * 24 * 60 * 60 }),
    ],
  })
);
 
// 5. API 请求 - StaleWhileRevalidate
registerRoute(
  ({ url }) => url.pathname.startsWith('/api/'),
  new StaleWhileRevalidate({
    cacheName: 'api-cache',
    plugins: [
      new CacheableResponsePlugin({ statuses: [200] }),
      new ExpirationPlugin({ maxEntries: 50 }),
    ],
  })
);
 
// 6. 跳过等待，立即激活
self.addEventListener('message', (event) => {
  if (event.data?.type === 'SKIP_WAITING') {
    self.skipWaiting();
  }
});

// ❌ 错误：不处理 Service Worker 更新
navigator.serviceWorker.register('/sw.js');
 
// ✅ 正确：监听更新并提示用户
const registration = await navigator.serviceWorker.register('/sw.js');
registration.addEventListener('updatefound', () => {
  const newWorker = registration.installing;
  newWorker.addEventListener('statechange', () => {
    if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
      // 提示用户刷新
    }
  });
});
 
// ❌ 错误：缓存无限增长
registerRoute(/.*/, new CacheFirst());
 
// ✅ 正确：设置过期策略
registerRoute(/.*/, new CacheFirst({
  plugins: [new ExpirationPlugin({ maxEntries: 100 })],
}));