Menu

How to build a Progressive Web Application (PWA) with Next.js

渐进式 Web 应用（PWAs）结合了 Web 应用的覆盖面和可访问性，以及原生移动应用的功能和用户体验。使用 Next.js，你可以创建提供无缝、类应用体验的 PWAs，无需多个代码库或应用商店审批。

PWAs 允许你：

  • 即时部署更新，无需等待应用商店审批
  • 使用单一代码库创建跨平台应用
  • 提供类原生功能，如主屏幕安装和推送通知

使用 Next.js 创建 PWA

1. 创建 Web 应用清单

Next.js 通过 App Router 提供了创建 web 应用清单 的内置支持。你可以创建静态或动态清单文件：

例如，创建 app/manifest.ts 或 app/manifest.json 文件：

app/manifest.ts
TypeScript
import type { MetadataRoute } from 'next'
 
export default function manifest(): MetadataRoute.Manifest {
  return {
    name: 'Next.js PWA',
    short_name: 'NextPWA',
    description: 'A Progressive Web App built with Next.js',
    start_url: '/',
    display: 'standalone',
    background_color: '#ffffff',
    theme_color: '#000000',
    icons: [
      {
        src: '/icon-192x192.png',
        sizes: '192x192',
        type: 'image/png',
      },
      {
        src: '/icon-512x512.png',
        sizes: '512x512',
        type: 'image/png',
      },
    ],
  }
}

此文件应包含关于名称、图标以及如何在用户设备上显示为图标的信息。这将允许用户在其主屏幕上安装你的 PWA，提供类原生应用的体验。

你可以使用类似 favicon 生成器 的工具创建不同的图标集，并将生成的文件放在你的 public/ 文件夹中。

2. 实现 Web 推送通知

Web 推送通知在所有现代浏览器中都受支持，包括：

  • iOS 16.4+ 对于安装到主屏幕的应用
  • macOS 13 或更高版本上的 Safari 16
  • 基于 Chromium 的浏览器
  • Firefox

这使得 PWAs 成为原生应用的可行替代品。值得注意的是，你可以触发安装提示，而无需离线支持。

Web 推送通知允许你重新吸引用户，即使他们没有主动使用你的应用。以下是在 Next.js 应用中实现它们的方法：

首先，让我们在 app/page.tsx 中创建主页面组件。我们将其分解为较小的部分以便更好地理解。首先，我们将添加一些需要的导入和工具函数。暂时不用担心引用的 Server Actions 尚不存在：

'use client'
 
import { useState, useEffect } from 'react'
import { subscribeUser, unsubscribeUser, sendNotification } from './actions'
 
function urlBase64ToUint8Array(base64String: string) {
  const padding = '='.repeat((4 - (base64String.length % 4)) % 4)
  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/')
 
  const rawData = window.atob(base64)
  const outputArray = new Uint8Array(rawData.length)
 
  for (let i = 0; i < rawData.length; ++i) {
    outputArray[i] = rawData.charCodeAt(i)
  }
  return outputArray
}
'use client'
 
import { useState, useEffect } from 'react'
import { subscribeUser, unsubscribeUser, sendNotification } from './actions'
 
function urlBase64ToUint8Array(base64String) {
  const padding = '='.repeat((4 - (base64String.length % 4)) % 4)
  const base64 = (base64String + padding)
    .replace(/\\-/g, '+')
    .replace(/_/g, '/')
 
  const rawData = window.atob(base64)
  const outputArray = new Uint8Array(rawData.length)
 
  for (let i = 0; i < rawData.length; ++i) {
    outputArray[i] = rawData.charCodeAt(i)
  }
  return outputArray
}

现在让我们添加一个组件来管理订阅、取消订阅和发送推送通知。

