产品教程

PWA 真机实时预览工具使用教程

ROIBest发布于 2026年8月20日 · 分类产品教程

调页面样式的时候，最耗时间的往往不是改代码，而是「改完之后怎么在手机上看到」。打包、上传、在手机上重新安装，一轮下来几分钟就过去了，而你可能只是想把一个按钮往上挪 8 像素。

PWA Preview 就是为了砍掉这一轮而做的一个 Android 小工具。它把你电脑上正在跑的开发服务器（dev server）直接搬到手机屏幕上：电脑里改一行 CSS 保存，手机上的画面立刻跟着变，不需要打包，也不需要重新安装。

它适合谁

前端开发：在真机上确认布局、字号、点击区域、安全区适配，配合 Vite / webpack 的热更新（HMR）实时看效果。
产品和设计：不用等开发出包，就能在自己手机上看当前正在做的页面长什么样。
测试：快速验证不同显示模式、屏幕方向下的表现。

一、下载安装

用手机扫下面的二维码，或者直接在手机浏览器里打开链接下载安装包：

点此下载安装包

这个链接长期有效，永远指向最新版本，不用每次换地址；下载下来的文件名会自动带上版本号（例如 roibest-pwa-preview-1.0.0.apk），所以你能一眼看出手里这个包是哪一版。需要在电脑上复制完整地址或自己生成二维码时用它：

https://storage.sitepower.com/apps/pwa-preview/latest/roibest-pwa-preview.apk

当前最新版是 1.0.0。如果要固定到某个具体版本（比如复现问题时），用带版本号的地址：roibest-pwa-preview-1.0.0.apk。

安装时的注意事项：

这是 Android 应用，iPhone 用不了。
安装包不是从应用商店下载的，Android 会弹出「禁止安装未知来源应用」之类的提示。按提示进入设置，给你使用的浏览器或文件管理器打开「允许安装未知应用」，再回来继续安装即可。
后续升级直接下载新包覆盖安装，不用先卸载，本地保存的连接记录和预览配置都会保留。

二、连接方式一：同一个 Wi-Fi（推荐）

这是最常用的方式，不需要数据线。

第一步：让开发服务器对局域网开放。

开发服务器默认只监听 127.0.0.1，也就是只有电脑自己能访问，手机是连不上的。启动时要加参数让它监听所有网卡：

# Vite
pnpm dev -- --host 0.0.0.0

# webpack-dev-server
npx webpack serve --host 0.0.0.0

# Next.js
next dev -H 0.0.0.0

Vite 也可以在 vite.config 里写 server.host = true，效果一样。

第二步：记下终端打印的 Network 地址。

加上 --host 之后，终端会多打印一行 Network 地址，形如 http://192.168.1.23:5173。这个才是手机要用的地址。

不要用 localhost 或 127.0.0.1——手机上的 127.0.0.1 指的是手机自己，不是你的电脑。

第三步：手机连同一个 Wi-Fi，打开 App 输入地址，点「连接」。

连过一次的地址会存在首页的「最近连接」里，一共保留 5 条，下次点一下就能进去，不用重新输。

三、连接方式二：USB 数据线（进阶）

如果公司 Wi-Fi 开了客户端隔离（手机和电脑互相看不到）、或者你需要 localhost 这种「可信上下文」环境来调试 Service Worker，就走 USB 这条路：手机开启 USB 调试并用数据线连上电脑，执行一条端口转发命令，然后在 App 里连本机地址。

adb reverse tcp:5173 tcp:5173

转发建好后，在 App 里填 http://localhost:5173 即可。这条通道走 USB，不受 Wi-Fi 隔离、防火墙和 VPN 影响，在管控严格的办公网络里往往比局域网更省事。

四、扫码直连：不用手打地址

IP 地址又长又容易输错，更快的办法是在电脑上把地址生成二维码，手机扫一下直接连上：

npx qrcode-terminal "pwapreview://connect?url=http%3A%2F%2F192.168.1.23%3A5173"

