如何开发 PWA 本地应用——让网页变成"真正的 App"

1 什么是 PWA 和 PWA 开发

在这篇教程中，我们将完整跑通一条闭环：从一个普通的网页项目，到一个可以安装在电脑桌面和手机主屏幕上、断网也能正常使用的"真正的 App"。 你会亲手把一个 React 应用变成 PWA，部署上线后在手机上安装体验。

我们将要开发的是一个 番茄农场（Tomato Farm） 应用——一个将番茄钟工作法与种菜游戏完美结合的 PWA 应用。通过 25 分钟的专注时间获得积分，用积分购买种子种植作物，随着等级提升解锁更多菜地和高级种子。最重要的是，即使断网也能正常使用，所有数据都保存在本地。

本次教程，你至少需要具备：

• 一台电脑（Windows 或 Mac 均可）
• Node.js 环境（18.0 以上版本）
• 你的 AI 编程助手（Cursor / Trae / Claude Code 等）
• 一个手机（用于体验移动端安装）

1.1 PWA 的定义

PWA（Progressive Web App，渐进式 Web 应用）是一种使用 Web 技术构建的应用程序，但它能够提供接近原生应用的用户体验。你有没有想过：一个网页，能不能像微信、抖音一样，直接安装在手机桌面上，点开就用，甚至断网也能跑？ 答案是：可以。这就是 PWA。

PWA 本质上还是一个网页，但它通过几项关键技术，让自己"进化"成了一个接近原生 App 的存在：

• 可安装：用户可以把它"安装"到桌面/主屏幕，拥有自己的图标和启动画面，打开后没有浏览器的地址栏，看起来就像一个独立的 App。
• 可离线：即使没有网络，App 也能正常打开并展示缓存过的内容。
• 可推送：像原生 App 一样发送通知提醒。

简单来说，PWA 就是 "穿上了 App 外衣的网页"。

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，需要三样东西：

1. HTTPS（安全连接）

PWA 必须运行在 HTTPS 协议下。这是浏览器的硬性要求——只有安全的网站才有资格使用 Service Worker 等高级功能。好消息是，现在主流的部署平台（Vercel、Netlify、GitHub Pages）都自动提供免费的 HTTPS。

2. Web App Manifest（应用清单）

这是一个 JSON 配置文件，告诉浏览器："我是一个 App，我叫什么名字、用什么图标、打开后长什么样"。它决定了你的 PWA 安装后的外观和行为。

3. Service Worker（服务工作线程）

这是 PWA 的"灵魂"。它是一段运行在浏览器后台的 JavaScript 代码，充当你的 App 和网络之间的"中间人"。它可以拦截网络请求、缓存资源，从而实现离线访问。你可以把它理解为一个 "住在浏览器里的小管家"，负责帮你存东西、取东西。

1.4 为什么选择 PWA？

在 Vibe Coding 时代，PWA 是性价比最高的"跨平台方案"之一：

对比维度	原生 App	PWA
开发成本	需要分别开发 iOS / Android / 桌面端	一套代码，全平台通用
安装方式	需要去应用商店下载	浏览器里直接安装，秒装
更新方式	用户需要手动更新	自动更新，用户无感
体积大小	动辄几十 MB	通常只有几百 KB
离线能力	天然支持	通过 Service Worker 支持
适用场景	需要深度硬件访问（AR/蓝牙等）	内容展示、工具类、轻量应用

一句话总结：如果你的应用不需要调用摄像头的 AR 功能或蓝牙硬件，PWA 几乎是最省心的选择。

1.5 本教程的路线图

为了让整个学习过程不再枯燥，本教程将全程围绕一个既有趣又实用的案例—— 《番茄农场》 展开。这是一个番茄钟种菜游戏，将专注工作与游戏化激励完美结合。我们将结合 AI 编程助手的 Vibe Coding 模式，把从零开始到手机安装的过程，拆解为一条你可以反复复用的路线：

1. 建立认知与环境：弄清楚 PWA 的形态，安装好 Node.js 和 AI 编程助手，确保工具链通畅。
2. 搭建项目骨架：创建一个可以在本地成功运行的 React + TypeScript 项目。
3. AI 迭代开发：通过与 AI 的对话，从番茄钟倒计时开始，逐步实现种菜系统、等级系统、SVG 作物展示等功能。
4. PWA 配置与离线测试：添加 Service Worker 和 Manifest，测试离线能力。
5. 部署与手机安装：部署到 Vercel 获得 HTTPS 地址，在手机上安装并使用。

这一节只负责把全景图画出来，不展开具体命令。现在只需要记住这条主线： 环境准备 → 骨架搭建 → AI 描述与生成 → PWA 配置 → 部署交付 。接下来的章节，我们会手把手带你走完每一步。

