Next.js 13：PWA本地正常但部署至Azure App Service后失效求助

我在Next.js 13项目中集成PWA功能，本地运行完全正常，但部署到Microsoft Azure App Service后无法正常工作。以下是相关配置文件：

Manifest.js 文件 #

{    
    "theme_color": "#6083ff",    
    "background_color": "#6083ff",    
    "display": "standalone",    
    "scope": "/",    
    "start_url": "/",    
    "name": "App_name",    
    "short_name": "App_name",    
    "description": "Experience Live Anywhere",    
    "icons": [        
        {            
            "src": "/icon-192x192.png",            
            "sizes": "192x192",            
            "type": "image/png"        
        },        
        {            
            "src": "/icon-256x256.png",            
            "sizes": "256x256",            
            "type": "image/png"        
        },        
        {            
            "src": "/icon-384x384.png",            
            "sizes": "384x384",            
            "type": "image/png"        
        },        
        {            
            "src": "/icon-512x512.png",            
            "sizes": "512x512",            
            "type": "image/png"        
        },        
        {            
            "src": "/maskable_icon.png",            
            "sizes": "794x200",            
            "type": "image/png",            
            "purpose": "any maskable"          
        }    
    ],    
    "screenshots": [        
        {          
            "src": "/screenshot.png",          
            "sizes": "192x48",          
            "type": "image/png",          
            "form_factor": "wide",          
            "label": "Coventi"        
        },        
        {          
            "src": "/screenshot-mobile.png",          
            "sizes": "794x200",          
            "type": "image/png",          
            "form_factor": "narrow",          
            "label": "Coventi"        
      }      
    ]
}

next.config.js 文件 #

const withPWA = require("next-pwa");
const runtimeCaching = require("next-pwa/cache");

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  experimental: { esmExternals: true, scrollRestoration: true },
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "placehold.co",
      },
      {
        protocol: "https",
        hostname: "coventiassets.blob.core.windows.net",
      },
    ],
    ...withPWA({
      dest: "public",
      register: true,
      skipWaiting: true,
      runtimeCaching,
      // buildExcludes: [/middleware-manifest.json$/],
      // disable: process.env.NODE_ENV === "development",
    }),
  },
};

module.exports = nextConfig;

_document 文件中的manifest链接 #

<link
  rel="manifest"
  crossOrigin="use-credentials"
  href="manifest.json"
/>

我安装的next-pwa版本为^5.6.0，已经尝试过以下操作但问题仍未解决：

• 修改manifest链接地址为%PUBLIC_URL%/manifest.json
• 将next-pwa版本降级至5.5.0（带/不带package.json中的"^"符号）
• 重新生成manifest文件

解决建议 #

1. 修正next.config.js的配置结构
   当前把withPWA配置嵌套在images字段内是错误的，正确的做法是将withPWA作为外层包裹整个配置：

   const withPWA = require("next-pwa");
   const runtimeCaching = require("next-pwa/cache");
   
   /** @type {import('next').NextConfig} */
   const baseConfig = {
     reactStrictMode: true,
     experimental: { esmExternals: true, scrollRestoration: true },
     images: {
       remotePatterns: [
         {
           protocol: "https",
           hostname: "placehold.co",
         },
         {
           protocol: "https",
           hostname: "coventiassets.blob.core.windows.net",
         },
       ],
     },
   };
   
   module.exports = withPWA({
     ...baseConfig,
     dest: "public",
     register: true,
     skipWaiting: true,
     runtimeCaching,
     // buildExcludes: [/middleware-manifest.json$/],
     // disable: process.env.NODE_ENV === "development",
   });
   

2. 调整manifest链接配置
   如果站点域名与静态资源域名一致，无需crossOrigin="use-credentials"，简化为：

   <link rel="manifest" href="/manifest.json" />
   

3. 检查Azure部署的构建产物

   • 确认Azure上部署的public目录包含manifest.json及所有图标文件
   • 检查Azure App Service的应用设置，确保静态文件服务正常启用，必要时添加.json的MIME类型映射

4. 排查浏览器端错误
   部署后打开浏览器开发者工具的Application面板：

   • 查看Manifest标签，确认manifest是否加载成功、有无格式错误
   • 查看Service Workers标签，检查是否有注册失败的报错信息，根据具体提示进一步处理

内容的提问来源于stack exchange，提问作者Solomon Sunday