function PushNotificationManager() {
  const [isSupported, setIsSupported] = useState(false)
  const [subscription, setSubscription] = useState<PushSubscription | null>(
    null
  )
  const [message, setMessage] = useState('')
 
  useEffect(() => {
    if ('serviceWorker' in navigator && 'PushManager' in window) {
      setIsSupported(true)
      registerServiceWorker()
    }
  }, [])
 
  async function registerServiceWorker() {
    const registration = await navigator.serviceWorker.register('/sw.js', {
      scope: '/',
      updateViaCache: 'none',
    })
    const sub = await registration.pushManager.getSubscription()
    setSubscription(sub)
  }
 
  async function subscribeToPush() {
    const registration = await navigator.serviceWorker.ready
    const sub = await registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(
        process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!
      ),
    })
    setSubscription(sub)
    const serializedSub = JSON.parse(JSON.stringify(sub))
    await subscribeUser(serializedSub)
  }
 
  async function unsubscribeFromPush() {
    await subscription?.unsubscribe()
    setSubscription(null)
    await unsubscribeUser()
  }
 
  async function sendTestNotification() {
    if (subscription) {
      await sendNotification(message)
      setMessage('')
    }
  }
 
  if (!isSupported) {
    return <p>此浏览器不支持推送通知。</p>
  }
 
  return (
    <div>
      <h3>推送通知</h3>
      {subscription ? (
        <>
          <p>你已订阅推送通知。</p>
          <button onClick={unsubscribeFromPush}>取消订阅</button>
          <input
            type="text"
            placeholder="输入通知消息"
            value={message}
            onChange={(e) => setMessage(e.target.value)}
          />
          <button onClick={sendTestNotification}>发送测试</button>
        </>
      ) : (
        <>
          <p>你尚未订阅推送通知。</p>
          <button onClick={subscribeToPush}>订阅</button>
        </>
      )}
    </div>
  )
}
function PushNotificationManager() {
  const [isSupported, setIsSupported] = useState(false);
  const [subscription, setSubscription] = useState(null);
  const [message, setMessage] = useState('');
 
  useEffect(() => {
    if ('serviceWorker' in navigator && 'PushManager' in window) {
      setIsSupported(true);
      registerServiceWorker();
    }
  }, []);
 
  async function registerServiceWorker() {
    const registration = await navigator.serviceWorker.register('/sw.js', {
      scope: '/',
      updateViaCache: 'none',
    });
    const sub = await registration.pushManager.getSubscription();
    setSubscription(sub);
  }
 
  async function subscribeToPush() {
    const registration = await navigator.serviceWorker.ready;
    const sub = await registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(
        process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!
      ),
    });
    setSubscription(sub);
    await subscribeUser(sub);
  }
 
  async function unsubscribeFromPush() {
    await subscription?.unsubscribe();
    setSubscription(null);
    await unsubscribeUser();
  }
 
  async function sendTestNotification() {
    if (subscription) {
      await sendNotification(message);
      setMessage('');
    }
  }
 
  if (!isSupported) {
    return <p>此浏览器不支持推送通知。</p>;
  }
 
  return (
    <div>
      <h3>推送通知</h3>
      {subscription ? (
        <>
          <p>你已订阅推送通知。</p>
          <button onClick={unsubscribeFromPush}>取消订阅</button>
          <input
            type="text"
            placeholder="输入通知消息"
            value={message}
            onChange={(e) => setMessage(e.target.value)}
          />
          <button onClick={sendTestNotification}>发送测试</button>
        </>
      ) : (
        <>
          <p>你尚未订阅推送通知。</p>
          <button onClick={subscribeToPush}>订阅</button>
        </>
      )}
    </div>
  );
}

最后，让我们创建一个组件，向 iOS 设备显示安装到主屏幕的指示信息，并且仅在应用尚未安装时显示。

function InstallPrompt() {
  const [isIOS, setIsIOS] = useState(false)
  const [isStandalone, setIsStandalone] = useState(false)
 
  useEffect(() => {
    setIsIOS(
      /iPad|iPhone|iPod/.test(navigator.userAgent) && !(window as any).MSStream
    )
 
    setIsStandalone(window.matchMedia('(display-mode: standalone)').matches)
  }, [])
 
  if (isStandalone) {
    return null // 如果已安装，不显示安装按钮
  }
 
  return (
    <div>
      <h3>安装应用</h3>
      <button>添加到主屏幕</button>
      {isIOS && (
        <p>
          要在你的 iOS 设备上安装此应用，点击分享按钮
          <span role="img" aria-label="share icon">
            {' '}
            ⎋{' '}
          </span>
          然后"添加到主屏幕"
          <span role="img" aria-label="plus icon">
            {' '}
            ➕{' '}
          </span>。
        </p>
      )}
    </div>
  )
}
 