2 开发环境搭建

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，下载 LTS（长期支持）版本（本教程基于 Node.js 18.x 以上版本编写）。

下载完成后，像安装普通软件一样双击运行，保持默认选项一路"Next"即可完成安装。

安装完成后，打开终端（Windows 用户打开 CMD 或 PowerShell，Mac 用户打开 Terminal），输入以下命令验证安装是否成功：

node --version
npm --version

如果能看到版本号输出（如 v18.17.0 和 9.6.7），说明安装成功。

2.3 AI 编程助手安装

AI 编程助手是我们进行 Vibe Coding 的主战场。你可以把它简单理解为一个 "内置了超级 AI 的代码编辑器"。

推荐选择：

• Trae：访问官网 https://www.trae.cn，根据你的电脑系统下载对应版本
• Cursor：访问官网 https://cursor.sh，下载安装
• Claude Code：如果你已经在使用 Claude，可以直接使用 Claude Code 功能

安装过程非常简单，和安装普通软件一样，双击安装包并按提示点击"下一步"即可完成。准备好这个工具后，在接下来的实战中，我们就不需要面对枯燥的代码框发呆了，而是直接在这里打开项目，通过对话框用自然语言指挥 AI 帮我们写代码、改 Bug。

2.4 新建一个项目

打开你的 AI 编程助手，在对话框中输入以下 Prompt：

请帮我创建一个 React 项目，项目名叫 tomato-farm-pwa，用来做番茄农场应用。
需要支持 TypeScript，并且加上 PWA 功能（就是能让网页安装到手机桌面的那种）。

AI 会自动执行以下步骤：

第一步：创建项目

npm create vite@latest tomato-farm-pwa -- --template react-ts

第二步：进入项目并安装依赖

cd tomato-farm-pwa
npm install

第三步：安装 PWA 插件

npm install vite-plugin-pwa -D

等 AI 执行完毕后，你的项目目录结构大致如下：

tomato-farm-pwa/
├── public/              # 静态资源（图标、SVG 素材放这里）
├── src/
│   ├── App.tsx          # 主组件
│   ├── main.tsx         # 入口文件
│   └── App.css          # 样式
├── index.html           # HTML 入口
├── vite.config.ts       # Vite 配置（PWA 配置写在这里）
├── package.json
└── tsconfig.json

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 帮你生成：

请帮我生成两个应用图标，尺寸分别是 192x192 和 512x512。
背景用绿色渐变，中间画一个红色番茄，保存到 public 文件夹里。

或者你也可以用任何设计工具（Figma、Canva）做一个你喜欢的图标，放到 public/ 目录下。

2.7 配置 vite-plugin-pwa

这是最关键的一步。打开 vite.config.ts，让 AI 帮你配置 PWA 插件：

请帮我把 vite.config.ts 改成 PWA 配置，让网页可以安装到手机桌面：
- 应用名称叫"番茄农场"，主题是绿色
- 使用 public 目录下的 icon-192.png 和 icon-512.png 作为图标
- 开启自动更新
- 缓存所有 js、css、html 和图片文件，让应用可以离线使用

AI 会帮你生成类似这样的配置：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'autoUpdate',
      manifest: {
        name: '番茄农场',
        short_name: '番茄农场',
        description: '专注种菜，收获成长',
        theme_color: '#4CAF50',
        background_color: '#ffffff',
        display: 'standalone',
        icons: [
          {
            src: '/icon-192.png',
            sizes: '192x192',
            type: 'image/png'
          },
          {
            src: '/icon-512.png',
            sizes: '512x512',
            type: 'image/png'
          }
        ]
      },
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg}']
      }
    })
  ]
})

关键配置解读：

• registerType: 'autoUpdate'：当你发布新版本时，用户下次打开 App 会自动更新，无需手动操作。
• display: 'standalone'：安装后以独立窗口运行，没有浏览器地址栏，看起来像原生 App。
• workbox.globPatterns：告诉 Service Worker 要缓存哪些类型的文件，这些文件在离线时也能访问。

3 番茄农场 PWA 开发

在前两章，我们已经搞清楚了 PWA 是什么，并把开发环境搭建完毕。从这一节开始，我们不再纸上谈兵，而是正式进入实战环节。我们将采用 Vibe Coding 模式，从零打造一款既有趣又实用的应用—— "番茄农场" (Tomato Farm) 。它不仅将番茄钟工作法与游戏化激励完美结合，而且涵盖了 PWA 开发的核心要素：UI 交互（番茄钟）、数据存储（积分和作物）、离线能力（Service Worker 缓存）。

