React 360 Progressive Web App改造：离线访问与缓存实现

蒋荔卿Lorelei

842人浏览 · 2025-10-26 03:50:39

蒋荔卿Lorelei · 2025-10-26 03:50:39 发布

React 360 Progressive Web App改造：离线访问与缓存实现

【免费下载链接】react-360 项目地址: https://gitcode.com/gh_mirrors/reac/react-360

你还在为React 360应用依赖网络连接而烦恼吗？当用户处于弱网或无网络环境时，精心打造的360体验瞬间变成空白页面？本文将带你通过PWA技术改造React 360应用，实现核心资源离线缓存、智能预加载和网络状态自适应，让你的VR应用在任何网络环境下都能流畅运行。

读完本文你将掌握：

如何为React 360项目添加Service Worker支持
核心资源缓存策略设计与实现
离线状态检测与用户体验优化
生产环境构建与缓存配置

项目现状分析

React 360应用默认采用在线加载模式，所有资源包括JavaScript束、静态资产和媒体文件都需要实时从服务器获取。官方构建流程通过npm run bundle生成生产版本，输出到build目录，包含以下核心文件：

Web Server
├─ static_assets/      # 静态资源目录
├─ index.html          # 应用入口HTML
├─ index.bundle.js     # 主应用束
├─ client.bundle.js    # 客户端运行时
└─ NonBlobBridge.js    # 桥接脚本

这种架构在网络不稳定时会导致加载失败或体验卡顿。通过分析docs/publish.md可知，React 360本身未提供离线支持，但我们可以通过PWA技术栈对其进行增强。

PWA改造方案设计

我们将通过以下三个关键步骤实现React 360应用的PWA化：

添加Service Worker实现资源缓存
配置Web App Manifest实现应用安装
优化资源加载策略实现智能预缓存

缓存策略规划

根据React 360应用的资源特性，我们设计三级缓存策略：

缓存类型	资源类型	更新策略	存储位置
预缓存	核心JS束、HTML、CSS	版本更新时	CacheStorage
运行时缓存	图片、音频、3D模型	LRU淘汰	CacheStorage
持久化存储	用户偏好、会话数据	实时更新	IndexedDB

实现步骤

1. 添加Service Worker

首先创建Service Worker文件sw.js，放置在项目根目录：

// sw.js - Service Worker核心逻辑
const CACHE_NAME = 'react360-pwa-v1';
const PRECACHE_ASSETS = [
  '/',
  '/index.html',
  '/index.bundle.js',
  '/client.bundle.js',
  '/NonBlobBridge.js',
  // 基础静态资源
  '/static_assets/default-pano.jpg',
  '/static_assets/logo.png'
];

// 安装阶段：缓存核心资源
self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => cache.addAll(PRECACHE_ASSETS))
      .then(() => self.skipWaiting())
  );
});

// 激活阶段：清理旧缓存
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())
  );
});

//  fetch事件：实现缓存优先策略
self.addEventListener('fetch', event => {
  // 对于API请求使用网络优先策略
  if (event.request.url.includes('/api/')) {
    event.respondWith(
      fetch(event.request).catch(() => 
        caches.match('/offline-api-fallback.json')
      )
    );
    return;
  }
  
  // 对于静态资源使用缓存优先，后备网络
  event.respondWith(
    caches.match(event.request)
      .then(response => {
        // 缓存命中则返回，同时后台更新缓存
        if (response) {
          fetch(event.request).then(newResponse => 
            caches.open(CACHE_NAME).then(cache => 
              cache.put(event.request, newResponse)
            )
          );
          return response;
        }
        
        // 缓存未命中则从网络获取
        return fetch(event.request).then(response => {
          // 不缓存大于5MB的资源
          if (response.headers.get('Content-Length') > 5 * 1024 * 1024) {
            return response;
          }
          
          // 缓存新获取的资源
          const responseClone = response.clone();
          caches.open(CACHE_NAME).then(cache => 
            cache.put(event.request, responseClone)
          );
          return response;
        }).catch(() => {
          // 网络失败时的后备内容
          if (event.request.mode === 'navigate') {
            return caches.match('/offline.html');
          }
          return caches.match('/static_assets/offline-fallback.jpg');
        });
      })
  );
});

2. 修改入口HTML

编辑Samples/BasicAppTemplate/index.html，添加PWA相关元数据和Service Worker注册代码：

<!DOCTYPE html>
<html>
  <head>
    <title>React 360 PWA</title>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <!-- 添加PWA元数据 -->
    <meta name="theme-color" content="#000000">
    <link rel="manifest" href="/manifest.json">
    <link rel="apple-touch-icon" href="/static_assets/icons/icon-192x192.png">
    <style>body { margin: 0; }</style>
  </head>
  <body>
    <div id="container"></div>
    <script src="./client.bundle?platform=vr"></script>
    <script>
      React360.init(
        'index.bundle?platform=vr&dev=true',
        document.getElementById('container'),
        {
          bridgeFile: 'NonBlobBridge.js',
          assetRoot: 'static_assets/',
        }
      );
      
      // 注册Service Worker
      if ('serviceWorker' in navigator) {
        window.addEventListener('load', () => {
          navigator.serviceWorker.register('/sw.js')
            .then(registration => {
              console.log('SW registered:', registration.scope);
            })
            .catch(err => {
              console.log('SW registration failed:', err);
            });
        });
      }
    </script>
  </body>
