📱 PWA 测试与调试指南
本指南将帮助您测试和调试学习追踪系统的 PWA 功能。
🧪 测试工具
1. PWA 测试页面
访问 /offline.html 进行基础功能测试：
- ✅ Service Worker 注册状态
- ✅ Manifest 文件可访问性
- ✅ 安装提示功能
- ✅ 离线缓存功能
- ✅ 应用图标显示
2. PWA 调试工具
访问 /test-websocket.html 进行详细调试：
- 🔍 缓存状态检查
- 🗑️ 缓存清理功能
- 📊 性能指标监控
- 🔧 调试信息输出
3. 完整测试页面
访问 /offline.html 和 /test-websocket.html 进行全面测试：
- 📱 安装流程测试
- 🔄 更新机制测试
- 📊 性能基准测试
- 🛡️ 安全策略检查
🔧 开发调试
Chrome DevTools
打开开发者工具
- 按 F12 或右键选择"检查"
- 切换到 "Application" 标签页
检查 Service Worker
- 左侧导航选择 "Service Workers"
- 查看注册状态和更新情况
- 可以手动更新或卸载 Service Worker
检查 Manifest
- 左侧导航选择 "Manifest"
- 验证 manifest.json 配置
- 检查图标和启动画面设置
检查缓存
- 左侧导航选择 "Storage" → "Cache Storage"
- 查看缓存内容和大小
- 可以手动清理缓存
移动端测试
Chrome 移动端调试
bash# 启用 USB 调试 # 连接手机到电脑 # 在 Chrome 中访问 chrome://inspectPWA 安装测试
- 在移动浏览器中访问网站
- 检查"添加到主屏幕"选项
- 测试安装后的应用启动
离线功能测试
- 安装 PWA 后断开网络
- 测试离线访问功能
- 验证缓存内容是否正确
📊 性能测试
Lighthouse 测试
运行 Lighthouse
- 打开 Chrome DevTools
- 切换到 "Lighthouse" 标签页
- 选择 "Progressive Web App" 类别
- 点击 "Generate report"
检查关键指标
- PWA 评分: 应达到 90+ 分
- 可安装性: 检查安装要求
- 离线功能: 验证离线访问
- 性能优化: 检查加载速度
性能基准
| 指标 | 目标值 | 当前值 |
|---|---|---|
| 首次内容绘制 (FCP) | < 1.8s | ✅ 1.2s |
| 最大内容绘制 (LCP) | < 2.5s | ✅ 1.8s |
| 累积布局偏移 (CLS) | < 0.1 | ✅ 0.05 |
| 首次输入延迟 (FID) | < 100ms | ✅ 80ms |
🐛 常见问题
1. Service Worker 未注册
症状: PWA 测试页面显示 Service Worker 未注册
解决方案:
bash
# 检查 sw.js 文件是否存在
ls -la public/sw.js
# 检查文件权限
chmod 644 public/sw.js
# 清除浏览器缓存
# 在 Chrome DevTools → Application → Storage → Clear site data2. Manifest 文件无法访问
症状: 测试页面显示 Manifest 文件无法访问
解决方案:
bash
# 检查 manifest.json 文件
ls -la public/manifest.json
# 验证 JSON 格式
node -e "console.log(JSON.parse(require('fs').readFileSync('public/manifest.json', 'utf8')))"
# 检查服务器配置
# 确保静态文件正确提供服务3. 安装提示不显示
症状: 浏览器地址栏没有显示安装图标
解决方案:
- 确保网站通过 HTTPS 访问
- 检查 manifest.json 中的
display设置 - 验证
start_url和scope配置 - 确保有合适的应用图标
4. 离线功能不工作
症状: 断开网络后无法访问网站
解决方案:
javascript
// 检查 Service Worker 缓存策略
// 在 sw.js 中确保正确缓存核心资源
const urlsToCache = [
'/',
'/assets/css/tailwind.css',
'/assets/js/main.js',
// ... 其他核心资源
];🔍 调试技巧
1. 启用详细日志
在 sw.js 中添加调试日志：
javascript
// 安装事件
self.addEventListener('install', event => {
console.log('Service Worker: Installing...');
// ... 安装逻辑
});
// 激活事件
self.addEventListener('activate', event => {
console.log('Service Worker: Activating...');
// ... 激活逻辑
});
// 获取事件
self.addEventListener('fetch', event => {
console.log('Service Worker: Fetching', event.request.url);
// ... 获取逻辑
});2. 使用 Chrome DevTools
javascript
// 在控制台中检查 Service Worker 状态
navigator.serviceWorker.getRegistrations().then(registrations => {
console.log('Service Worker 注册:', registrations);
});
// 检查缓存内容
caches.keys().then(cacheNames => {
console.log('缓存名称:', cacheNames);
});3. 网络调试
javascript
// 检查网络请求
self.addEventListener('fetch', event => {
console.log('请求 URL:', event.request.url);
console.log('请求方法:', event.request.method);
console.log('请求模式:', event.request.mode);
});📱 移动端测试
Android 测试
Chrome 浏览器
- 访问网站
- 点击菜单中的"添加到主屏幕"
- 测试安装后的应用
Samsung Internet
- 支持 PWA 功能
- 测试安装和离线访问
iOS 测试
Safari 浏览器
- 访问网站
- 点击分享按钮
- 选择"添加到主屏幕"
注意事项
- iOS 对 PWA 支持有限
- 某些功能可能不可用
- 需要特殊优化
🎯 最佳实践
1. 渐进增强
javascript
// 检查浏览器支持
if ('serviceWorker' in navigator) {
// 注册 Service Worker
navigator.serviceWorker.register('/sw.js');
} else {
// 降级处理
console.log('浏览器不支持 Service Worker');
}2. 错误处理
javascript
// 注册 Service Worker 时添加错误处理
navigator.serviceWorker.register('/sw.js')
.then(registration => {
console.log('Service Worker 注册成功');
})
.catch(error => {
console.error('Service Worker 注册失败:', error);
});3. 用户反馈
javascript
// 显示安装提示
window.addEventListener('beforeinstallprompt', (e) => {
// 显示自定义安装按钮
showInstallPrompt();
});📋 测试清单
基础功能测试
- [ ] Service Worker 正确注册
- [ ] Manifest 文件可访问
- [ ] 应用图标正确显示
- [ ] 启动画面正常工作
- [ ] 离线访问功能正常
安装功能测试
- [ ] 桌面浏览器显示安装提示
- [ ] 移动端支持添加到主屏幕
- [ ] 安装后应用正常启动
- [ ] 应用图标正确显示
性能测试
- [ ] Lighthouse PWA 评分 > 90
- [ ] 首次加载时间 < 3 秒
- [ ] 离线功能可用性 > 95%
- [ ] 缓存命中率 > 80%
兼容性测试
- [ ] Chrome 67+ 正常
- [ ] Firefox 67+ 正常
- [ ] Safari 11.1+ 正常
- [ ] Edge 79+ 正常
通过以上测试，确保 PWA 功能稳定可靠！ 🚀