接下来，请跟随我的节奏，向 AI 发出第一道指令。

3.1 第一次"总指令"：从零到一

在 Vibe Coding 模式下，我们不需要像传统开发那样先创建布局文件、再写逻辑代码。我们要做的，是 一次性把需求描述清楚，让 AI 帮我们生成第一版可运行的雏形。

在 AI 编程助手中打开我们刚才创建的项目目录，在对话框中输入下面这段 Prompt：

请帮我写番茄农场应用的主页面，包含以下功能：

**番茄钟功能：**
- 一个 25 分钟的倒计时器，可以开始、暂停、重置
- 显示剩余时间和进度条
- 专注完成后给用户 10 个积分

**种菜功能：**
- 3 块菜地，最开始只有第 1 块能用，后面的要升级解锁
- 商店里可以买菜籽：胡萝卜 5 积分、番茄 10 积分、玉米 15 积分
- 买了种子种到地里，作物会慢慢长大，成熟后可以收获换积分

**等级系统：**
- 根据总积分升级：0-100 分是新手农民，100-300 分是熟练农民，300 分以上是农场大师
- 升级后解锁新的菜地和更高级的种子

**界面设计：**
- 顶部显示等级、积分和升级进度条
- 中间是番茄钟倒计时
- 下面是菜地网格
- 底部是商店按钮
- 整体用绿色主题，看起来清新可爱
- 要能适配手机屏幕

**数据保存：**
- 所有数据（积分、等级、菜地状态）都要保存下来，刷新页面不会丢失

发送指令后，你会看到 AI 开始思考并分析你的项目结构。几秒钟后，它会直接生成 App.tsx 的完整代码。

1. 通过它的回答，我们可以看到它的思考逻辑、交互逻辑等等
2. 我们可以直观的看到它对哪些代码进行了改写
3. 如果我们对生成的效果不满意，我们可以回退到上一个版本

3.2 运行与查看（本地开发服务器）

此时 AI 已经完成了第一轮开发，但请记住，在 AI 编程助手中我们看到的只是一堆代码"图纸"，而非可以点击交互的真实应用。我们需要启动本地开发服务器，让我们能立刻把刚才的代码运行起来，查看到真实的运行效果。

在 AI 编程助手的终端中执行：

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 只在生产构建中生效（开发模式下不会注册）。所以我们需要先构建，再预览：

请帮我执行以下命令：
1. npm run build（构建生产版本）
2. npm run preview（启动本地预览服务器）

构建完成后，Vite 会在 dist/ 目录下生成所有文件，包括自动生成的 sw.js（Service Worker）和 manifest.webmanifest。

预览服务器启动后，打开浏览器访问提示的地址（通常是 http://localhost:4173）。

4.2 在电脑上安装 PWA

打开预览地址后，你会注意到浏览器地址栏右侧出现了一个 安装图标（一个小小的下载箭头或 "+" 号）。

Chrome / Edge 安装步骤：

1. 点击地址栏右侧的安装图标
2. 在弹出的对话框中点击 "安装"
3. PWA 会以独立窗口打开，同时在你的桌面/开始菜单/Dock 中创建快捷方式

安装后的 PWA 看起来就像一个原生桌面应用——没有地址栏，没有标签页，有自己的窗口和图标。现在你可以随时打开番茄农场，开始专注种菜之旅！

macOS Safari 安装步骤：

1. 在 Safari 中打开 PWA 地址
2. 点击菜单栏的 文件 → 添加到程序坞
3. PWA 图标会出现在 Dock 中

4.3 测试离线能力

这是 PWA 最酷的部分。让我们验证一下离线是否真的能用：

1. 确保 PWA 已经在浏览器中打开过一次（让 Service Worker 缓存资源）
2. 断开网络（关闭 Wi-Fi 或拔掉网线）
3. 刷新页面——你会发现 番茄农场 App 依然正常加载！
4. 开始一个番茄钟——专注完成后获得积分，购买种子种植——所有数据正常保存在 localStorage 中

你也可以打开 Chrome DevTools（F12）→ Application → Service Workers，查看 Service Worker 的运行状态和缓存的资源列表。

5 部署上线

PWA 必须运行在 HTTPS 上才能正常工作。好消息是，现在主流的部署平台都自动提供免费的 HTTPS。我们以 Vercel 为例（也可以用 Netlify 或 GitHub Pages）。

5.1 部署到 Vercel

第一步：安装部署工具

请帮我安装 Vercel 的部署工具

第二步：部署项目

请帮我部署项目到 Vercel，项目名叫 tomato-farm-pwa

AI 会自动处理所有部署步骤，你只需要在提示时：

