From f29dbc65b99b470c20dd6039922ce9be39fffc84 Mon Sep 17 00:00:00 2001 From: sanbuphy Date: Sat, 28 Feb 2026 19:09:56 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=E4=BC=98=E5=8C=96=203.8-pwa-local-a?= =?UTF-8?q?pp=20=E6=95=99=E7=A8=8B=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将示例主题统一为番茄农场 PWA - 优化章节编号和结构 - 增加番茄农场功能描述和进阶方向 - 更新图片占位符标记 --- .../cross-platform/3.8-pwa-local-app/index.md | 430 +++++++++++++----- 1 file changed, 319 insertions(+), 111 deletions(-) diff --git a/docs/zh-cn/stage-3/cross-platform/3.8-pwa-local-app/index.md b/docs/zh-cn/stage-3/cross-platform/3.8-pwa-local-app/index.md index 3590a7f..555aa06 100644 --- a/docs/zh-cn/stage-3/cross-platform/3.8-pwa-local-app/index.md +++ b/docs/zh-cn/stage-3/cross-platform/3.8-pwa-local-app/index.md @@ -1,8 +1,10 @@ # 如何开发 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 等） - 一个手机（用于体验移动端安装） -## 1.1 什么是 PWA？ +## 1.1 PWA 的定义 -你有没有想过：**一个网页，能不能像微信、抖音一样，直接安装在手机桌面上，点开就用，甚至断网也能跑？** - -答案是：可以。这就是 **PWA（Progressive Web App，渐进式 Web 应用）**。 +PWA（Progressive Web App，渐进式 Web 应用）是一种使用 Web 技术构建的应用程序，但它能够提供接近原生应用的用户体验。你有没有想过：**一个网页，能不能像微信、抖音一样，直接安装在手机桌面上，点开就用，甚至断网也能跑？** 答案是：可以。这就是 PWA。 PWA 本质上还是一个网页，但它通过几项关键技术，让自己"进化"成了一个接近原生 App 的存在： @@ -25,9 +25,17 @@ PWA 本质上还是一个网页，但它通过几项关键技术，让自己"进 简单来说，PWA 就是 **"穿上了 App 外衣的网页"**。 - + -## 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，需要三样东西： @@ -43,9 +51,9 @@ PWA 必须运行在 HTTPS 协议下。这是浏览器的硬性要求——只有 这是 PWA 的"灵魂"。它是一段运行在浏览器后台的 JavaScript 代码，充当你的 App 和网络之间的"中间人"。它可以拦截网络请求、缓存资源，从而实现离线访问。你可以把它理解为一个 **"住在浏览器里的小管家"**，负责帮你存东西、取东西。 - + -## 1.3 为什么选择 PWA？ +## 1.4 为什么选择 PWA？ 在 Vibe Coding 时代，PWA 是性价比最高的"跨平台方案"之一： @@ -60,35 +68,94 @@ PWA 必须运行在 HTTPS 协议下。这是浏览器的硬性要求——只有 **一句话总结**：如果你的应用不需要调用摄像头的 AR 功能或蓝牙硬件，PWA 几乎是最省心的选择。 -## 1.4 本教程的路线图 +## 1.5 本教程的路线图 -我们将使用 **Vite + React + vite-plugin-pwa** 的技术栈，按以下步骤完成整个流程： +为了让整个学习过程不再枯燥，本教程将全程围绕一个既有趣又实用的案例—— **《番茄农场》** 展开。这是一个番茄钟种菜游戏，将专注工作与游戏化激励完美结合。我们将结合 AI 编程助手的 Vibe Coding 模式，把从零开始到手机安装的过程，拆解为一条你可以反复复用的路线： -1. **创建项目并配置 PWA**：用 Vite 创建 React 项目，安装并配置 vite-plugin-pwa -2. **本地体验 PWA**：构建生产版本，在电脑上安装并测试离线能力 -3. **部署上线**：部署到 Vercel 获得 HTTPS 地址 -4. **手机安装**：在 Android 和 iPhone 上安装并使用 +1. **建立认知与环境**：弄清楚 PWA 的形态，安装好 Node.js 和 AI 编程助手，确保工具链通畅。 +2. **搭建项目骨架**：创建一个可以在本地成功运行的 React + TypeScript 项目。 +3. **AI 迭代开发**：通过与 AI 的对话，从番茄钟倒计时开始，逐步实现种菜系统、等级系统、SVG 作物展示等功能。 +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`），说明安装成功。 + + + +## 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。 + + + +## 2.4 新建一个项目 + +打开你的 AI 编程助手，在对话框中输入以下 Prompt： ``` -请帮我创建一个 Vite + React + TypeScript 项目，项目名叫 my-pwa-app。 -要求： -1. 使用 npm create vite@latest 创建项目 -2. 选择 React 框架和 TypeScript 模板 -3. 创建完成后进入项目目录并安装依赖 -4. 额外安装 vite-plugin-pwa 插件：npm install vite-plugin-pwa -D +请帮我创建一个 React 项目，项目名叫 tomato-farm-pwa，用来做番茄农场应用。 +需要支持 TypeScript，并且加上 PWA 功能（就是能让网页安装到手机桌面的那种）。 +``` + +AI 会自动执行以下步骤： + +**第一步：创建项目** + +```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 执行完毕后，你的项目目录结构大致如下： ``` -my-pwa-app/ -├── public/ # 静态资源（图标放这里） +tomato-farm-pwa/ +├── public/ # 静态资源（图标、SVG 素材放这里） ├── src/ │ ├── App.tsx # 主组件 │ ├── main.tsx # 入口文件 @@ -99,39 +166,49 @@ my-pwa-app/ └── 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 图片。 你可以让 AI 帮你生成： ``` -请帮我用 HTML Canvas 生成两个简单的 PWA 图标（192x192 和 512x512）， -背景色用渐变蓝色，中间写一个白色的字母 "P"。 -保存到 public/icon-192.png 和 public/icon-512.png。 +请帮我生成两个应用图标，尺寸分别是 192x192 和 512x512。 +背景用绿色渐变，中间画一个红色番茄，保存到 public 文件夹里。 ``` 或者你也可以用任何设计工具（Figma、Canva）做一个你喜欢的图标，放到 `public/` 目录下。 - + -## 2.3 配置 vite-plugin-pwa +## 2.7 配置 vite-plugin-pwa 这是最关键的一步。打开 `vite.config.ts`，让 AI 帮你配置 PWA 插件： ``` -请帮我修改 vite.config.ts，添加 vite-plugin-pwa 的配置。要求： -1. 引入 VitePWA 插件 -2. 注册类型设为 autoUpdate（自动更新） -3. 配置 manifest： - - name: "My PWA App" - - 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 文件 +请帮我把 vite.config.ts 改成 PWA 配置，让网页可以安装到手机桌面： +- 应用名称叫"番茄农场"，主题是绿色 +- 使用 public 目录下的 icon-192.png 和 icon-512.png 作为图标 +- 开启自动更新 +- 缓存所有 js、css、html 和图片文件，让应用可以离线使用 ``` AI 会帮你生成类似这样的配置： @@ -147,10 +224,10 @@ export default defineConfig({ VitePWA({ registerType: 'autoUpdate', manifest: { - name: 'My PWA App', - short_name: 'MyPWA', - description: '一个示例 PWA 应用', - theme_color: '#4285f4', + name: '番茄农场', + short_name: '番茄农场', + description: '专注种菜，收获成长', + theme_color: '#4CAF50', background_color: '#ffffff', display: 'standalone', icons: [ @@ -180,28 +257,156 @@ export default defineConfig({ * `display: 'standalone'`：安装后以独立窗口运行，没有浏览器地址栏，看起来像原生 App。 * `workbox.globPatterns`：告诉 Service Worker 要缓存哪些类型的文件，这些文件在离线时也能访问。 - + -## 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 持久化存储 -4. 界面风格简洁现代，使用蓝色主题色 #4285f4 -5. 适配移动端（响应式布局） +请帮我写番茄农场应用的主页面，包含以下功能： + +**番茄钟功能：** +- 一个 25 分钟的倒计时器，可以开始、暂停、重置 +- 显示剩余时间和进度条 +- 专注完成后给用户 10 个积分 + +**种菜功能：** +- 3 块菜地，最开始只有第 1 块能用，后面的要升级解锁 +- 商店里可以买菜籽：胡萝卜 5 积分、番茄 10 积分、玉米 15 积分 +- 买了种子种到地里，作物会慢慢长大，成熟后可以收获换积分 + +**等级系统：** +- 根据总积分升级：0-100 分是新手农民，100-300 分是熟练农民，300 分以上是农场大师 +- 升级后解锁新的菜地和更高级的种子 + +**界面设计：** +- 顶部显示等级、积分和升级进度条 +- 中间是番茄钟倒计时 +- 下面是菜地网格 +- 底部是商店按钮 +- 整体用绿色主题，看起来清新可爱 +- 要能适配手机屏幕 + +**数据保存：** +- 所有数据（积分、等级、菜地状态）都要保存下来，刷新页面不会丢失 ``` -这个 Todo 应用非常适合演示 PWA 的能力：即使断网，你依然可以添加和管理待办事项，因为数据存在本地，页面资源也被 Service Worker 缓存了。 +发送指令后，你会看到 AI 开始思考并分析你的项目结构。几秒钟后，它会直接生成 `App.tsx` 的完整代码。 - +1. 通过它的回答，我们可以看到它的思考逻辑、交互逻辑等等 +2. 我们可以直观的看到它对哪些代码进行了改写 +3. 如果我们对生成的效果不满意，我们可以回退到上一个版本 -# 第 3 章：本地体验 PWA + -## 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 应用雏形！ + + + +## 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 绘制和动画逻辑。修改完成后，刷新浏览器页面，你应该能看到精美的作物图案和流畅的生长动画。 + + + +## 3.4 添加音效和提示（可选） + +如果你想让番茄农场更加沉浸，可以添加音效和提示功能。这同样只需要一个简单的 Prompt： + +``` +请帮番茄农场加上音效和提示： + +**音效：** +- 开始专注时播放"叮"的一声 +- 专注完成时播放胜利音效 +- 种植和收获时也要有对应的音效 + +**提示：** +- 专注完成后弹出"恭喜你完成专注！" +- 升级时显示"恭喜升级到 XX 级！" +- 解锁新菜地时提示"解锁了新菜地！" + +可以用简单的音频文件或者 Web Audio API 来实现 +``` + +AI 会帮你添加音效和提示功能，让你的番茄农场更加生动有趣。 + + + +# 4 本地体验 PWA + +## 4.1 构建并预览 PWA 的 Service Worker 只在生产构建中生效（开发模式下不会注册）。所以我们需要先构建，再预览： @@ -215,7 +420,7 @@ PWA 的 Service Worker 只在生产构建中生效（开发模式下不会注册 预览服务器启动后，打开浏览器访问提示的地址（通常是 `http://localhost:4173`）。 -## 3.2 在电脑上安装 PWA +## 4.2 在电脑上安装 PWA 打开预览地址后，你会注意到浏览器地址栏右侧出现了一个 **安装图标**（一个小小的下载箭头或 "+" 号）。 @@ -225,9 +430,9 @@ PWA 的 Service Worker 只在生产构建中生效（开发模式下不会注册 2. 在弹出的对话框中点击 **"安装"** 3. PWA 会以独立窗口打开，同时在你的桌面/开始菜单/Dock 中创建快捷方式 -安装后的 PWA 看起来就像一个原生桌面应用——没有地址栏，没有标签页，有自己的窗口和图标。 +安装后的 PWA 看起来就像一个原生桌面应用——没有地址栏，没有标签页，有自己的窗口和图标。现在你可以随时打开番茄农场，开始专注种菜之旅！ - + **macOS Safari 安装步骤：** @@ -235,129 +440,132 @@ PWA 的 Service Worker 只在生产构建中生效（开发模式下不会注册 2. 点击菜单栏的 **文件 → 添加到程序坞** 3. PWA 图标会出现在 Dock 中 -## 3.3 测试离线能力 +## 4.3 测试离线能力 这是 PWA 最酷的部分。让我们验证一下离线是否真的能用： 1. 确保 PWA 已经在浏览器中打开过一次（让 Service Worker 缓存资源） 2. **断开网络**（关闭 Wi-Fi 或拔掉网线） -3. 刷新页面——你会发现 **App 依然正常加载！** -4. 添加几个待办事项——数据正常保存在 localStorage 中 +3. 刷新页面——你会发现 **番茄农场 App 依然正常加载！** +4. 开始一个番茄钟——专注完成后获得积分，购买种子种植——所有数据正常保存在 localStorage 中 你也可以打开 Chrome DevTools（F12）→ Application → Service Workers，查看 Service Worker 的运行状态和缓存的资源列表。 - + -# 第 4 章：部署上线 +# 5 部署上线 PWA 必须运行在 HTTPS 上才能正常工作。好消息是，现在主流的部署平台都自动提供免费的 HTTPS。我们以 **Vercel** 为例（也可以用 Netlify 或 GitHub Pages）。 -## 4.1 部署到 Vercel +## 5.1 部署到 Vercel -**第一步：安装 Vercel CLI** +**第一步：安装部署工具** ``` -请帮我全局安装 Vercel CLI：npm install -g vercel +请帮我安装 Vercel 的部署工具 ``` -**第二步：部署** - -在项目根目录下执行： +**第二步：部署项目** ``` -请帮我执行 vercel 命令部署项目。 -当提示 "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，项目名叫 tomato-farm-pwa ``` -等待几十秒，Vercel 会自动构建并部署你的项目。完成后，你会得到一个类似 `https://my-pwa-app.vercel.app` 的 HTTPS 地址。 +AI 会自动处理所有部署步骤，你只需要在提示时： +- 选择你的账号 +- 确认创建新项目 +- 其他按默认选项即可 - +等待几十秒，Vercel 会自动构建并部署你的项目。完成后，你会得到一个类似 `https://tomato-farm-pwa.vercel.app` 的 HTTPS 地址。 + + **第三步：验证 PWA** 在浏览器中打开部署后的地址，你应该能看到： 1. 地址栏右侧出现安装图标 -2. 打开 DevTools → Application → Manifest，能看到你配置的 App 信息 +2. 打开 DevTools → Application → Manifest，能看到你配置的 App 信息（名称为"番茄农场"） 3. Service Workers 标签下显示 Service Worker 已激活 -## 4.2 使用 GitHub Pages 部署（替代方案） +## 5.2 使用 GitHub Pages 部署（替代方案） -如果你更喜欢 GitHub Pages，需要额外配置 `base` 路径： +如果你更喜欢 GitHub Pages，需要额外配置路径： ``` -请帮我修改 vite.config.ts，添加 base 配置： -base: '/my-pwa-app/'（替换为你的 GitHub 仓库名） -同时更新 manifest 中的 icon 路径，加上 base 前缀。 +请帮我修改配置，让项目能部署到 GitHub Pages。 +我的仓库名是 tomato-farm-pwa，需要相应调整路径配置。 ``` 然后将构建产物推送到 GitHub 仓库的 `gh-pages` 分支即可。 -# 第 5 章：在手机上安装 PWA +# 6 在手机上安装 PWA -这是最激动人心的部分——让你的网页变成手机上的"App"。 +这是最激动人心的部分——让你的番茄农场网页变成手机上的"App"。 -## 5.1 Android 手机安装 +## 6.1 Android 手机安装 -1. 在手机的 **Chrome 浏览器** 中打开你部署好的 PWA 地址 +1. 在手机的 **Chrome 浏览器** 中打开你部署好的番茄农场 PWA 地址 2. Chrome 可能会自动弹出 **"添加到主屏幕"** 的横幅提示，直接点击即可 3. 如果没有自动弹出，点击右上角的 **三个点菜单 → "安装应用"** 或 **"添加到主屏幕"** -4. 确认安装后，你的手机桌面上就会出现 App 图标 +4. 确认安装后，你的手机桌面上就会出现番茄农场 App 图标 -打开它，你会发现它以全屏模式运行，没有浏览器的地址栏和导航按钮，和原生 App 几乎一模一样。 +打开它，你会发现它以全屏模式运行，没有浏览器的地址栏和导航按钮，和原生 App 几乎一模一样。现在你可以随时随地开始专注种菜了！ - + -## 5.2 iPhone 安装 +## 6.2 iPhone 安装 iOS 上安装 PWA 只能通过 **Safari** 浏览器（其他浏览器不支持）： -1. 在 **Safari** 中打开你的 PWA 地址 +1. 在 **Safari** 中打开你的番茄农场 PWA 地址 2. 点击底部的 **分享按钮**（方框加向上箭头的图标） 3. 在弹出的菜单中选择 **"添加到主屏幕"** 4. 给 App 起个名字，点击 **"添加"** 从 iOS 26 开始，所有添加到主屏幕的网站都会默认以独立 App 模式打开，这是一个重大改进。 - + > **iOS 的已知限制**： > * 推送通知需要 iOS 16.4 以上，且必须先将 PWA 添加到主屏幕 > * 不支持后台同步（Background Sync） > * 存储空间比 Android 更受限 -## 5.3 用 Lighthouse 审计你的 PWA +## 6.3 用 Lighthouse 审计你的 PWA Google 提供了一个叫 **Lighthouse** 的工具，可以给你的 PWA 打分。打开 Chrome DevTools（F12）→ Lighthouse 标签 → 勾选 "Progressive Web App" → 点击 "Analyze page load"。 -一个合格的 PWA 应该在 PWA 评分上拿到满分。如果有扣分项，Lighthouse 会告诉你具体原因和修复建议。 +一个合格的番茄农场 PWA 应该在 PWA 评分上拿到满分。如果有扣分项，Lighthouse 会告诉你具体原因和修复建议。 - + -# 第 6 章：写在最后 +# 7 写在最后 -恭喜你！你已经成功构建了一个可以安装在电脑和手机上的 PWA 应用。回顾一下我们做了什么： +恭喜你！你已经成功构建了一个可以安装在电脑和手机上的番茄钟种菜 PWA 应用。回顾一下我们做了什么： -1. 用 Vite + React 创建了一个 Web 应用 +1. 用 Vite + React 创建了一个番茄农场 Web 应用 2. 通过 vite-plugin-pwa 添加了 Service Worker 和 Manifest 3. 部署到 Vercel 获得了 HTTPS 地址 4. 在电脑和手机上都成功安装并体验了离线能力 +现在你的番茄农场 PWA 已经可以实现： +* **专注种菜**：通过番茄钟机制帮助用户专注学习或工作 +* **游戏化激励**：通过种菜、升级、解锁新内容来激励持续使用 +* **离线可用**：即使没有网络也能继续专注、种菜、管理自己的农场 +* **跨平台安装**：一次开发，可以在各种设备上安装使用 + PWA 的魅力在于它的"渐进式"——你不需要一开始就做到完美。先让你的网页能被安装、能离线访问，然后再逐步添加推送通知、后台同步等高级功能。 **进阶方向：** -* **推送通知**：使用 Push API + Notification API，让你的 App 能像微信一样发送消息提醒 -* **后台同步**：使用 Background Sync API，在网络恢复时自动同步离线期间的操作 +* **推送通知**：使用 Push API + Notification API，在番茄钟结束时提醒用户休息，或在作物成熟时通知收获 +* **后台同步**：使用 Background Sync API，在网络恢复时同步用户的农场数据到云端 * **更智能的缓存策略**：根据不同类型的资源使用不同的 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 的力量。专注种菜，收获成长！*** # 参考文献