终端里会直接画出二维码，用手机自带的相机对准扫一下，系统就会唤起 PWA Preview 并自动连接，不需要先打开 App。App 首页的「扫码连接」按钮也能扫，而且普通的 http 地址二维码和 pwapreview:// 链接二维码它都认。

链接里除了必填的 url，还可以顺带带上预览配置，扫码时一并生效并记住：

参数	取值
`url`	开发服务器地址，需要 URL 编码
`display`	`standalone` / `fullscreen`
`bg`	背景色，如 `%23ffffff`（即 `#ffffff`）
`statusbar`	`dark` / `light`
`orientation`	`auto` / `portrait` / `landscape`

五、预览配置：模拟安装后的显示效果

首页的「预览配置」按钮，以及预览页悬浮菜单里的同名入口，都能打开配置面板。四项配置对应 PWA manifest 里的常见字段：

显示模式：standalone 保留系统状态栏，fullscreen 隐藏所有系统栏、从屏幕顶部下滑可临时唤出，用来看沉浸式效果。
状态栏图标：切换深色或浅色图标，对应你在 theme_color 上的明暗选择，用来确认状态栏文字在你的页面顶部背景上看不看得清。
屏幕方向：跟随系统 / 强制竖屏 / 强制横屏，对应 orientation。
背景色：对应 background_color，填 #ffffff 这样的十六进制色值，留空则跟随系统主题。它同时决定页面首帧渲染前的底色和加载指示的背景，和真实安装后的观感一致。

配置改完立即生效，并且按地址分别保存——同一个项目下次再连自动带出上次的设置；没有填地址时改的是全局默认值，之后新连的地址会套用这套。

六、预览页的悬浮菜单

进入预览后，屏幕右下角有一个半透明的小圆球，可以拖动到不挡内容的位置。点开是一组常用操作：

显示当前正在预览的地址
重新加载
打开预览配置
清除站点数据并重载（清掉缓存、localStorage / IndexedDB 和 Cookie，用来验证「首次访问」的效果）
用系统浏览器打开当前地址
断开连接，返回首页

手机的系统返回键也可以用：页面能后退就后退，退到头再按就回到连接页。

页面整页跳转时会显示居中的加载提示和目标地址；热更新只是局部刷新，不会打断你看画面。

七、连不上怎么排查

连接失败时 App 会直接显示一张诊断页，按下面的顺序查，绝大多数问题都在前两条：

手机和电脑是不是同一个 Wi-Fi。 公司访客网络、手机热点常常开着客户端隔离，设备之间互相访问不了。
开发服务器是不是真的加了 --host。看终端有没有打印出 Network 那一行，没有就是没生效。
电脑防火墙有没有放行。 macOS 在「系统设置 → 网络 → 防火墙」检查；Windows 在开发服务器首次启动时会弹窗，需要点「允许」。
电脑上的 VPN。 VPN 经常接管局域网路由，先关掉再试。
电脑 IP 变了。 换 Wi-Fi、重连网络之后地址会变，回终端重新看一眼当前的 Network 地址。

还有一条容易忽略的：地址只支持 http:// 和 https://，其中 http:// 明文只允许连局域网地址（192.168.x / 10.x / 172.16-31.x / 127.x / *.local）。想预览公网上的地址，请用 https。

八、使用边界：它不等于真实安装的 PWA

有一点要如实说明：PWA Preview 是一个布局与交互的调试壳，用来快速看样式和点击效果，它不是真实安装的 PWA。manifest 是否被浏览器正确识别、Service Worker 的安装与缓存行为、真实的安装流程和桌面图标表现，这些仍然要用手机浏览器的「添加到主屏幕」来做最终验收。

换句话说：日常改样式用它，能省下大量打包时间；上线前的功能验收，还是要回到浏览器里走一遍完整流程。

小结

把这套流程跑顺，日常的节奏就变成了：电脑上 pnpm dev -- --host 0.0.0.0，手机扫码连上，然后改代码、抬头看手机、再改。中间没有打包，也没有安装。

下载地址再放一次，长期有效：点此下载 PWA Preview 安装包