如何使用 Next.js 构建渐进式 Web 应用(PWA)
了解如何使用 Next.js 构建渐进式 Web 应用(PWA)。
渐进式 Web 应用(PWA)兼具 Web 应用的覆盖范围和可访问性,以及原生移动应用的功能和用户体验。借助 Next.js,您可以创建 PWA,在所有平台上提供无缝、类似应用的体验,而无需维护多个代码库或等待应用商店审核。
PWA 使您能够:
- 无需等待应用商店审核即可即时部署更新
- 使用单一代码库创建跨平台应用
- 提供类似原生的功能,例如主屏幕安装和推送通知
使用 Next.js 创建 PWA#
1. 创建 Web App Manifest#
Next.js 提供内置支持,可使用 App Router 创建 web app manifest。您可以创建静态或动态的 manifest 文件:
例如,创建 app/manifest.ts 或 app/manifest.json 文件:
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',
},
],
}
}export default function 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
这使得 PWA 成为原生应用的可行替代方案。值得注意的是,您无需离线支持即可触发安装提示。
即使用户未主动使用您的应用,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(
new URL('../lib/service-worker.js', import.meta.url),
{
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>Push notifications are not supported in this browser.</p>
}
return (
<div>
<h3>Push Notifications</h3>
{subscription ? (
<>
<p>You are subscribed to push notifications.</p>
<button onClick={unsubscribeFromPush}>Unsubscribe</button>
<input
type="text"
placeholder="Enter notification message"
value={message}
onChange={(e) => setMessage(e.target.value)}
/>
<button onClick={sendTestNotification}>Send Test</button>
</>
) : (
<>
<p>You are not subscribed to push notifications.</p>
<button onClick={subscribeToPush}>Subscribe</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(
new URL('../lib/service-worker.js', import.meta.url),
{
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>Push notifications are not supported in this browser.</p>;
}
return (
<div>
<h3>Push Notifications</h3>
{subscription ? (
<>
<p>You are subscribed to push notifications.</p>
<button onClick={unsubscribeFromPush}>Unsubscribe</button>
<input
type="text"
placeholder="Enter notification message"
value={message}
onChange={(e) => setMessage(e.target.value)}
/>
<button onClick={sendTestNotification}>Send Test</button>
</>
) : (
<>
<p>You are not subscribed to push notifications.</p>
<button onClick={subscribeToPush}>Subscribe</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>Install App</h3>
<button>Add to Home Screen</button>
{isIOS && (
<p>
To install this app on your iOS device, tap the share button
<span role="img" aria-label="share icon">
{' '}
⎋{' '}
</span>
and then "Add to Home Screen"
<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>Install App</h3>
<button>Add to Home Screen</button>
{isIOS && (
<p>
To install this app on your iOS device, tap the share button
<span role="img" aria-label="share icon">
{' '}
⎋{' '}
</span>
and then "Add to Home Screen"
<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 创建一个新文件来存放您的 actions。该文件将处理创建订阅、删除订阅和发送通知。
'use server'
import webpush from 'web-push'
webpush.setVapidDetails(
'<mailto:your-email@example.com>',
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('No subscription available')
}
try {
await webpush.sendNotification(
subscription,
JSON.stringify({
title: 'Test Notification',
body: message,
icon: '/icon.png',
})
)
return { success: true }
} catch (error) {
console.error('Error sending push notification:', error)
return { success: false, error: 'Failed to send notification' }
}
}'use server';
import webpush from 'web-push';
webpush.setVapidDetails(
'<mailto:your-email@example.com>',
process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!,
process.env.VAPID_PRIVATE_KEY!
);
let subscription= null;
export async function subscribeUser(sub) {
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) {
if (!subscription) {
throw new Error('No subscription available');
}
try {
await webpush.sendNotification(
subscription,
JSON.stringify({
title: 'Test Notification',
body: message,
icon: '/icon.png',
})
);
return { success: true };
} catch (error) {
console.error('Error sending push notification:', error);
return { success: false, error: 'Failed to send notification' };
}
}发送通知将由我们在步骤 5 中创建的 service worker 处理。
在生产环境中,您可能希望将订阅存储在数据库中,以便在服务器重启后保持数据持久,并管理多个用户的订阅。
4. 生成 VAPID 密钥#
要使用 Web Push API,您需要生成 VAPID 密钥。最简单的方法是直接使用 web-push CLI:
首先,全局安装 web-push:
pnpm add -g web-pushnpm install -g web-pushyarn global add web-pushbun add -g web-push运行以下命令生成 VAPID 密钥:
web-push generate-vapid-keys复制输出并将密钥粘贴到您的 .env 文件中:
NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_public_key_here
VAPID_PRIVATE_KEY=your_private_key_here5. 创建 Service Worker#
为您的 service worker 创建 lib/service-worker.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('Notification click received.')
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 设备显示一条消息,指导他们安装到主屏幕。
要确保您的应用可以安装到移动设备主屏幕,您必须具备:
- 有效的 web app manifest(在步骤 1 中创建)
- 通过 HTTPS 提供网站服务
当满足这些条件时,现代浏览器会自动向用户显示安装提示。您可以使用 beforeinstallprompt 提供自定义安装按钮,但我们不推荐这样做,因为它不跨浏览器和平台兼容(在 Safari iOS 上不起作用)。
7. 本地测试#
要确保您可以在本地查看通知,请确保:
- 您使用 HTTPS 在本地运行
- 使用
next dev --experimental-https进行测试
- 使用
- 您的浏览器(Chrome、Safari、Firefox)已启用通知
- 在本地出现提示时,接受使用通知的权限
- 确保整个浏览器的通知未被全局禁用
- 如果仍然看不到通知,请尝试使用其他浏览器进行调试
8. 保护您的应用#
安全性是任何 Web 应用的关键方面,对 PWA 尤其如此。Next.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'",
},
],
},
]
},
}让我们逐一了解这些选项:
- 全局标头(应用于所有路由):
X-Content-Type-Options: nosniff:防止 MIME 类型嗅探,降低恶意文件上传的风险。X-Frame-Options: DENY:通过防止您的网站被嵌入 iframe 来防御点击劫持攻击。Referrer-Policy: strict-origin-when-cross-origin:控制请求中包含多少 referrer 信息,在安全性和功能性之间取得平衡。
- Service Worker 专用标头:
Content-Type: application/javascript; charset=utf-8:确保 service worker 被正确识别为 JavaScript。Cache-Control: no-cache, no-store, must-revalidate:防止缓存 service worker,确保用户始终获取最新版本。Content-Security-Policy: default-src 'self'; script-src 'self':为 service worker 实施严格的内容安全策略,仅允许来自同源的脚本。
了解更多关于使用 Next.js 定义内容安全策略的信息。
扩展您的 PWA#
- 探索 PWA 能力:PWA 可以利用各种 Web API 提供高级功能。考虑探索后台同步、定期后台同步或 File System Access API 等功能来增强您的应用。如需了解 PWA 能力的灵感和最新信息,您可以参考 What PWA Can Do Today等资源。
- 静态导出: 如果您的应用不需要运行服务器,而是使用静态文件导出,您可以更新 Next.js 配置以启用此更改。在 Next.js 静态导出文档中了解更多信息。不过,您需要从 Server Actions 改为调用外部 API,并将您定义的标头迁移到 proxy。
- 离线支持:Next.js 提供了一个实验性的
useOfflinehook 和配套的experimental.useOffline配置,用于支持网络状态感知的 UI 以及失败导航和 Server Action 请求的自动重试。对于完整的基于 service worker 的离线缓存,一个选择是 Serwist,它为 Turbopack 和 webpack 都提供了 Next.js 集成示例。 - 安全注意事项:确保您的 service worker 得到妥善保护。这包括使用 HTTPS、验证推送消息的来源以及实施适当的错误处理。
- 用户体验:考虑实施渐进增强技术,确保即使用户的浏览器不支持某些 PWA 功能,您的应用也能良好运行。