• 选择你的账号
• 确认创建新项目
• 其他按默认选项即可

等待几十秒，Vercel 会自动构建并部署你的项目。完成后，你会得到一个类似 https://tomato-farm-pwa.vercel.app 的 HTTPS 地址。

第三步：验证 PWA

在浏览器中打开部署后的地址，你应该能看到：

1. 地址栏右侧出现安装图标
2. 打开 DevTools → Application → Manifest，能看到你配置的 App 信息（名称为"番茄农场"）
3. Service Workers 标签下显示 Service Worker 已激活

5.2 使用 GitHub Pages 部署（替代方案）

如果你更喜欢 GitHub Pages，需要额外配置路径：

请帮我修改配置，让项目能部署到 GitHub Pages。
我的仓库名是 tomato-farm-pwa，需要相应调整路径配置。

然后将构建产物推送到 GitHub 仓库的 gh-pages 分支即可。

6 在手机上安装 PWA

这是最激动人心的部分——让你的番茄农场网页变成手机上的"App"。

6.1 Android 手机安装

1. 在手机的 Chrome 浏览器 中打开你部署好的番茄农场 PWA 地址
2. Chrome 可能会自动弹出 "添加到主屏幕" 的横幅提示，直接点击即可
3. 如果没有自动弹出，点击右上角的 三个点菜单 → "安装应用" 或 "添加到主屏幕"
4. 确认安装后，你的手机桌面上就会出现番茄农场 App 图标

打开它，你会发现它以全屏模式运行，没有浏览器的地址栏和导航按钮，和原生 App 几乎一模一样。现在你可以随时随地开始专注种菜了！

6.2 iPhone 安装

iOS 上安装 PWA 只能通过 Safari 浏览器（其他浏览器不支持）：

1. 在 Safari 中打开你的番茄农场 PWA 地址
2. 点击底部的 分享按钮（方框加向上箭头的图标）
3. 在弹出的菜单中选择 "添加到主屏幕"
4. 给 App 起个名字，点击 "添加"

从 iOS 26 开始，所有添加到主屏幕的网站都会默认以独立 App 模式打开，这是一个重大改进。

iOS 的已知限制：

• 推送通知需要 iOS 16.4 以上，且必须先将 PWA 添加到主屏幕
• 不支持后台同步（Background Sync）
• 存储空间比 Android 更受限

6.3 用 Lighthouse 审计你的 PWA

Google 提供了一个叫 Lighthouse 的工具，可以给你的 PWA 打分。打开 Chrome DevTools（F12）→ Lighthouse 标签 → 勾选 "Progressive Web App" → 点击 "Analyze page load"。

一个合格的番茄农场 PWA 应该在 PWA 评分上拿到满分。如果有扣分项，Lighthouse 会告诉你具体原因和修复建议。

7 写在最后

恭喜你！你已经成功构建了一个可以安装在电脑和手机上的番茄钟种菜 PWA 应用。回顾一下我们做了什么：

1. 用 Vite + React 创建了一个番茄农场 Web 应用
2. 通过 vite-plugin-pwa 添加了 Service Worker 和 Manifest
3. 部署到 Vercel 获得了 HTTPS 地址
4. 在电脑和手机上都成功安装并体验了离线能力

现在你的番茄农场 PWA 已经可以实现：

• 专注种菜：通过番茄钟机制帮助用户专注学习或工作
• 游戏化激励：通过种菜、升级、解锁新内容来激励持续使用
• 离线可用：即使没有网络也能继续专注、种菜、管理自己的农场
• 跨平台安装：一次开发，可以在各种设备上安装使用

PWA 的魅力在于它的"渐进式"——你不需要一开始就做到完美。先让你的网页能被安装、能离线访问，然后再逐步添加推送通知、后台同步等高级功能。

进阶方向：

• 推送通知：使用 Push API + Notification API，在番茄钟结束时提醒用户休息，或在作物成熟时通知收获
• 后台同步：使用 Background Sync API，在网络恢复时同步用户的农场数据到云端
• 更智能的缓存策略：根据不同类型的资源使用不同的 Workbox 缓存策略（CacheFirst、NetworkFirst、StaleWhileRevalidate）
• 发布到应用商店：使用 PWA Builder 可以将番茄农场 PWA 打包成 Android APK 或 Microsoft Store 应用
• 社交功能：增加好友系统，让用户可以互相访问农场、交换作物等

一套代码，全平台通用——这就是 PWA 的力量。专注种菜，收获成长！

参考文献

• Vite PWA 官方文档
• Google PWA 开发指南
• MDN Web App Manifest 文档
• Workbox 缓存策略详解
• PWA Builder - 将 PWA 发布到应用商店