</html>

3. 创建Web App Manifest

在项目根目录创建manifest.json文件，使应用可被安装到设备主屏幕：

{
  "name": "React 360 PWA Demo",
  "short_name": "React360",
  "description": "A Progressive Web App for React 360",
  "start_url": "/",
  "display": "fullscreen",
  "orientation": "landscape",
  "background_color": "#000000",
  "theme_color": "#4285f4",
  "icons": [
    {
      "src": "static_assets/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png"
    },
    {
      "src": "static_assets/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "static_assets/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

4. 优化资源加载策略

React 360应用大量使用静态资源，如全景图、纹理和3D模型。根据docs/static-assets.md的最佳实践，我们应该使用asset()方法引用资源，以便在生产环境中正确指向CDN或缓存位置：

// 优化资源引用方式
import { asset } from 'react-360';

// 组件中使用asset()加载资源
<Pano source={asset('equirectangular-pano.jpg')} />
<Image source={asset('product-image.jpg')} />
<Model source={{ obj: asset('model.obj'), mtl: asset('model.mtl') }} />

5. 添加离线状态检测

创建OfflineDetector.js组件，放置在src/components/目录下：

// src/components/OfflineDetector.js
import React, { Component } from 'react';
import { View, Text, VrButton } from 'react-360';

export default class OfflineDetector extends Component {
  state = {
    isOnline: navigator.onLine,
    cachedAssets: []
  };

  componentDidMount() {
    // 监听网络状态变化
    window.addEventListener('online', this.handleOnline);
    window.addEventListener('offline', this.handleOffline);
    
    // 检查缓存内容
    this.checkCacheContents();
  }

  componentWillUnmount() {
    window.removeEventListener('online', this.handleOnline);
    window.removeEventListener('offline', this.handleOffline);
  }

  handleOnline = () => {
    this.setState({ isOnline: true });
    // 网络恢复时同步数据
    this.props.onReconnect && this.props.onReconnect();
  };

  handleOffline = () => {
    this.setState({ isOnline: false });
  };

  checkCacheContents = async () => {
    if ('caches' in window) {
      const cacheNames = await caches.keys();
      const assets = [];
      
      for (const name of cacheNames) {
        const cache = await caches.open(name);
        const keys = await cache.keys();
        assets.push(...keys.map(request => request.url));
      }
      
      this.setState({ cachedAssets: assets });
    }
  };

  render() {
    const { isOnline } = this.state;
    
    if (isOnline) return null;
    
    return (
      <View style={{
        backgroundColor: '#ff4444',
        padding: 0.2,
        borderRadius: 0.1,
        alignItems: 'center'
      }}>
        <Text style={{ fontSize: 0.3 }}>
          离线模式 - 使用缓存内容
        </Text>
        <VrButton onClick={this.checkCacheContents}>
          <Text style={{ fontSize: 0.2 }}>
            查看缓存资源 ({this.state.cachedAssets.length})
          </Text>
        </VrButton>
      </View>
    );
  }
}

构建与部署优化

生产环境构建命令

修改package.json添加PWA构建脚本：

"scripts": {
  "build:pwa": "npm run bundle && cp sw.js manifest.json build/ && cp -r static_assets/icons build/static_assets/"
}

执行构建命令生成PWA版本：

npm run build:pwa

资源预加载配置

编辑client.js，使用React 360的staticResourceURL方法预加载关键资源：

// client.js
import { staticResourceURL } from 'react-360';

// 预加载核心360资源
const preloadResources = async () => {
  const resources = [
    staticResourceURL('static_assets/essential-pano.jpg'),
    staticResourceURL('static_assets/ui-elements.png'),
    staticResourceURL('static_assets/audio/background.mp3')
  ];
  
  // 并行预加载所有资源
  await Promise.all(
    resources.map(url => 
      fetch(url).then(response => {
        if (response.ok) return caches.open('react360-pwa-v1').then(cache => cache.put(url, response));
      })
    )
  );
};

// 应用初始化前预加载
preloadResources().then(() => {
  React360.init(
    // 初始化参数...
  );
});

测试与验证

离线功能测试步骤

使用Chrome浏览器访问应用
打开开发者工具 > Application > Service Workers
勾选"Offline"复选框模拟离线环境
刷新页面验证应用是否正常加载

Lighthouse性能检测

运行Lighthouse审计验证PWA特性：

# 安装Lighthouse CLI
npm install -g lighthouse

# 运行审计
lighthouse http://localhost:8081 --view

目标指标：

渐进式Web应用分数 ≥ 90
首次内容绘制 < 2s
离线可用性: 100%

项目目录结构优化

改造后的项目目录结构如下：

React 360 PWA项目
├── build/                # 构建输出目录
├── src/
│   ├── components/
│   │   └── OfflineDetector.js  # 离线检测组件
│   ├── client.js         # 客户端入口
│   ├── index.js          # 应用入口
│   └── sw.js             # Service Worker
├── static_assets/
│   ├── icons/            # PWA图标集
│   └── ...               # 其他静态资源
├── manifest.json         # Web App Manifest
└── package.json          # 项目配置