Docsify项目PWA离线模式实现指南

Docsify项目PWA离线模式实现指南

docsify 🃏 A magical documentation site generator. 项目地址: https://gitcode.com/gh_mirrors/do/docsify

什么是PWA离线模式

PWA(Progressive Web App)是一种结合了Web和原生应用优势的技术方案。在Docsify项目中实现PWA离线模式，可以让你的文档网站在网络不稳定或完全离线的情况下仍然能够访问，显著提升用户体验。

实现原理

PWA离线模式的核心是Service Worker技术，它本质上是一个运行在浏览器后台的脚本，能够拦截和处理网络请求，包括缓存管理等功能。

具体实现步骤

1. 创建Service Worker文件

在项目根目录下创建sw.js文件，内容如下：

const RUNTIME = 'docsify';
// 允许缓存的域名白名单
const HOSTNAME_WHITELIST = [
  self.location.hostname,
  'fonts.gstatic.com',
  'fonts.googleapis.com',
  'cdn.jsdelivr.net',
];

// 处理请求URL
const getFixedUrl = req => {
  const now = Date.now();
  const url = new URL(req.url);
  
  // 1. 修正协议为当前页面协议
  url.protocol = self.location.protocol;

  // 2. 添加缓存破坏查询参数
  if (url.hostname === self.location.hostname) {
    url.search += (url.search ? '&' : '?') + 'cache-bust=' + now;
  }
  return url.href;
};

// Service Worker激活事件
self.addEventListener('activate', event => {
  event.waitUntil(self.clients.claim());
});

// 拦截和处理网络请求
self.addEventListener('fetch', event => {
  if (HOSTNAME_WHITELIST.indexOf(new URL(event.request.url).hostname) > -1) {
    const cached = caches.match(event.request);
    const fixedUrl = getFixedUrl(event.request);
    const fetched = fetch(fixedUrl, { cache: 'no-store' });
    const fetchedCopy = fetched.then(resp => resp.clone());

    event.respondWith(
      Promise.race([fetched.catch(_ => cached), cached])
        .then(resp => resp || fetched)
        .catch(_ => {})
    );

    event.waitUntil(
      Promise.all([fetchedCopy, caches.open(RUNTIME)])
        .then(([response, cache]) =>
          response.ok && cache.put(event.request, response)
        )
        .catch(_ => {})
    );
  }
});

2. 注册Service Worker

在index.html中添加以下代码来注册Service Worker：

<script>
  // 检查浏览器是否支持Service Worker
  if ('serviceWorker' in navigator) {
    // 注册Service Worker
    navigator.serviceWorker.register('sw.js')
      .then(registration => {
        console.log('ServiceWorker注册成功:', registration.scope);
      })
      .catch(error => {
        console.log('ServiceWorker注册失败:', error);
      });
  }
</script>

高级配置选项

自定义缓存策略

可以根据需要修改缓存策略，常见的策略有：

1. Cache First：优先使用缓存
2. Network First：优先使用网络
3. Stale-While-Revalidate：同时请求网络和缓存，快速返回缓存内容，然后更新缓存

缓存更新机制

可以通过以下方式确保用户获取最新内容：

1. 在文件名中添加hash值
2. 使用查询参数破坏缓存
3. 在Service Worker更新时清理旧缓存

测试与调试

测试方法

1. 使用Chrome开发者工具的Application面板
2. 模拟离线状态进行测试
3. 检查缓存存储情况

常见问题解决

1. Service Worker不更新：关闭所有标签页后重新打开
2. 缓存不生效：检查白名单配置是否正确
3. 跨域资源问题：确保资源支持CORS

最佳实践建议

1. 合理设置缓存白名单，避免缓存过大
2. 对静态资源使用长期缓存
3. 对API请求使用Network First策略
4. 提供友好的离线提示界面

通过以上步骤，你的Docsify文档网站就具备了PWA离线能力，用户即使在网络状况不佳或完全离线的情况下，也能顺畅访问之前浏览过的内容。

docsify 🃏 A magical documentation site generator. 项目地址: https://gitcode.com/gh_mirrors/do/docsify