如何用Service Workers实现Laravel指定页面及PDF的部分离线访问？

针对你的Laravel多页面站点需求，以下是具体的实现方案、问题排查及最佳实践：

一、正确配置Service Worker缓存特定页面与PDF #

1. 注册Service Worker #

在需要离线访问的项目列表页面（Blade模板）底部添加注册代码，确保Service Worker仅在该页面生效：

<script>
if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
        navigator.serviceWorker.register('/service-worker.js')
            .catch(err => console.error('Service Worker注册失败:', err));
    });
}
</script>

注意：service-worker.js文件必须放在Laravel的public目录下，注册路径用根路径/service-worker.js，保证其作用域覆盖目标页面和PDF资源。

2. 编写Service Worker缓存逻辑 #

创建public/service-worker.js，实现针对目标页面和PDF的缓存策略：

const CACHE_NAME = 'project-cache-v1';
// 初始缓存资源：目标页面、页面依赖的静态资源
const INITIAL_CACHES = [
    '/projects',
    '/css/app.css',
    '/js/app.js'
];

// 安装阶段：缓存初始资源
self.addEventListener('install', (event) => {
    event.waitUntil(
        caches.open(CACHE_NAME)
            .then(cache => cache.addAll(INITIAL_CACHES))
            .then(() => self.skipWaiting()) // 立即激活新Worker
    );
});

// 激活阶段：清理旧版本缓存
self.addEventListener('activate', (event) => {
    event.waitUntil(
        caches.keys().then(cacheNames => {
            return Promise.all(
                cacheNames.filter(name => name !== CACHE_NAME)
                    .map(name => caches.delete(name))
            );
        }).then(() => self.clients.claim()) // 接管所有打开的客户端
    );
});

// 缓存动态加载的PDF
self.addEventListener('message', (event) => {
    if (event.data.type === 'CACHE_PDFS') {
        caches.open(CACHE_NAME)
            .then(cache => cache.addAll(event.data.urls));
    }
});

// Fetch事件：拦截目标资源请求
self.addEventListener('fetch', (event) => {
    const url = new URL(event.request.url);
    // 仅处理项目页面和PDF资源
    if (url.pathname === '/projects' || url.pathname.startsWith('/storage/projects/')) {
        event.respondWith(
            caches.match(event.request)
                .then(cachedRes => {
                    // 优先返回缓存，后台联网更新缓存
                    const updateFetch = fetch(event.request)
                        .then(networkRes => {
                            caches.open(CACHE_NAME)
                                .then(cache => cache.put(event.request, networkRes.clone()));
                            return networkRes;
                        });
                    return cachedRes || updateFetch;
                })
        );
    }
    // 其他请求直接走网络，不干预
});

3. 动态缓存PDF资源 #

在项目列表页面的JS中，收集所有PDF的URL并发送给Service Worker缓存：

// 假设页面中PDF链接的类名为project-pdf
const pdfUrls = Array.from(document.querySelectorAll('.project-pdf')).map(el => el.href);
navigator.serviceWorker.ready.then(reg => {
    reg.active.postMessage({ type: 'CACHE_PDFS', urls: pdfUrls });
});

确保Laravel的PDF存储路径配置正确（通过Storage::url()生成可访问的公共URL）。

二、Service Worker无法离线提供页面的常见原因排查 #

1. HTTPS环境缺失：Service Worker仅支持HTTPS（localhost除外），检查共享主机是否已启用HTTPS，未启用的话无法正常工作。
2. 缓存路径不匹配：fetch请求的URL必须与缓存的URL完全一致，比如带查询参数的/projects?page=1和不带参数的/projects是两个不同的缓存键，需根据需求调整缓存逻辑（如忽略查询参数或包含参数）。
3. Service Worker未激活：打开浏览器开发者工具的Application标签，查看Service Worker状态是否为Activated，若安装失败，检查控制台错误（如初始缓存资源加载失败）。
4. 快捷方式URL问题：手动创建快捷方式时，确保URL精确匹配缓存的/projects，建议添加极简的Web App Manifest（无需完整PWA）来规范快捷方式的启动行为：
   在页面头部添加：

   <link rel="manifest" href="/manifest.json">
   

   创建public/manifest.json：

   {
       "start_url": "/projects",
       "display": "standalone"
   }
   

三、部分离线+定期同步的最佳实践 #

1. 用Workbox简化缓存逻辑：Workbox可自动处理缓存策略、版本管理和更新，减少手动代码出错概率。可通过npm安装Workbox，配置后生成Service Worker：

   const { injectManifest } = require('workbox-build');
   injectManifest({
       swSrc: 'src/sw-base.js',
       swDest: 'public/service-worker.js',
       globDirectory: 'public',
       globPatterns: [
           'projects',
           'storage/projects/**/*.pdf',
           'css/app.css',
           'js/app.js'
       ],
       maximumFileSizeToCacheInBytes: 50 * 1024 * 1024 // 支持大体积PDF缓存
   });
   

   采用StaleWhileRevalidate策略，优先返回缓存，后台同步更新。

2. 定期检查更新：在页面中添加定时更新逻辑，确保联网时自动同步最新资源：

   navigator.serviceWorker.ready.then(reg => {
       // 每日检查一次更新
       setInterval(() => {
           reg.update().then(updated => {
               if (updated) window.location.reload();
           });
       }, 86400000);
   });
   

3. 精细化缓存管理：

   • 仅缓存必要资源，避免全站缓存增加体积和更新成本；
   • 通过修改CACHE_NAME的版本号（如project-cache-v2）触发缓存更新；
   • 对PDF资源设置合理的缓存过期时间，或在后端更新PDF时主动通知前端刷新缓存。

内容的提问来源于stack exchange，提问作者Tasneem HamedAlneel