Uniapp + PWA 问题排查 03，踩坑实录：Uniapp 打包 PWA 遇到的 5 个坑及解决办法

最新推荐文章于 2026-02-08 22:11:06 发布

原创最新推荐文章于 2026-02-08 22:11:06 发布 · 735 阅读

14 ·

CC 4.0 BY-SA版权

文章标签：

#uni-app #前端 #架构

前端同时被 2 个专栏收录

197 篇文章

订阅专栏

Uniapp + PWA

25 篇文章

订阅专栏

PWA（Progressive Web App，渐进式 Web 应用）凭借“可安装、离线访问、推送通知”等原生 App 级体验，成为很多 Web 项目的优选方案。而 Uniapp 作为跨端开发利器，支持一键打包 PWA，看似便捷，实则暗藏不少“坑”。

最近在使用 Uniapp 开发项目并打包 PWA 的过程中，我接连遇到了 5 个棘手问题，耗费了不少时间排查解决。今天整理成踩坑实录，希望能帮到正在踩坑或即将入坑的小伙伴，少走弯路！

坑 1：Manifest 配置错误，无法正常安装

问题现象

打包后部署到服务器，打开页面后，浏览器地址栏没有“安装到桌面”的提示，通过 Chrome 开发者工具（Application - Manifest）查看，显示“Manifest is not valid”。

排查过程

首先检查 Uniapp 项目中 manifest.on 的 PWA 配置项，发现 icon 路径使用了相对路径（如“/static/icon.png”）；2. 查看打包后的 dist 文件夹，发现 manifest.on 中 icon 的 src 路径与实际文件路径不匹配；3. 进一步确认，Uniapp 打包 PWA 时，对 manifest 的 icon 路径有严格要求，相对路径容易导致解析失败。

解决办法

统一使用绝对路径配置 icon：如果项目部署在根域名下，可直接写“/static/icon-xxx.png”；如果部署在子路径下（如“https://xxx.com/app/”），则需写完整绝对路径（“https://xxx.com/app/static/icon-xxx.png”）。
确保 icon 规格符合要求：PWA 要求至少提供 192x192 和 512x512 两种尺寸的 icon，且格式为 png。在 Uniapp 的 manifest.on 中按如下格式配置：


"pwa": {
  "manifest": {
    "name": "XXX应用",
    "short_name": "XXX",
    "start_url": "/",
    "display": "standalone",
    "background_color": "#ffffff",
    "theme_color": "#007aff",
    "icons": [
      {
        "src": "https://xxx.com/static/icon-192x192.png",
        "sizes": "192x192",
        "type": "image/png"
      },
      {
        "src": "https://xxx.com/static/icon-512x512.png",
        "sizes": "512x512",
        "type": "image/png"
      }
    ]
  }
}

打包后再次检查 dist 文件夹下的 manifest.on，确认配置项无语法错误（如逗号遗漏、引号不匹配等）。

坑 2：Service Worker 注册失败，无法实现离线访问

问题现象

部署后，Chrome 开发者工具（Application - Service Workers）显示 Service Worker 状态为“waiting”或“error”，无法激活；离线状态下打开页面，提示“无法访问此网站”。

排查过程

检查 Uniapp 打包配置，发现未勾选“启用 Service Worker”选项；2. 勾选后重新打包，仍注册失败，查看控制台报错“ServiceWorker script evaluation failed”；3. 定位到打包生成的 service-worker. 文件，发现其中引用的资源路径错误，导致脚本执行失败。

解决办法

开启 Uniapp 的 Service Worker 配置：打开 HBuilderX，进入项目的“manifest.on” - “PWA”选项，勾选“启用 Service Worker”，并配置“缓存策略”（推荐选择“networkFirst”，优先从网络获取资源，离线时使用缓存）。
修复 service-worker. 的资源路径：如果项目部署在子路径下，需要在 service-worker. 中添加基础路径配置。Uniapp 支持自定义 service-worker.，可在项目根目录创建“service-worker.”文件，然后在 manifest.on 中指定“自定义 Service Worker 路径”，内容示例：


// 基础路径，根据项目部署路径修改
const BASE_URL = '/app/';

self.addEventListener('fetch', function(event) {
  // 忽略跨域请求和非 GET 请求
  if (event.request.method !== 'GET' || event.request.url.indexOf('http') !== 0) {
    return;
  }

  event.respondWith(
    caches.open('app-cache').then(function(cache) {
      return fetch(event.request).then(function(response) {
        // 缓存成功响应
        cache.put(event.request.url.replace(BASE_URL, '/'), response.clone());
        return response;
      }).catch(function() {
        // 离线时从缓存获取
        return cache.match(event.request.url.replace(BASE_URL, '/'));
      });
    })
  );
});

