delorex/test-repo
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs):优化 3.8-pwa-local-app 教程内容

Browse Source 
- 将示例主题统一为番茄农场 PWA
- 优化章节编号和结构
- 增加番茄农场功能描述和进阶方向
- 更新图片占位符标记
This commit is contained in:
sanbuphy
2026-02-28 19:09:56 +08:00
parent c87e4fc66f
commit f29dbc65b9
1 changed files with 319 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh-cn/stage-3/cross-platform/3.8-pwa-local-app/index.md
+319 -111
View File
@@ -1,8 +1,10 @@
# 如何开发 PWA 本地应用——让网页变成"真正的 App" # 如何开发 PWA 本地应用——让网页变成"真正的 App"
# 第 1 章：什么是 PWA 和 PWA 开发 # 1 什么是 PWA 和 PWA 开发
在这篇教程中，我们将完整跑通一条闭环：从一个普通的网页项目，到一个可以安装在电脑桌面和手机主屏幕上、断网也能正常使用的"真正的 App"。你会亲手把一个 React 应用变成 PWA，部署上线后在手机上安装体验。 在这篇教程中，我们将完整跑通一条闭环：**从一个普通的网页项目，到一个可以安装在电脑桌面和手机主屏幕上、断网也能正常使用的"真正的 App"。** 你会亲手把一个 React 应用变成 PWA，部署上线后在手机上安装体验。
我们将要开发的是一个 **番茄农场（Tomato Farm）** 应用——一个将番茄钟工作法与种菜游戏完美结合的 PWA 应用。通过 25 分钟的专注时间获得积分，用积分购买种子种植作物，随着等级提升解锁更多菜地和高级种子。最重要的是，即使断网也能正常使用，所有数据都保存在本地。
本次教程，你至少需要具备： 本次教程，你至少需要具备：
@@ -11,11 +13,9 @@
- 你的 AI 编程助手（Cursor / Trae / Claude Code 等） - 你的 AI 编程助手（Cursor / Trae / Claude Code 等）
- 一个手机（用于体验移动端安装） - 一个手机（用于体验移动端安装）
## 1.1 什么是 PWA？ ## 1.1 PWA 的定义
你有没有想过：**一个网页，能不能像微信、抖音一样，直接安装在手机桌面上，点开就用，甚至断网也能跑？** PWA（Progressive Web App，渐进式 Web 应用）是一种使用 Web 技术构建的应用程序，但它能够提供接近原生应用的用户体验。你有没有想过：**一个网页，能不能像微信、抖音一样，直接安装在手机桌面上，点开就用，甚至断网也能跑？** 答案是：可以。这就是 PWA。
答案是：可以。这就是 **PWA（Progressive Web App，渐进式 Web 应用）**。
PWA 本质上还是一个网页，但它通过几项关键技术，让自己"进化"成了一个接近原生 App 的存在： PWA 本质上还是一个网页，但它通过几项关键技术，让自己"进化"成了一个接近原生 App 的存在：
@@ -25,9 +25,17 @@ PWA 本质上还是一个网页，但它通过几项关键技术，让自己"进
简单来说，PWA 就是 **"穿上了 App 外衣的网页"**。 简单来说，PWA 就是 **"穿上了 App 外衣的网页"**。
<!-- ![placeholder: 一张对比图，左边是普通网页在浏览器中打开的样子（有地址栏），右边是同一个网页以 PWA 模式安装后的样子（独立窗口，无地址栏，像原生 App）](images/image1.png) --> <!-- ![](images/image1.png) -->
## 1.2 PWA 的三大核心技术 ## 1.2 PWA 开发
PWA 开发是指构建上述应用程序的全过程。在本教程的 Vibe Coding 开发模式中，借助 **AI 辅助编程模式**，它将开发者的角色从过去的"代码撰写者"转变为"产品架构师"：
1. **你（架构师/PM）**：负责业务逻辑设计、Prompt（提示词）编写以及最终效果验收。
2. **AI 编程助手（工程师）**：负责执行指令，将自然语言转化为标准的 React 代码和 PWA 配置，并处理语法错误和逻辑细节。
3. **Vite + vite-plugin-pwa（构建工厂）**：负责提供编译环境，将代码打包成可运行的 PWA，并自动生成 Service Worker 和 Manifest。
## 1.3 PWA 的三大核心技术
要让一个普通网页"进化"成 PWA，需要三样东西： 要让一个普通网页"进化"成 PWA，需要三样东西：
@@ -43,9 +51,9 @@ PWA 必须运行在 HTTPS 协议下。这是浏览器的硬性要求——只有
这是 PWA 的"灵魂"。它是一段运行在浏览器后台的 JavaScript 代码，充当你的 App 和网络之间的"中间人"。它可以拦截网络请求、缓存资源，从而实现离线访问。你可以把它理解为一个 **"住在浏览器里的小管家"**，负责帮你存东西、取东西。 这是 PWA 的"灵魂"。它是一段运行在浏览器后台的 JavaScript 代码，充当你的 App 和网络之间的"中间人"。它可以拦截网络请求、缓存资源，从而实现离线访问。你可以把它理解为一个 **"住在浏览器里的小管家"**，负责帮你存东西、取东西。
<!-- ![placeholder: 一张示意图，展示 PWA 三大核心技术的关系：HTTPS 是地基，Manifest 是门面，Service Worker 是引擎](images/image2.png) --> <!-- 0 -->
## 1.3 为什么选择 PWA？ ## 1.4 为什么选择 PWA？
在 Vibe Coding 时代，PWA 是性价比最高的"跨平台方案"之一： 在 Vibe Coding 时代，PWA 是性价比最高的"跨平台方案"之一：
@@ -60,35 +68,94 @@ PWA 必须运行在 HTTPS 协议下。这是浏览器的硬性要求——只有
**一句话总结**：如果你的应用不需要调用摄像头的 AR 功能或蓝牙硬件，PWA 几乎是最省心的选择。 **一句话总结**：如果你的应用不需要调用摄像头的 AR 功能或蓝牙硬件，PWA 几乎是最省心的选择。
## 1.4 本教程的路线图 ## 1.5 本教程的路线图
我们将使用 **Vite + React + vite-plugin-pwa** 的技术栈，按以下步骤完成整个流程： 为了让整个学习过程不再枯燥，本教程将全程围绕一个既有趣又实用的案例—— **《番茄农场》** 展开。这是一个番茄钟种菜游戏，将专注工作与游戏化激励完美结合。我们将结合 AI 编程助手的 Vibe Coding 模式，把从零开始到手机安装的过程，拆解为一条你可以反复复用的路线：
1. **创建项目并配置 PWA**：用 Vite 创建 React 项目，安装并配置 vite-plugin-pwa 1. **建立认知与环境**：弄清楚 PWA 的形态，安装好 Node.js 和 AI 编程助手，确保工具链通畅。
2. **本地体验 PWA**：构建生产版本，在电脑上安装并测试离线能力 2. **搭建项目骨架**：创建一个可以在本地成功运行的 React + TypeScript 项目。
3. **部署上线**：部署到 Vercel 获得 HTTPS 地址 3. **AI 迭代开发**：通过与 AI 的对话，从番茄钟倒计时开始，逐步实现种菜系统、等级系统、SVG 作物展示等功能。
4. **手机安装**：在 Android 和 iPhone 上安装并使用 4. **PWA 配置与离线测试**：添加 Service Worker 和 Manifest，测试离线能力。
5. **部署与手机安装**：部署到 Vercel 获得 HTTPS 地址，在手机上安装并使用。
# 第 2 章：创建项目并配置 PWA 这一节只负责把全景图画出来，不展开具体命令。现在只需要记住这条主线： **环境准备 → 骨架搭建 → AI 描述与生成 → PWA 配置 → 部署交付** 。接下来的章节，我们会手把手带你走完每一步。
## 2.1 用 AI 初始化项目 # 2 开发环境搭建
打开你的 AI 编程助手（Cursor / Trae / Claude Code），在对话框中输入以下 Prompt： ## 2.1 本教程会用到的工具
整个开发过程我们需要配合使用三个工具，它们分别承担了"设计"、"建造"和"验收"的角色。
- **AI 编程助手（Cursor / Trae / Claude Code）**：这是你的 **AI 编程搭子**。在 Vibe Coding 模式下，我们不再需要一行行手敲代码，而是主要在 AI 编程助手里通过自然语言告诉 AI 想要什么功能，由它来负责生成和修改代码。
- **Node.js + Vite**：它们是 **项目构建工厂**。Node.js 提供 JavaScript 运行环境，Vite 是新一代前端构建工具，速度极快，特别适合开发 PWA 应用。
- **一台手机**：作为 **测试终端** 来查看运行效果，可以直接在手机浏览器中访问部署后的 PWA，体验真实的安装和离线功能。
## 2.2 Node.js 安装
Node.js 是我们开发 PWA 的基础环境。请访问官网 [https://nodejs.org](https://nodejs.org)，下载 **LTS（长期支持）版本**（本教程基于 Node.js 18.x 以上版本编写）。
下载完成后，像安装普通软件一样双击运行，保持默认选项一路"Next"即可完成安装。
安装完成后，打开终端（Windows 用户打开 CMD 或 PowerShell，Mac 用户打开 Terminal），输入以下命令验证安装是否成功：
```bash
node --version
npm --version
```
如果能看到版本号输出（如 `v18.17.0` 和 `9.6.7`），说明安装成功。
<!-- 0 -->
## 2.3 AI 编程助手安装
AI 编程助手是我们进行 **Vibe Coding** 的主战场。你可以把它简单理解为一个 **"内置了超级 AI 的代码编辑器"**。
**推荐选择：**
- **Trae**：访问官网 [https://www.trae.cn](https://www.trae.cn)，根据你的电脑系统下载对应版本
- **Cursor**：访问官网 [https://cursor.sh](https://cursor.sh)，下载安装
- **Claude Code**：如果你已经在使用 Claude，可以直接使用 Claude Code 功能
安装过程非常简单，和安装普通软件一样，双击安装包并按提示点击"下一步"即可完成。准备好这个工具后，在接下来的实战中，我们就不需要面对枯燥的代码框发呆了，而是直接在这里打开项目，通过对话框用自然语言指挥 AI 帮我们写代码、改 Bug。
<!-- 0 -->
## 2.4 新建一个项目
打开你的 AI 编程助手，在对话框中输入以下 Prompt：
``` ```
请帮我创建一个 Vite + React + TypeScript 项目，项目名叫 my-pwa-app。 请帮我创建一个 React 项目，项目名叫 tomato-farm-pwa，用来做番茄农场应用。
要求： 需要支持 TypeScript，并且加上 PWA 功能（就是能让网页安装到手机桌面的那种）。
1. 使用 npm create vite@latest 创建项目 ```
2. 选择 React 框架和 TypeScript 模板
3. 创建完成后进入项目目录并安装依赖 AI 会自动执行以下步骤：
4. 额外安装 vite-plugin-pwa 插件：npm install vite-plugin-pwa -D
**第一步：创建项目**
```bash
npm create vite@latest tomato-farm-pwa -- --template react-ts
```
**第二步：进入项目并安装依赖**
```bash
cd tomato-farm-pwa
npm install
```
**第三步：安装 PWA 插件**
```bash
npm install vite-plugin-pwa -D
``` ```
等 AI 执行完毕后，你的项目目录结构大致如下： 等 AI 执行完毕后，你的项目目录结构大致如下：
``` ```
my-pwa-app/ tomato-farm-pwa/
├── public/ # 静态资源（图标放这里） ├── public/ # 静态资源（图标、SVG 素材放这里）
├── src/ ├── src/
│ ├── App.tsx # 主组件 │ ├── App.tsx # 主组件
│ ├── main.tsx # 入口文件 │ ├── main.tsx # 入口文件
@@ -99,39 +166,49 @@ my-pwa-app/
└── tsconfig.json └── tsconfig.json
``` ```
## 2.2 准备 App 图标 ## 2.5 理解项目结构
项目创建成功后，我们需要了解几个关键文件的作用：
| 文件/目录 | 作用说明 |
|----------|---------|
| `src/App.tsx` | 应用主组件，所有页面逻辑都在这里编写 |
| `src/main.tsx` | 应用入口文件，负责挂载 React 应用 |
| `vite.config.ts` | Vite 配置文件，PWA 的核心配置写在这里 |
| `public/` | 静态资源目录，PWA 图标、SVG 素材放在这里 |
| `index.html` | HTML 入口文件，通常不需要修改 |
我们作为初学者，主要关注三个文件即可：
- `App.tsx`：控制程序行为、决定"屏幕上显示什么"
- `vite.config.ts`：配置 PWA 功能、决定"应用如何安装和缓存"
- `public/`：存放应用图标和素材
## 2.6 准备 App 图标
PWA 需要图标才能被安装。我们至少需要两个尺寸：**192x192** 和 **512x512** 像素的 PNG 图片。 PWA 需要图标才能被安装。我们至少需要两个尺寸：**192x192** 和 **512x512** 像素的 PNG 图片。
你可以让 AI 帮你生成： 你可以让 AI 帮你生成：
``` ```
请帮我用 HTML Canvas 生成两个简单的 PWA 图标（192x192 和 512x512）， 请帮我生成两个应用图标，尺寸分别是 192x192 和 512x512。
背景色用渐变蓝色，中间写一个白色的字母 "P"。 背景用绿色渐变，中间画一个红色番茄，保存到 public 文件夹里。
保存到 public/icon-192.png 和 public/icon-512.png。
``` ```
或者你也可以用任何设计工具（Figma、Canva）做一个你喜欢的图标，放到 `public/` 目录下。 或者你也可以用任何设计工具（Figma、Canva）做一个你喜欢的图标，放到 `public/` 目录下。
<!-- ![placeholder: 两个 PWA 图标示例，一个 192x192，一个 512x512，蓝色渐变背景加白色字母](images/image3.png) --> <!-- 0 -->
## 2.3 配置 vite-plugin-pwa ## 2.7 配置 vite-plugin-pwa
这是最关键的一步。打开 `vite.config.ts`，让 AI 帮你配置 PWA 插件： 这是最关键的一步。打开 `vite.config.ts`，让 AI 帮你配置 PWA 插件：
``` ```
请帮我修改 vite.config.ts，添加 vite-plugin-pwa 的配置。要求： 请帮我把 vite.config.ts 改成 PWA 配置，让网页可以安装到手机桌面：
1. 引入 VitePWA 插件 - 应用名称叫"番茄农场"，主题是绿色
2. 注册类型设为 autoUpdate（自动更新） - 使用 public 目录下的 icon-192.png 和 icon-512.png 作为图标
3. 配置 manifest： - 开启自动更新
- name: "My PWA App" - 缓存所有 js、css、html 和图片文件，让应用可以离线使用
- short_name: "MyPWA"
- description: "一个示例 PWA 应用"
- theme_color: "#4285f4"
- background_color: "#ffffff"
- display: "standalone"
- 图标使用 public 目录下的 icon-192.png 和 icon-512.png
4. workbox 配置：缓存所有 js、css、html、png、svg 文件
``` ```
AI 会帮你生成类似这样的配置： AI 会帮你生成类似这样的配置：
@@ -147,10 +224,10 @@ export default defineConfig({
VitePWA({ VitePWA({
registerType: 'autoUpdate', registerType: 'autoUpdate',
manifest: { manifest: {
name: 'My PWA App', name: '番茄农场',
short_name: 'MyPWA', short_name: '番茄农场',
description: '一个示例 PWA 应用', description: '专注种菜，收获成长',
theme_color: '#4285f4', theme_color: '#4CAF50',
background_color: '#ffffff', background_color: '#ffffff',
display: 'standalone', display: 'standalone',
icons: [ icons: [
@@ -180,28 +257,156 @@ export default defineConfig({
* `display: 'standalone'`：安装后以独立窗口运行，没有浏览器地址栏，看起来像原生 App。 * `display: 'standalone'`：安装后以独立窗口运行，没有浏览器地址栏，看起来像原生 App。
* `workbox.globPatterns`：告诉 Service Worker 要缓存哪些类型的文件，这些文件在离线时也能访问。 * `workbox.globPatterns`：告诉 Service Worker 要缓存哪些类型的文件，这些文件在离线时也能访问。
<!-- ![placeholder: vite.config.ts 文件的编辑器截图，展示 PWA 配置代码](images/image4.png) --> <!-- 0 -->
## 2.4 给 App 添加一些内容 # 3 番茄农场 PWA 开发
一个空白页面没什么意思。让 AI 帮你写一个简单但实用的页面，比如一个 **待办事项（Todo）应用**——这样我们还能体验离线数据持久化： 在前两章，我们已经搞清楚了 PWA 是什么，并把开发环境搭建完毕。从这一节开始，我们不再纸上谈兵，而是正式进入实战环节。我们将采用 Vibe Coding 模式，从零打造一款既有趣又实用的应用—— **"番茄农场" (Tomato Farm)** 。它不仅将番茄钟工作法与游戏化激励完美结合，而且涵盖了 PWA 开发的核心要素：**UI 交互（番茄钟）、数据存储（积分和作物）、离线能力（Service Worker 缓存）**。
接下来，请跟随我的节奏，向 AI 发出第一道指令。
## 3.1 第一次"总指令"：从零到一
在 Vibe Coding 模式下，我们不需要像传统开发那样先创建布局文件、再写逻辑代码。我们要做的，是 **一次性把需求描述清楚，让 AI 帮我们生成第一版可运行的雏形**。
在 AI 编程助手中打开我们刚才创建的项目目录，在对话框中输入下面这段 Prompt：
``` ```
请帮我修改 App.tsx，实现一个简单的待办事项应用： 请帮我写番茄农场应用的主页面，包含以下功能：
1. 顶部有一个输入框和 "添加" 按钮
2. 下方展示待办列表，每项有完成/删除按钮 **番茄钟功能：**
3. 数据使用 localStorage 持久化存储 - 一个 25 分钟的倒计时器，可以开始、暂停、重置
4. 界面风格简洁现代，使用蓝色主题色 #4285f4 - 显示剩余时间和进度条
5. 适配移动端（响应式布局） - 专注完成后给用户 10 个积分
**种菜功能：**
- 3 块菜地，最开始只有第 1 块能用，后面的要升级解锁
- 商店里可以买菜籽：胡萝卜 5 积分、番茄 10 积分、玉米 15 积分
- 买了种子种到地里，作物会慢慢长大，成熟后可以收获换积分
**等级系统：**
- 根据总积分升级：0-100 分是新手农民，100-300 分是熟练农民，300 分以上是农场大师
- 升级后解锁新的菜地和更高级的种子
**界面设计：**
- 顶部显示等级、积分和升级进度条
- 中间是番茄钟倒计时
- 下面是菜地网格
- 底部是商店按钮
- 整体用绿色主题，看起来清新可爱
- 要能适配手机屏幕
**数据保存：**
- 所有数据（积分、等级、菜地状态）都要保存下来，刷新页面不会丢失
``` ```
这个 Todo 应用非常适合演示 PWA 的能力：即使断网，你依然可以添加和管理待办事项，因为数据存在本地，页面资源也被 Service Worker 缓存了。 发送指令后，你会看到 AI 开始思考并分析你的项目结构。几秒钟后，它会直接生成 `App.tsx` 的完整代码。
<!-- ![placeholder: Todo 应用的界面截图，展示输入框、待办列表和完成/删除按钮](images/image5.png) --> 1. 通过它的回答，我们可以看到它的思考逻辑、交互逻辑等等
2. 我们可以直观的看到它对哪些代码进行了改写
3. 如果我们对生成的效果不满意，我们可以回退到上一个版本
# 第 3 章：本地体验 PWA <!-- 0 -->
## 3.1 构建并预览 ## 3.2 运行与查看（本地开发服务器）
此时 AI 已经完成了第一轮开发，但请记住，在 AI 编程助手中我们看到的只是一堆代码"图纸"，而非可以点击交互的真实应用。我们需要启动本地开发服务器，让我们能立刻把刚才的代码运行起来，查看到真实的运行效果。
在 AI 编程助手的终端中执行：
```bash
npm run dev
```
几秒钟后，终端会显示类似这样的输出：
```
VITE v5.0.0 ready in 300 ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
➜ press h + enter to show help
```
打开浏览器访问 `http://localhost:5173/`，你应该能看到：
- 顶部显示等级、积分和进度条
- 中间是一个番茄钟倒计时器
- 下方是菜地区域
- 底部有商店按钮
试着点击"开始专注"按钮，看看倒计时是否正常工作。点击菜地，看看是否能购买种子并种植。这就是你的第一个 PWA 应用雏形！
<!-- 0 -->
## 3.3 优化迭代（添加 SVG 作物和动画）
此时，我们的 App 已经具备了雏形：番茄钟倒计时、种菜系统、等级系统。但它现在可能还比较简陋，作物可能只是简单的文字或方块。接下来，我们将通过添加精美的 SVG 作物和生长动画，让这个番茄农场变得生动有趣。
**这正是 Vibe Coding 模式最迷人的地方。** 在传统开发中，绘制 SVG 图形和实现复杂的生长动画往往是新手的噩梦。你不仅要处理 SVG 的路径绘制，还要计算动画的时间曲线。但在 Vibe Coding 模式下，这些底层技术细节你完全不需要关心，你只需要像导演一样告诉 AI："给作物加上精美的 SVG 图案，种植后要有生长动画"，复杂的代码实现瞬间就能完成。
**第一步：准备 SVG 作物素材**
你可以让 AI 直接在代码中绘制 SVG，也可以准备现成的 SVG 文件放到 `public/` 目录。本教程推荐让 AI 直接生成 SVG 代码，这样更灵活。
**第二步：下达迭代指令**
回到 AI 编程助手，输入以下 Prompt：
```
请帮我把作物画得更好看一些，加上生长动画：
**作物图案：**
- 胡萝卜：橙色身体，绿色叶子
- 番茄：红色圆形，带绿色小叶子
- 玉米：黄色玉米棒，绿色外皮
都用简单的图形画出来就行
**生长动画：**
- 刚种下去是小苗，慢慢长大，最后成熟
- 分 3 个阶段显示不同的样子
**收获效果：**
- 点击成熟的作物，播放简单的收获动画
- 显示获得了多少积分
**整体优化：**
- 菜地格子要有边框和背景色
- 作物在格子中间显示
- 看起来要可爱一点
```
AI 会再次修改代码，帮你处理复杂的 SVG 绘制和动画逻辑。修改完成后，刷新浏览器页面，你应该能看到精美的作物图案和流畅的生长动画。
<!-- 0 -->
## 3.4 添加音效和提示（可选）
如果你想让番茄农场更加沉浸，可以添加音效和提示功能。这同样只需要一个简单的 Prompt：
```
请帮番茄农场加上音效和提示：
**音效：**
- 开始专注时播放"叮"的一声
- 专注完成时播放胜利音效
- 种植和收获时也要有对应的音效
**提示：**
- 专注完成后弹出"恭喜你完成专注！"
- 升级时显示"恭喜升级到 XX 级！"
- 解锁新菜地时提示"解锁了新菜地！"
可以用简单的音频文件或者 Web Audio API 来实现
```
AI 会帮你添加音效和提示功能，让你的番茄农场更加生动有趣。
<!-- 0 -->
# 4 本地体验 PWA
## 4.1 构建并预览
PWA 的 Service Worker 只在生产构建中生效（开发模式下不会注册）。所以我们需要先构建，再预览： PWA 的 Service Worker 只在生产构建中生效（开发模式下不会注册）。所以我们需要先构建，再预览：
@@ -215,7 +420,7 @@ PWA 的 Service Worker 只在生产构建中生效（开发模式下不会注册
预览服务器启动后，打开浏览器访问提示的地址（通常是 `http://localhost:4173`）。 预览服务器启动后，打开浏览器访问提示的地址（通常是 `http://localhost:4173`）。
## 3.2 在电脑上安装 PWA ## 4.2 在电脑上安装 PWA
打开预览地址后，你会注意到浏览器地址栏右侧出现了一个 **安装图标**（一个小小的下载箭头或 "+" 号）。 打开预览地址后，你会注意到浏览器地址栏右侧出现了一个 **安装图标**（一个小小的下载箭头或 "+" 号）。
@@ -225,9 +430,9 @@ PWA 的 Service Worker 只在生产构建中生效（开发模式下不会注册
2. 在弹出的对话框中点击 **"安装"** 2. 在弹出的对话框中点击 **"安装"**
3. PWA 会以独立窗口打开，同时在你的桌面/开始菜单/Dock 中创建快捷方式 3. PWA 会以独立窗口打开，同时在你的桌面/开始菜单/Dock 中创建快捷方式
安装后的 PWA 看起来就像一个原生桌面应用——没有地址栏，没有标签页，有自己的窗口和图标。 安装后的 PWA 看起来就像一个原生桌面应用——没有地址栏，没有标签页，有自己的窗口和图标。现在你可以随时打开番茄农场，开始专注种菜之旅！
<!-- ![placeholder: 两张对比截图：左边是浏览器中的安装提示，右边是安装后的独立窗口效果](images/image6.png) --> <!-- 0 -->
**macOS Safari 安装步骤：** **macOS Safari 安装步骤：**
@@ -235,129 +440,132 @@ PWA 的 Service Worker 只在生产构建中生效（开发模式下不会注册
2. 点击菜单栏的 **文件 → 添加到程序坞** 2. 点击菜单栏的 **文件 → 添加到程序坞**
3. PWA 图标会出现在 Dock 中 3. PWA 图标会出现在 Dock 中
## 3.3 测试离线能力 ## 4.3 测试离线能力
这是 PWA 最酷的部分。让我们验证一下离线是否真的能用： 这是 PWA 最酷的部分。让我们验证一下离线是否真的能用：
1. 确保 PWA 已经在浏览器中打开过一次（让 Service Worker 缓存资源） 1. 确保 PWA 已经在浏览器中打开过一次（让 Service Worker 缓存资源）
2. **断开网络**（关闭 Wi-Fi 或拔掉网线） 2. **断开网络**（关闭 Wi-Fi 或拔掉网线）
3. 刷新页面——你会发现 **App 依然正常加载！** 3. 刷新页面——你会发现 **番茄农场 App 依然正常加载！**
4. 添加几个待办事项——数据正常保存在 localStorage 中 4. 开始一个番茄钟——专注完成后获得积分，购买种子种植——所有数据正常保存在 localStorage 中
你也可以打开 Chrome DevTools（F12）→ Application → Service Workers，查看 Service Worker 的运行状态和缓存的资源列表。 你也可以打开 Chrome DevTools（F12）→ Application → Service Workers，查看 Service Worker 的运行状态和缓存的资源列表。
<!-- ![placeholder: Chrome DevTools 的 Application 面板截图，展示 Service Worker 状态和 Cache Storage 中缓存的文件列表](images/image7.png) --> <!-- 0 -->
# 第 4 章：部署上线 # 5 部署上线
PWA 必须运行在 HTTPS 上才能正常工作。好消息是，现在主流的部署平台都自动提供免费的 HTTPS。我们以 **Vercel** 为例（也可以用 Netlify 或 GitHub Pages）。 PWA 必须运行在 HTTPS 上才能正常工作。好消息是，现在主流的部署平台都自动提供免费的 HTTPS。我们以 **Vercel** 为例（也可以用 Netlify 或 GitHub Pages）。
## 4.1 部署到 Vercel ## 5.1 部署到 Vercel
**第一步：安装 Vercel CLI** **第一步：安装部署工具**
``` ```
请帮我全局安装 Vercel CLI：npm install -g vercel 请帮我安装 Vercel 的部署工具
``` ```
**第二步：部署** **第二步：部署项目**
在项目根目录下执行：
``` ```
请帮我执行 vercel 命令部署项目。 请帮我部署项目到 Vercel，项目名叫 tomato-farm-pwa
当提示 "Set up and deploy?" 时选择 Yes。
当提示 "Which scope?" 时选择你的账号。
当提示 "Link to existing project?" 时选择 No。
当提示 "What's your project's name?" 时输入 my-pwa-app。
当提示 "In which directory is your code located?" 时直接回车（默认当前目录）。
当提示 "Want to modify these settings?" 时选择 No。
``` ```
等待几十秒，Vercel 会自动构建并部署你的项目。完成后，你会得到一个类似 `https://my-pwa-app.vercel.app` 的 HTTPS 地址。 AI 会自动处理所有部署步骤，你只需要在提示时：
- 选择你的账号
- 确认创建新项目
- 其他按默认选项即可
<!-- ![placeholder: 终端中 Vercel 部署成功的截图，展示部署后的 URL](images/image8.png) --> 等待几十秒，Vercel 会自动构建并部署你的项目。完成后，你会得到一个类似 `https://tomato-farm-pwa.vercel.app` 的 HTTPS 地址。
<!-- 0 -->
**第三步：验证 PWA** **第三步：验证 PWA**
在浏览器中打开部署后的地址，你应该能看到： 在浏览器中打开部署后的地址，你应该能看到：
1. 地址栏右侧出现安装图标 1. 地址栏右侧出现安装图标
2. 打开 DevTools → Application → Manifest，能看到你配置的 App 信息 2. 打开 DevTools → Application → Manifest，能看到你配置的 App 信息（名称为"番茄农场"）
3. Service Workers 标签下显示 Service Worker 已激活 3. Service Workers 标签下显示 Service Worker 已激活
## 4.2 使用 GitHub Pages 部署（替代方案） ## 5.2 使用 GitHub Pages 部署（替代方案）
如果你更喜欢 GitHub Pages，需要额外配置 `base` 路径： 如果你更喜欢 GitHub Pages，需要额外配置路径：
``` ```
请帮我修改 vite.config.ts，添加 base 配置： 请帮我修改配置，让项目能部署到 GitHub Pages。
base: '/my-pwa-app/'（替换为你的 GitHub 仓库名） 我的仓库名是 tomato-farm-pwa，需要相应调整路径配置。
同时更新 manifest 中的 icon 路径，加上 base 前缀。
``` ```
然后将构建产物推送到 GitHub 仓库的 `gh-pages` 分支即可。 然后将构建产物推送到 GitHub 仓库的 `gh-pages` 分支即可。
# 第 5 章：在手机上安装 PWA # 6 在手机上安装 PWA
这是最激动人心的部分——让你的网页变成手机上的"App"。 这是最激动人心的部分——让你的番茄农场网页变成手机上的"App"。
## 5.1 Android 手机安装 ## 6.1 Android 手机安装
1. 在手机的 **Chrome 浏览器** 中打开你部署好的 PWA 地址 1. 在手机的 **Chrome 浏览器** 中打开你部署好的番茄农场 PWA 地址
2. Chrome 可能会自动弹出 **"添加到主屏幕"** 的横幅提示，直接点击即可 2. Chrome 可能会自动弹出 **"添加到主屏幕"** 的横幅提示，直接点击即可
3. 如果没有自动弹出，点击右上角的 **三个点菜单 → "安装应用"** 或 **"添加到主屏幕"** 3. 如果没有自动弹出，点击右上角的 **三个点菜单 → "安装应用"** 或 **"添加到主屏幕"**
4. 确认安装后，你的手机桌面上就会出现 App 图标 4. 确认安装后，你的手机桌面上就会出现番茄农场 App 图标
打开它，你会发现它以全屏模式运行，没有浏览器的地址栏和导航按钮，和原生 App 几乎一模一样。 打开它，你会发现它以全屏模式运行，没有浏览器的地址栏和导航按钮，和原生 App 几乎一模一样。现在你可以随时随地开始专注种菜了！
<!-- ![placeholder: Android 手机上的安装流程截图：左边是 Chrome 中的安装提示，中间是确认对话框，右边是安装后桌面上的图标](images/image9.png) --> <!-- 0 -->
## 5.2 iPhone 安装 ## 6.2 iPhone 安装
iOS 上安装 PWA 只能通过 **Safari** 浏览器（其他浏览器不支持）： iOS 上安装 PWA 只能通过 **Safari** 浏览器（其他浏览器不支持）：
1. 在 **Safari** 中打开你的 PWA 地址 1. 在 **Safari** 中打开你的番茄农场 PWA 地址
2. 点击底部的 **分享按钮**（方框加向上箭头的图标） 2. 点击底部的 **分享按钮**（方框加向上箭头的图标）
3. 在弹出的菜单中选择 **"添加到主屏幕"** 3. 在弹出的菜单中选择 **"添加到主屏幕"**
4. 给 App 起个名字，点击 **"添加"** 4. 给 App 起个名字，点击 **"添加"**
从 iOS 26 开始，所有添加到主屏幕的网站都会默认以独立 App 模式打开，这是一个重大改进。 从 iOS 26 开始，所有添加到主屏幕的网站都会默认以独立 App 模式打开，这是一个重大改进。
<!-- ![placeholder: iPhone 上的安装流程截图：左边是 Safari 的分享菜单，右边是添加到主屏幕的确认页面](images/image10.png) --> <!-- 0 -->
> **iOS 的已知限制**： > **iOS 的已知限制**：
> * 推送通知需要 iOS 16.4 以上，且必须先将 PWA 添加到主屏幕 > * 推送通知需要 iOS 16.4 以上，且必须先将 PWA 添加到主屏幕
> * 不支持后台同步（Background Sync） > * 不支持后台同步（Background Sync）
> * 存储空间比 Android 更受限 > * 存储空间比 Android 更受限
## 5.3 用 Lighthouse 审计你的 PWA ## 6.3 用 Lighthouse 审计你的 PWA
Google 提供了一个叫 **Lighthouse** 的工具，可以给你的 PWA 打分。打开 Chrome DevTools（F12）→ Lighthouse 标签 → 勾选 "Progressive Web App" → 点击 "Analyze page load"。 Google 提供了一个叫 **Lighthouse** 的工具，可以给你的 PWA 打分。打开 Chrome DevTools（F12）→ Lighthouse 标签 → 勾选 "Progressive Web App" → 点击 "Analyze page load"。
一个合格的 PWA 应该在 PWA 评分上拿到满分。如果有扣分项，Lighthouse 会告诉你具体原因和修复建议。 一个合格的番茄农场 PWA 应该在 PWA 评分上拿到满分。如果有扣分项，Lighthouse 会告诉你具体原因和修复建议。
<!-- ![placeholder: Lighthouse 审计结果截图，展示 PWA 评分为满分，各项检查都通过](images/image11.png) --> <!-- 0 -->
# 第 6 章：写在最后 # 7 写在最后
恭喜你！你已经成功构建了一个可以安装在电脑和手机上的 PWA 应用。回顾一下我们做了什么： 恭喜你！你已经成功构建了一个可以安装在电脑和手机上的番茄钟种菜 PWA 应用。回顾一下我们做了什么：
1. 用 Vite + React 创建了一个 Web 应用 1. 用 Vite + React 创建了一个番茄农场 Web 应用
2. 通过 vite-plugin-pwa 添加了 Service Worker 和 Manifest 2. 通过 vite-plugin-pwa 添加了 Service Worker 和 Manifest
3. 部署到 Vercel 获得了 HTTPS 地址 3. 部署到 Vercel 获得了 HTTPS 地址
4. 在电脑和手机上都成功安装并体验了离线能力 4. 在电脑和手机上都成功安装并体验了离线能力
现在你的番茄农场 PWA 已经可以实现：
* **专注种菜**：通过番茄钟机制帮助用户专注学习或工作
* **游戏化激励**：通过种菜、升级、解锁新内容来激励持续使用
* **离线可用**：即使没有网络也能继续专注、种菜、管理自己的农场
* **跨平台安装**：一次开发，可以在各种设备上安装使用
PWA 的魅力在于它的"渐进式"——你不需要一开始就做到完美。先让你的网页能被安装、能离线访问，然后再逐步添加推送通知、后台同步等高级功能。 PWA 的魅力在于它的"渐进式"——你不需要一开始就做到完美。先让你的网页能被安装、能离线访问，然后再逐步添加推送通知、后台同步等高级功能。
**进阶方向：** **进阶方向：**
* **推送通知**：使用 Push API + Notification API，让你的 App 能像微信一样发送消息提醒 * **推送通知**：使用 Push API + Notification API，在番茄钟结束时提醒用户休息，或在作物成熟时通知收获
* **后台同步**：使用 Background Sync API，在网络恢复时自动同步离线期间的操作 * **后台同步**：使用 Background Sync API，在网络恢复时同步用户的农场数据到云端
* **更智能的缓存策略**：根据不同类型的资源使用不同的 Workbox 缓存策略（CacheFirst、NetworkFirst、StaleWhileRevalidate） * **更智能的缓存策略**：根据不同类型的资源使用不同的 Workbox 缓存策略（CacheFirst、NetworkFirst、StaleWhileRevalidate）
* **发布到应用商店**：使用 [PWA Builder](https://www.pwabuilder.com/) 可以将 PWA 打包成 Android APK 或 Microsoft Store 应用 * **发布到应用商店**：使用 [PWA Builder](https://www.pwabuilder.com/) 可以将番茄农场 PWA 打包成 Android APK 或 Microsoft Store 应用
* **社交功能**：增加好友系统，让用户可以互相访问农场、交换作物等
***一套代码，全平台通用——这就是 PWA 的力量。*** ***一套代码，全平台通用——这就是 PWA 的力量。专注种菜，收获成长！***
# 参考文献 # 参考文献