export default function Page() {
  return (
    <div>
      <PushNotificationManager />
      <InstallPrompt />
    </div>
  )
}
function InstallPrompt() {
  const [isIOS, setIsIOS] = useState(false);
  const [isStandalone, setIsStandalone] = useState(false);
 
  useEffect(() => {
    setIsIOS(
      /iPad|iPhone|iPod/.test(navigator.userAgent) && !(window as any).MSStream
    );
 
    setIsStandalone(window.matchMedia('(display-mode: standalone)').matches);
  }, []);
 
  if (isStandalone) {
    return null; // 如果已安装，不显示安装按钮
  }
 
  return (
    <div>
      <h3>安装应用</h3>
      <button>添加到主屏幕</button>
      {isIOS && (
        <p>
          要在你的 iOS 设备上安装此应用，点击分享按钮
          <span role="img" aria-label="share icon">
            {' '}
            ⎋{' '}
          </span>
          然后"添加到主屏幕"
          <span role="img" aria-label="plus icon">
            {' '}
            ➕{' '}
          </span>
          。
        </p>
      )}
    </div>
  );
}
 
export default function Page() {
  return (
    <div>
      <PushNotificationManager />
      <InstallPrompt />
    </div>
  );
}

现在，让我们创建此文件调用的 Server Actions。

3. 实现 Server Actions

在 app/actions.ts 创建一个新文件来包含你的动作。此文件将处理创建订阅、删除订阅和发送通知。

app/actions.ts
TypeScript
'use server'
 
import webpush from 'web-push'
 
webpush.setVapidDetails(
  '<mailto:[email protected]>',
  process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
  process.env.VAPID_PRIVATE_KEY!
)
 
let subscription: PushSubscription | null = null
 
export async function subscribeUser(sub: PushSubscription) {
  subscription = sub
  // 在生产环境中，你会希望将订阅存储在数据库中
  // 例如：await db.subscriptions.create({ data: sub })
  return { success: true }
}
 
export async function unsubscribeUser() {
  subscription = null
  // 在生产环境中，你会希望从数据库中删除订阅
  // 例如：await db.subscriptions.delete({ where: { ... } })
  return { success: true }
}
 
export async function sendNotification(message: string) {
  if (!subscription) {
    throw new Error('没有可用的订阅')
  }
 
  try {
    await webpush.sendNotification(
      subscription,
      JSON.stringify({
        title: '测试通知',
        body: message,
        icon: '/icon.png',
      })
    )
    return { success: true }
  } catch (error) {
    console.error('发送推送通知时出错：', error)
    return { success: false, error: '发送通知失败' }
  }
}

发送通知将由我们在步骤 5 中创建的 service worker 处理。

在生产环境中，你会希望将订阅存储在数据库中，以便在服务器重启后保持持久性，并管理多个用户的订阅。

4. 生成 VAPID 密钥

要使用 Web Push API，你需要生成 VAPID 密钥。最简单的方式是直接使用 web-push CLI：

首先，全局安装 web-push：

Terminal
npm install -g web-push

通过运行以下命令生成 VAPID 密钥：

Terminal
web-push generate-vapid-keys

复制输出并将密钥粘贴到你的 .env 文件中：

NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_public_key_here
VAPID_PRIVATE_KEY=your_private_key_here

5. 创建 Service Worker

为你的 service worker 创建一个 public/sw.js 文件：

public/sw.js
self.addEventListener('push', function (event) {
  if (event.data) {
    const data = event.data.json()
    const options = {
      body: data.body,
      icon: data.icon || '/icon.png',
      badge: '/badge.png',
      vibrate: [100, 50, 100],
      data: {
        dateOfArrival: Date.now(),
        primaryKey: '2',
      },
    }
    event.waitUntil(self.registration.showNotification(data.title, options))
  }
})
 
self.addEventListener('notificationclick', function (event) {
  console.log('收到通知点击。')
  event.notification.close()
  event.waitUntil(clients.openWindow('<https://your-website.com>'))
})

这个 service worker 支持自定义图像和通知。它处理传入的推送事件和通知点击。

  • 你可以使用 icon 和 badge 属性为通知设置自定义图标。
  • 可以调整 vibrate 模式来创建支持设备上的自定义振动提醒。
  • 可以使用 data 属性将额外数据附加到通知。

