2026-01-11-【架构】PWA初体验

PWA 配置说明

本文档说明项目的 PWA（渐进式 Web 应用）配置和使用方法。

已配置的 PWA 功能

1. site.webmanifest 文件

• 文件位置: /public/site.webmanifest
• 功能: 定义 Web 应用的元数据、图标和显示模式
• 配置内容:
  • 应用名称和描述
  • 启动 URL 和显示模式
  • 主题颜色和背景色
  • 图标配置（支持多种尺寸）

2. 图标文件

已生成以下图标文件：

• favicon-192x192.svg - PWA 小图标（192x192）
• favicon-512x512.svg - PWA 大图标（512x512）
• apple-touch-icon.svg - iOS 设备图标（180x180）
• favicon.ico - 传统浏览器图标

3. HTML 配置

在index.html中添加了：

• manifest 文件引用
• 主题颜色 meta 标签
• iOS Web App 配置
• Apple Touch Icon 引用

PWA 功能特性

应用安装

• 用户可以将应用安装到设备主屏幕
• 支持离线访问（需配置 Service Worker）
• 全屏模式运行，类似原生应用

移动端优化

• 适配移动设备显示
• 支持横竖屏切换
• 优化的触摸交互体验

SEO 增强

• 提升搜索引擎排名
• 改善移动端搜索体验
• 增强社交媒体分享效果

使用说明

生成图标

# 生成所有PWA图标
npm run icons:generate

# 如果安装了ImageMagick，会生成PNG格式图标
# 如果未安装，会生成SVG占位图标

构建 PWA 版本

# 包含图标生成的完整SEO+PWA构建
npm run build:pwa

# 仅构建（包含manifest配置）
npm run build

验证配置

1. 打开 Chrome DevTools → Application → Manifest
2. 检查 manifest 是否正确加载
3. 验证图标显示是否正常
4. 测试”Add to Home Screen”功能

配置详解

site.webmanifest 字段说明

字段	说明	示例值
name	应用完整名称	“web”
short_name	应用短名称	“web 应用简称”
description	应用描述	“专业的 XXX 管理平台”
start_url	启动 URL	“/“
display	显示模式	“standalone”（全屏）
theme_color	主题颜色	“#1890ff”（腾讯蓝）
background_color	背景颜色	“#ffffff”（白色）
icons	图标配置	多种尺寸的图标数组

{
  "name": "web应用名称",
  "short_name": "web应用简称",
  "description": "web应用名称提供专业的XXX解决方案，支持XXXX等功能",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#1890ff",
  "orientation": "portrait-primary",
  "scope": "/",
  "lang": "zh-CN",
  "categories": ["business", "finance", "productivity"],
  "icons": [
    {
      "src": "/favicon-192x192.svg",
      "sizes": "192x192",
      "type": "image/svg+xml",
      "purpose": "any maskable"
    },
    {
      "src": "/favicon-512x512.svg",
      "sizes": "512x512",
      "type": "image/svg+xml",
      "purpose": "any maskable"
    },
    {
      "src": "/apple-touch-icon.svg",
      "sizes": "180x180",
      "type": "image/svg+xml",
      "purpose": "any"
    }
  ]
}

显示模式选项

• fullscreen: 全屏显示，隐藏浏览器 UI
• standalone: 类似原生应用，显示状态栏
• minimal-ui: 最小化浏览器 UI
• browser: 普通浏览器模式

图标要求

推荐尺寸

• 192x192: Android 设备主屏幕图标
• 512x512: 应用安装提示和大型设备
• 180x180: iOS 设备主屏幕图标

格式建议

• 生产环境: PNG 格式（支持透明度）
• 开发环境: SVG 格式（占位使用）
• 兼容性: ICO 格式（传统浏览器）

进阶配置

Service Worker（待实现）

// 未来可添加离线缓存功能
if ("serviceWorker" in navigator) {
  navigator.serviceWorker.register("/sw.js");
}

推送通知（待实现）

// 未来可添加推送通知功能
Notification.requestPermission().then((permission) => {
  if (permission === "granted") {
    // 显示通知
  }
});

浏览器支持

完全支持

• Chrome 52+
• Firefox 48+
• Edge 79+
• Safari 11.1+

部分支持

• iOS Safari 11.3+
• Samsung Internet 6.2+

注意事项

图标优化

• 当前使用 SVG 占位图标，生产环境应替换为高质量 PNG
• 图标应具有清晰的轮廓和适当的边距
• 避免使用过多细节，确保小尺寸下可识别

HTTPS 要求

• PWA 功能需要 HTTPS 环境
• 本地开发可使用 localhost
• 生产环境必须配置 SSL 证书

缓存策略

• manifest 文件应设置适当的缓存头
• 图标文件可长期缓存
• 版本更新时需更新 manifest 文件

故障排除

常见问题

1. 图标不显示: 检查路径和文件是否存在
2. 安装提示不出现: 验证 manifest 配置是否正确
3. 主题颜色不生效: 确保 meta 标签和 manifest 配置一致

调试工具

• Chrome DevTools → Application → Manifest
• Lighthouse PWA 审计
• Web App Manifest Validator

更新日志

• 2026-01-13: 初始 PWA 配置完成
• 包含基本的 manifest 配置和图标生成
• 支持应用安装和移动端优化

后续计划

• 实现 Service Worker 离线缓存
• 添加推送通知功能
• 优化应用启动性能
• 添加应用更新检测机制