Next.js启用App Router后PWA无法安装的问题咨询

在Next.js初始化时选择启用App Router后，PWA无法触发安装（无安装图标），用Lighthouse检测提示page has no manifest link url nextjs；但选择不启用App Router（使用Pages Router）时，PWA可正常安装。

提供的Pages Router下的_document.js代码：

import Document, { Html, Head, Main, NextScript } from 'next/document';

class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head>
          {/* Include your manifest.json file */}
          <link rel="manifest" href="/manifest.webmanifest" />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

提供的manifest.json文件代码：

{
    "theme_color": "#f69435",
    "background_color": "#f69435",
    "display": "standalone",
    "scope": "/",
    "start_url": "/",
    "name": "PWA Test ",
    "short_name": "PWA Test ",
    "description": "cool PWA",
    "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"
        }
    ]
}

Next.js的App Router和Pages Router采用完全不同的页面渲染机制：

• Pages Router中，_document.js是自定义全局HTML文档的入口，你在这里添加的manifest链接会被全局加载；
• 但App Router彻底弃用了_document.js，它的全局HTML配置功能由app/layout.js（根布局）接管。你之前只在_document.js里配置了manifest链接，App Router环境下不会读取这个文件，导致浏览器找不到manifest资源，进而无法触发PWA安装。

1. 把manifest链接迁移到App Router根布局 #

在app/layout.js（或app/layout.tsx）中添加manifest的link标签，示例代码如下：

import './globals.css';

export const metadata = {
  title: 'PWA Test',
  description: 'cool PWA',
};

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <link rel="manifest" href="/manifest.webmanifest" />
        {/* 可选：补充PWA所需的苹果触摸图标、主题色元标签 */}
        <link rel="apple-touch-icon" href="/icon-192x192.png" />
        <meta name="theme-color" content="#f69435" />
      </head>
      <body>{children}</body>
    </html>
  );
}

2. 确认manifest文件位置 #

确保manifest.json（或你命名的manifest.webmanifest）放在项目根目录的public文件夹下，这样Next.js会将其作为静态资源暴露，/manifest.webmanifest的访问路径才会生效。

3. 适配Service Worker配置（如有使用） #

如果你的PWA依赖Service Worker，比如用了next-pwa插件，需要在next.config.js中确保配置适配App Router，示例如下：

const withPWA = require('next-pwa')({
  dest: 'public',
  register: true,
  skipWaiting: true,
});

module.exports = withPWA({
  // 你的其他Next.js配置项
});

内容的提问来源于stack exchange，提问作者behnam 4s