记得彻底测试你的 service worker，以确保它在不同设备和浏览器上按预期工作。另外，确保将 notificationclick 事件监听器中的 'https://your-website.com' 链接更新为你应用的适当 URL。

6. 添加到主屏幕

在步骤 2 中定义的 InstallPrompt 组件为 iOS 设备显示一条消息，指导它们将应用安装到主屏幕。

要确保你的应用可以安装到移动主屏幕，你必须具备：

  1. 有效的 web 应用清单（在步骤 1 中创建）
  2. 通过 HTTPS 提供的网站

当满足这些条件时，现代浏览器将自动向用户显示安装提示。你可以使用 beforeinstallprompt 提供自定义安装按钮，但我们不推荐这样做，因为它不是跨浏览器和平台的（在 Safari iOS 上不起作用）。

7. 本地测试

为确保你可以在本地查看通知，请确保：

  • 你正在使用 HTTPS 本地运行
    • 使用 next dev --experimental-https 进行测试
  • 你的浏览器（Chrome、Safari、Firefox）已启用通知
    • 在本地提示时，接受使用通知的权限
    • 确保通知未在整个浏览器全局禁用
    • 如果你仍然看不到通知，尝试使用另一个浏览器进行调试

8. 保护你的应用

安全是任何 web 应用的关键方面，特别是对于 PWAs。Next.js 允许你使用 next.config.js 文件配置安全头部。例如：

next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'X-Content-Type-Options',
            value: 'nosniff',
          },
          {
            key: 'X-Frame-Options',
            value: 'DENY',
          },
          {
            key: 'Referrer-Policy',
            value: 'strict-origin-when-cross-origin',
          },
        ],
      },
      {
        source: '/sw.js',
        headers: [
          {
            key: 'Content-Type',
            value: 'application/javascript; charset=utf-8',
          },
          {
            key: 'Cache-Control',
            value: 'no-cache, no-store, must-revalidate',
          },
          {
            key: 'Content-Security-Policy',
            value: "default-src 'self'; script-src 'self'",
          },
        ],
      },
    ]
  },
}

让我们回顾这些选项：

  1. 全局头部（应用于所有路由）：
    1. X-Content-Type-Options: nosniff：防止 MIME 类型嗅探，减少恶意文件上传的风险。
    2. X-Frame-Options: DENY：通过防止你的网站被嵌入 iframes 来保护免受点击劫持攻击。
    3. Referrer-Policy: strict-origin-when-cross-origin：控制请求中包含多少引用信息，平衡安全性和功能性。
  2. Service Worker 特定头部：
    1. Content-Type: application/javascript; charset=utf-8：确保 service worker 被正确解释为 JavaScript。
    2. Cache-Control: no-cache, no-store, must-revalidate：防止缓存 service worker，确保用户始终获得最新版本。
    3. Content-Security-Policy: default-src 'self'; script-src 'self'：为 service worker 实现严格的内容安全策略，只允许来自同一源的脚本。

了解更多关于使用 Next.js 定义 内容安全策略 的信息。

下一步

  1. 探索 PWA 能力：PWAs 可以利用各种 web API 提供高级功能。考虑探索后台同步、周期性后台同步或文件系统访问 API 等功能来增强你的应用。要获取灵感和 PWA 能力的最新信息，你可以参考 What PWA Can Do Today 等资源。
  2. 静态导出：如果你的应用不需要运行服务器，而是使用文件的静态导出，你可以更新 Next.js 配置来启用此更改。在 Next.js 静态导出文档 中了解更多。然而，你需要从 Server Actions 转移到调用外部 API，以及将定义的头部移动到你的代理。
  3. 离线支持：要提供离线功能，一个选择是在 Next.js 中使用 Serwist。你可以在他们的文档中找到如何将 Serwist 与 Next.js 整合的示例。注意： 此插件目前需要 webpack 配置。
  4. 安全考虑：确保你的 service worker 得到适当保护。这包括使用 HTTPS、验证推送消息的来源，以及实现适当的错误处理。
  5. 用户体验：考虑实现渐进增强技术，以确保即使用户的浏览器不支持某些 PWA 功能，你的应用也能正常工作。

下一步

manifest.json

manifest.json 文件的 API 参考。