> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monad.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何使用 Next.js Serwist Thirdweb 嵌入式钱包模板

本指南将带您使用 [模板](https://github.com/monad-developers/next-serwist-thirdweb),该模板使用 [Next.js](https://nextjs.org/docs)、[Serwist](https://serwist.pages.dev/)(离线能力) 和 [Thirdweb](https://portal.thirdweb.com/) 嵌入式钱包在 Monad 上构建渐进式 Web 应用(PWA)。

## 前置条件

* [Node.js](https://nodejs.org/)(v18 或更高版本)
* 一个 [Thirdweb 账户](https://thirdweb.com/)

## 设置

1. 克隆仓库:

   ```bash theme={null}
   git clone https://github.com/monad-developers/next-serwist-thirdweb.git
   ```

2. `cd` 进入项目目录:

   ```bash theme={null}
   cd next-serwist-thirdweb
   ```

3. 安装依赖:

   ```bash theme={null}
   npm install
   ```

4. 在根目录创建 `.env.local` 文件:

   ```bash theme={null}
   cp .env.example .env.local
   ```

5. 开始向 `.env.local` 文件添加环境变量:

   ```bash theme={null}
   # Thirdweb Configuration (Required)
   NEXT_PUBLIC_THIRDWEB_CLIENT_ID=your_thirdweb_client_id_here

   # Web Push (Required)
   WEB_PUSH_EMAIL=user@example.com
   WEB_PUSH_PRIVATE_KEY=your_vapid_private_key
   NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY=your_vapid_public_key
   ```

   如果您丢失了 Thirdweb Client ID,可以在 Thirdweb 仪表盘中找到。

6. 为 Web 推送通知生成 VAPID 密钥:

   ```bash theme={null}
   npx web-push generate-vapid-keys --json
   ```

   将生成的密钥复制到您的 .env.local 文件中(替换步骤 5 中的占位值)。

7. 运行应用:

   **开发模式**:

   ```bash theme={null}
   npm run dev
   ```

   应用将在 [http://localhost:3000](http://localhost:3000) 上可用。

   **生产模式:**

   完整的 PWA 功能(包括安装提示):

   ```bash theme={null}
   npm run build && npm run start
   ```

## 模板文件夹结构

```
next-serwist-thirdweb/
├── app/
│   ├── components/         # React components
│   │   ├── InstallPWA.tsx  # PWA install prompt
│   │   └── ...
│   ├── ~offline/           # Offline page
│   └── ...
├── public/                 # Static assets
└── ...
```

## 更改应用名称

* Edit [`public/manifest.json`](https://github.com/monad-developers/next-serwist-thirdweb/blob/main/public/manifest.json):
  * 修改 `name` 和 `short_name` 字段
* 运行 `npm run build` 更新应用

## 通知设置

<Warning title="启用通知以获得最佳体验!">
  要接收此应用的推送通知,您需要在浏览器和/或系统设置中启用通知。
</Warning>

### 浏览器设置

<Accordion title="Chrome/Edge">
  1. 点击地址栏中的锁形图标 🔒
  2. 将 "Notifications" 设置为 "Allow"
  3. 或前往 Settings → Privacy and security → Site Settings → Notifications
</Accordion>

<Accordion title="Firefox">
  1. 点击地址栏中的盾牌图标 🛡️
  2. 如有需要,为此站点关闭 "Enhanced Tracking Protection"
  3. 在出现提示时允许通知
  4. 或前往 Settings → Privacy & Security → Permissions → Notifications
</Accordion>

<Accordion title="Safari">
  1. 前往 Safari → Settings → Websites → Notifications
  2. 找到您的站点并将其设置为 "Allow"
</Accordion>

### 系统设置

<Accordion title="macOS">
  1. System Preferences → Notifications & Focus
  2. 找到您的浏览器并确保通知已启用
  3. 在浏览器设置中勾选 "Allow notifications from websites"
</Accordion>

<Accordion title="Windows">
  1. Settings → System → Notifications & actions
  2. 确保您的浏览器可以发送通知
  3. 检查浏览器通知设置
</Accordion>

<Accordion title="iOS">
  1. Settings → Notifications → \[您的浏览器]
  2. 启用 "Allow Notifications"
  3. 同时在浏览器设置中启用
</Accordion>

<Accordion title="Android">
  1. Settings → Apps → \[您的浏览器] → Notifications
  2. 启用通知
  3. 检查浏览器通知权限
</Accordion>

### 需要后端集成

<Info title="`SendNotification.tsx` 组件是示例代码">
  [`SendNotification.tsx`](https://github.com/monad-developers/next-serwist-thirdweb/blob/main/app/components/SendNotification.tsx) 需要后端实现:

  * 在用户订阅时 **保存订阅数据**(参见代码中的 TODO 注释)
  * 在用户取消订阅时 **删除订阅数据**
  * **实现 `/notification` 端点** 以发送实际的推送通知
  * 使用 **`web-push` 库** 或类似方案进行服务器端通知投递
</Info>

### 自定义通知内容

要自定义推送通知内容,请编辑 [`app/notification/route.ts`](https://github.com/monad-developers/next-serwist-thirdweb/blob/main/app/notification/route.ts) ,并修改 `sendNotification` 调用中的 `title`、`message`、`icon` 及其他属性。

## 修改应用图标和启动画面

### 应用图标

将 [`public/icons/`](https://github.com/monad-developers/next-serwist-thirdweb/tree/main/public/icons) 目录下的图标文件替换为您的自定义图标:

* **`icon-512x512.png`** - 主应用图标(512×512px)
* **`android-chrome-192x192.png`** - Android 图标(192×192px)
* **`apple-touch-icon.png`** - iOS 主屏幕图标(180×180px)

同时更新 favicon:

* **`public/favicon.ico`** - 浏览器 favicon
* **`app/favicon.ico`** - Next.js 应用 favicon

### 启动画面

启动画面根据您的应用图标和在以下位置定义的主题颜色自动生成: [`public/manifest.json`](https://github.com/monad-developers/next-serwist-thirdweb/blob/main/public/manifest.json)。要自定义:

1. 在以下位置更新 `theme_color` 和 `background_color`: [`public/manifest.json`](https://github.com/monad-developers/next-serwist-thirdweb/blob/main/public/manifest.json)
2. 确保您的主图标(`icon-512x512.png`)代表您的品牌
3. 运行 `npm run build` 以应用更改

<Tip>
  使用 [PWA Asset Generator](https://www.pwabuilder.com/imageGenerator) 等工具从单张源图片生成所有所需的图标尺寸。
</Tip>

## 部署到 Vercel

### 使用 Vercel 仪表盘

1. **连接您的仓库**:

   * 将您的代码推送到 GitHub
   * 访问 [vercel.com](https://vercel.com) 并导入您的仓库

2. **配置环境变量**:

   * 在您的 Vercel 项目仪表盘,前往 Settings → Environment Variables
   * 添加与您的 `.env.local` 相同的变量:
     ```
     NEXT_PUBLIC_THIRDWEB_CLIENT_ID
     WEB_PUSH_EMAIL
     WEB_PUSH_PRIVATE_KEY
     NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY
     ```

3. **部署**:Vercel 将自动构建并部署您的应用

4. **更新 Thirdweb 设置**:在您的 Thirdweb 仪表盘中,将您的 Vercel 域名(例如 `your-app.vercel.app`)添加到允许的来源

<Tip>
  PWA 功能(安装提示、离线支持、推送通知)会在 HTTPS 域名上(如 Vercel 部署)自动生效。
</Tip>

### 使用 Vercel CLI

或者,使用 Vercel CLI 部署:

1. **安装 Vercel CLI**:

   ```bash theme={null}
   npm i -g vercel
   ```

2. **登录 Vercel**:

   ```bash theme={null}
   vercel login
   ```

3. **部署**:

   ```bash theme={null}
   vercel
   ```

   按照提示配置您的项目。

4. **添加环境变量**:

   ```bash theme={null}
   vercel env add NEXT_PUBLIC_THIRDWEB_CLIENT_ID
   vercel env add WEB_PUSH_EMAIL
   vercel env add WEB_PUSH_PRIVATE_KEY
   vercel env add NEXT_PUBLIC_WEB_PUSH_PUBLIC_KEY
   ```

   您也可以前往 Vercel 仪表盘在那里添加环境变量。

5. **使用环境变量重新部署**:
   ```bash theme={null}
   vercel --prod
   ```

## 了解更多

* Serwist:[文档](https://serwist.pages.dev/) | [指南](https://serwist.pages.dev/docs/next/getting-started)
* Thirdweb:[文档](https://portal.thirdweb.com) | [指南](https://portal.thirdweb.com/)
* Monad:[支持的工具和基础设施](/zh/tooling-and-infra)