确保 Service Worker 脚本无语法错误：打包后检查 dist 文件夹下的 service-worker.，可通过 Chrome 开发者工具的“Sources”面板调试脚本，定位并修复报错。

坑 3：HTTPS 环境缺失，功能受限

问题现象

在本地开发环境（HTTP）中，PWA 的安装、离线访问等功能均无法使用；部署到非 HTTPS 的服务器后，同样存在这些问题，浏览器控制台提示“PWA requires a secure origin”。

排查过程

查阅 PWA 官方文档得知，PWA 的核心功能（Service Worker、Manifest 安装）仅支持 HTTPS 环境（localhost 除外，用于本地开发调试）。本地开发时使用的是 HTTP 协议，部署的服务器也未配置 HTTPS，导致功能受限。

解决办法

本地开发调试：使用 localhost 访问项目（Uniapp 运行时默认使用 localhost:8080），此时浏览器会允许 PWA 功能正常使用，用于开发调试。
生产环境部署：为服务器配置 HTTPS 证书。可通过阿里云、腾讯云等平台申请免费的 SSL 证书（如 Let’s Encrypt），然后在 Nginx 或 Apache 中配置 HTTPS，示例（Nginx 配置）：


server {
  listen 443 ssl;
  server_name xxx.com;

  ssl_certificate /usr/local/nginx/conf/ssl/xxx.crt;
  ssl_certificate_key /usr/local/nginx/conf/ssl/xxx.key;

  location /app/ {
    root /usr/share/nginx/html;
    index index.html;
    try_files $uri $uri/ /app/index.html; # 解决单页应用路由问题
  }
}

坑 4：路由模式不兼容，刷新页面 404

问题现象

PWA 打包后，使用 history 路由模式，首次访问首页正常，但刷新页面或直接访问二级路由（如“https://xxx.com/app/page1”）时，出现 404 错误。

排查过程

确认 Uniapp 路由配置：在 manifest.on 中设置了“router” - “mode”为“history”；2. 分析原因：history 路由模式下，浏览器直接访问二级路由时，会向服务器发送该路径的请求，而服务器上不存在对应的静态文件，导致 404；3. 对比 hash 路由模式：hash 模式下路由带“#”，刷新时不会向服务器发送新请求，因此不会出现 404，但 URL 不够美观。

解决办法

核心思路：配置服务器，将所有路由请求转发到 index.html（单页应用的入口文件）。以 Nginx 为例，修改配置如下：


location /app/ { # 项目部署的子路径
  root /usr/share/nginx/html;
  index index.html;
  # 关键配置：将所有请求转发到 index.html
  try_files $uri $uri/ /app/index.html;
}

如果部署在 Apache 服务器，可在项目根目录创建“.htaccess”文件，添加如下配置：


RewriteEngine On
RewriteBase /app/
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /app/index.html [L]

注意：如果项目部署在根域名下（无二级路径），则将上述配置中的“/app/”改为“/”即可。

坑 5：缓存策略不当，更新后无法加载最新资源

问题现象

PWA 部署新版本后，用户再次访问时，仍显示旧版本内容，需要手动清除浏览器缓存才能看到更新；部分用户反馈“明明更新了，却一直加载不出新功能”。

排查过程

检查 Service Worker 缓存策略：之前使用了“cacheFirst”（优先从缓存获取资源），导致资源被缓存后，即使服务器上有更新，也不会主动获取新资源；2. 查看缓存版本：打包后的资源文件名未添加哈希值，Service Worker 无法区分新旧资源，导致缓存未失效。

解决办法

优化缓存策略：采用“networkFirst”（优先网络）+“缓存版本控制”的方案。在自定义的 service-worker. 中，为缓存命名添加版本号（如“app-cache-v1”），当项目更新时，修改版本号，触发 Service Worker 重新安装和激活，示例：


const CACHE_NAME = 'app-cache-v2'; // 版本号更新时修改
const BASE_URL = '/app/';

// 安装时缓存核心资源
self.addEventListener('install', function(event) {
  event.waitUntil(
    caches.open(CACHE_NAME).then(function(cache) {
      return cache.addAll([
        BASE_URL,
        BASE_URL + 'index.html',
        BASE_URL + 'static//app.'
      ]);
    })
  );
});

// 激活时删除旧缓存
self.addEventListener('activate', function(event) {
  event.waitUntil(
    caches.keys().then(function(cacheNames) {
      return Promise.all(
        cacheNames.filter(function(name) {
          return name !== CACHE_NAME; // 删除非当前版本的缓存
        }).map(function(name) {
          return caches.delete(name);
        })
      );
    })
  );
});