# Manifest start_url

> start_url 清单字段如何设置 PWA 从主屏幕或应用启动器启动时加载的入口页，以及如何为深度链接、数据分析与 scope 对齐做好设计。

**一句话：** `start_url` 是用户从主屏幕或系统启动器启动 PWA 时打开的 URL。它必须位于声明的 `scope` 之内，也是添加 UTM 参数或其他分析标记的合适位置，这样你就能在分析工具中将已安装应用的启动与普通浏览器访问区分开来。

## 语法

```json
{
  "start_url": "/app/?source=pwa",
  "scope": "/app/"
}
```

`start_url` 可以是相对 URL 或绝对 URL。相对值以清单文件的 URL 而非页面 URL 作为基准进行解析。

## Scope 约束

`start_url` **必须**位于 `scope` 之内。若不满足此条件，浏览器会回退到将包含清单的目录视为 scope——你显式声明的 `scope` 字段将被静默忽略。请始终验证这一约束：

| `scope` | 有效的 `start_url` | 无效的 `start_url` |
|---|---|---|
| `/app/` | `/app/`、`/app/dashboard` | `/`、`/blog/` |
| `/` | `/`、`/app/`、`/blog/` | `https://other.example.com/` |

## W3C 规范说明

- 当 `start_url` 缺失时，浏览器使用链接到清单的页面 URL。
- 规范要求 `start_url` 与清单同源。
- 浏览器在将 `start_url` 与 `scope` 进行比对前会先对其做规范化处理；末尾斜杠的差异可能造成影响。

## 分析追踪与 UTM 参数

由于 `start_url` 是启动入口，它是添加追踪参数的规范位置：

```json
{
  "start_url": "/app/?utm_source=homescreen&utm_medium=pwa"
}
```

这让你无需修改任何 JavaScript，即可在分析工具中将已安装应用会话与自然浏览器流量区分开来。

## 深度链接与 start_url

`start_url` 是**默认**入口，而非唯一入口。用户可以通过通知、分享目标、快捷方式等方式直接深度链接到任意域内 URL。深度链接 URL 优先于 `start_url`；你的应用必须能将任意域内路径作为合法入口来处理，而不能只针对 `start_url` 中的那一个。

## 实践清单

- [ ] `start_url` 与清单同源。
- [ ] `start_url` 是声明的 `scope` 的子路径。
- [ ] 已在 Android、iOS 与桌面端测试已安装应用的启动，确认加载了正确的页面。
- [ ] 若使用 UTM 参数，已确认分析工具在全新安装启动时能捕获到这些参数。
- [ ] 应用能将每个域内 URL 作为合法入口处理——而非只处理 `start_url`。