# Uni App Practical Sop

> uni-app 跨平台开发实战 SOP，覆盖项目搭建、配置权限、登录支付、推送定位、隐私合规、打包发布、排障验证等完整流程。当需要实现/排查 uni-app Vue3/Vite 功能、H5 与小程序构建、App 原生打包、manifest/pages 配置、定位权限、登录支付推送能力、隐私合规、DevTools 自动化或发布物料准备时使用。

- Skill: `oliverpanda/uni-app-practical-sop` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add oliverpanda/uni-app-practical-sop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oliverpanda/uni-app-practical-sop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: OliverPanda (https://skillmd.com/u/oliverpanda)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/oliverpanda/uni-app-practical-sop

---


# Uni-App 实战 SOP

## 一、使用说明

本 skill 是 uni-app 项目实战操作手册，沉淀了跨平台项目（微信小程序 + Android/iOS APP + H5）从开工准备到上线验收的全流程经验。

**使用原则：**

1. **先读本文** → 确定任务类型 → 按路由表加载对应 reference
2. 配合通用 `uni-app` skill 获取框架 API 细节
3. 所有改动前必须：确认目标子项目 → 确认目标平台 → 阅读最近 README.md 和 package.json → 检查真实调用链和当前配置
4. 优先使用项目中已集成的成熟方案（官方 uni-app API、DCloud 插件、现有本地 helper），不手写平台桥接层
5. 改动范围限定在相关层，运行最小验证命令

## 二、快速决策树

### 我要做 App 推送

```
任务类型？
├── 首次配置 UniPush 2.0 → references/UniPush2.0配置小白文档.md
├── 推送收不到，排查问题 → references/APP定位与UniPush2.0小白排查手册.md
├── 检查当前项目推送状态 → references/UniPush2.0整体跑通检查结论.md
├── 发包前权限检查 → references/APP定位与UniPush2.0权限配置检查清单.md
└── 理解底层架构/升级 → references/DCloud官方通知方案源码级说明.md
```

### 我要做微信小程序订阅消息

```
→ references/微信小程序订阅消息配置小白操作手册.md
```

### 我要做 App 后台定位

```
├── 排查定位问题 → references/APP定位与UniPush2.0小白排查手册.md
├── 发包前权限检查 → references/APP定位与UniPush2.0权限配置检查清单.md
```

### 我要发包/上架

```
├── 理解发布流程 → references/release-and-verification-sop.md
├── 权限配置检查 → references/APP定位与UniPush2.0权限配置检查清单.md
├── 了解需要准备的资料 → references/uni小程序+APP的全程经验案例分享.md
```

### 我遇到了某个具体 Bug

```
├── 常见陷阱速查 → references/pitfalls-and-debugging.md
└── 全链路排查思路 → references/uni小程序+APP的全程经验案例分享.md（第15节）
```

## 三、官方文档验证记录

> 以下发现基于 2026-07-19 对 uni-app/DCloud/HBuilder 官方文档的实际查阅。当 reference 内容与官方最新文档有出入时，以此处记录为准。

### 3.1 UniPush 2.0 厂商通道配置

| 项目 | references 中的说法 | 官方文档实际 | 处理建议 |
|------|-------------------|-------------|---------|
| 厂商参数存放位置 | references 提及 manifest.json 中厂商参数为空对象，视为风险 | **厂商推送参数在 DCloud 开发者中心 (dev.dcloud.net.cn) 配置**，不在 manifest.json 中。manifest.json 仅用于开启 Push 模块和选择 uni-push 版本 | manifest.json 的空对象 `hms: {}` 等是正常的占位，不应视为配置缺失。真正的厂商配置状态应去 DCloud 后台确认 |
| `offline` 字段 | 多处讨论 `offline: true` | 官方文档描述为勾选框（开启/关闭离线推送），勾选后会打包个推原生 SDK | 仅开启 `offline: true` 不意味着离线推送已跑通，这只是客户端的必要条件之一 |
| 荣耀 (Honor) 通道 | references 中列为需配置项 | uni-push 主文档中未列出 Honor 为独立厂商 | Honor 仍需在 DCloud 后台配置，但需确认当前官方支持状态 |
| 服务空间绑定 | references 未强调 | **UniPush 2.0 开通时必须绑定 uniCloud 服务空间**，即使后端不在 uniCloud | 必须在 uni-app 项目中创建 uniCloud 环境并绑定 |

### 3.2 uni-cloud-s2s 鉴权

| 项目 | references 中的说法 | 官方文档实际 | 处理建议 |
|------|-------------------|-------------|---------|
| hashMethod 可选值 | 提到 `hmac-sha256` 是推荐值 | 官方支持 4 种：`md5`, `sha1`, `sha256`, `hmac-sha256`。默认 `hmac-sha256` | references 中关于 "sha256 实际调用 md5" 的描述如属实，可能是特定已安装版本 (v1.0.1) 的 bug，官方文档未记录此问题。升级后需重新审计 |
| HMAC 签名串格式 | 未明确 | `hmac-sha256`：签名字符串 = `timestamp\npayloadStr`（不含 signKey 在签名串末尾）<br>hash 方法（md5/sha1/sha256）：签名字符串 = `timestamp\npayloadStr\nsignKey` | references 中 NestJS 侧实现应按此格式 |
| JSON 签名字段筛选 | 正确描述了"只纳入顶层基础类型" | 官方确认：仅 string/number/boolean 进入签名，对象和数组被排除 | ✓ 正确 |
| connectCode 模式 | references 未提及 | 官方还提供更简单的 `connectCode` 共享密钥模式，适合内网服务间调用 | 可考虑安全性要求不高的场景使用 |

### 3.3 客户端 Push API

| 项目 | references 中的说法 | 官方文档实际 | 处理建议 |
|------|-------------------|-------------|---------|
| `uni.createPushMessage` | 描述为"本地系统通知兜底" | 官方定义：**创建本地通知栏消息**。参数包括 title(可选)、content(必填)、payload、icon、sound、cover、delay、when、channelId、category | ✓ 用法正确，HBuilderX 3.5.2+ |
| `uni.getChannelManager` | references 未提及 | Android 8.0+ / HBuilderX 4.02+，可创建和管理通知渠道，**渠道一旦建立不可修改配置**（即使删除重建也无效） | 这是重要约束，应加入 references |
| `uni.setAppBadgeNumber` | 未覆盖 | **仅鸿蒙 (HarmonyOS)** 支持，iOS/Android 使用 `plus.runtime.setBadgeNumber` | - |
| `uni.offPushMessage` | 未覆盖 | 可移除推送消息监听，不传参数时移除所有监听器 | - |

### 3.4 登录 API

| 项目 | references 中的说法 | 官方文档实际 | 处理建议 |
|------|-------------------|-------------|---------|
| 支付宝 App 登录 | 使用第三方插件 `DHQ-AlipayAuth` | **官方 `uni.login` 不直接支持支付宝 App 登录**，需通过插件市场或 UTS 原生插件 | ✓ 使用插件的做法是正确的 |
| 微信 App 登录安全性 | references 未强调 | HBuilderX 3.4.18+ 移除了 manifest.json 可视化 appsecret 配置，建议使用 `onlyAuthorize: true` 在后端换 token，避免 appsecret 泄露 | 应推荐 `onlyAuthorize: true` 方案 |
| Apple 登录 | references 正确 | `uni.login({ provider: 'apple' })` 返回 `appleInfo` | ✓ 正确 |

### 3.5 隐私合规

| 项目 | references 中的说法 | 官方文档实际 | 处理建议 |
|------|-------------------|-------------|---------|
| `androidPrivacy.json` | 多处提及，已描述主要字段 | HBuilderX 3.2.1+ 引入，核心字段：version、prompt ("template"/"none"/"custom")、title、message、buttonAccept、buttonRefuse、hrefLoader、backToExit、second、disagreeMode、styles | ✓ 正确 |
| `template` vs `custom` 模式 | 使用 template 模式 | **官方明确建议：先用 template 模式**，custom 模式不能完全阻止隐私弹窗前的设备信息读取（第三方 SDK 在应用启动时就初始化） | ✓ 使用 template 是正确的 |
| `pushRegisterMode` | references 中多处写为 `android.pushRegisterMode = "manual"` | ⚠️ 官方 manifest schema 中 `pushRegisterMode` 属于 **`ios`** 节点，Android 不存在该字段。Android 隐私合规通过 `androidPrivacy.json` template 模式实现 | 已统一修正：`ios.pushRegisterMode = manual`（控制 iOS 通知权限弹窗）；Android 用 template 阻断 |
| `enableOAID` | 正确描述为 HBuilderX 3.8.5+ 新增字段 | 确认在 `app-plus.distribute.android.enableOAID`，默认 `true`。设为 `false` 排除旧版 OAID SDK (v1.0.13) | ✓ 正确 |

### 3.6 后台定位

| 项目 | references 中的说法 | 官方文档实际 | 处理建议 |
|------|-------------------|-------------|---------|
| `uni.startLocationUpdateBackground` | 用于微信小程序后台定位 | uni-app 没有跨平台的 `startLocationUpdateBackground` API。微信小程序有自己的后台定位 API，App 平台需要原生插件或第三方方案 | ✓ references 使用 `sup-gpslocation` 插件是正确的，但需标注这不是 uni-app 内置 API |
| Android 后台定位可靠性 | 正确描述了"进程可能被杀" | 官方明确：Android 进程被杀后代码无法执行，方案建议使用 "保活" 插件 + uni-push 兜底 | ✓ 产品承诺边界应如实告知用户 |

### 3.7 统一推送网关

| 项目 | references 中的说法 | 官方文档实际 | 处理建议 |
|------|-------------------|-------------|---------|
| 推送主链路 | "NestJS 编排 + uniCloud 统一推送网关" | **UniPush 2.0 唯一支持的服务端方案是 uniCloud `uni-cloud-push` 扩展库**，不提供 MasterSecret，不支持直连个推 REST API（那是 UniPush 1.0 已废弃方案）。非 uniCloud 后端需要创建云函数 URL 化后通过 HTTP 调用 | ⚠️ 关键发现：`UniPush2.0配置小白文档.md` 描述的"后端直连个推 REST API"是 **UniPush 1.0 的废弃方案**，不应在新项目中使用。当前项目应只保留 uniCloud push-gateway 这一条主链路 |
| `uni-cloud-push` 运行环境 | 正确描述为"只能在 uniCloud 云函数运行时使用" | 官方确认：`uniCloud` 是云函数运行时注入的全局对象，普通 Node.js 不可用，也没有可安装的通用 npm SDK | ✓ 正确，这验证了 NestJS → HTTP 云函数 → uniCloud Push 架构的必要性 |
| `sendMessage()` 返回结构 | reference 定义了 `{ ok, status: 'SUBMITTED'\|'IGNORED'\|'FAILED', ... }` 的接口 | DCloud 原始 API 返回 `{ errCode, data: { $taskid: { $cid: \"$status\" } } }`，其中 `$status` 为 `successed_offline`/`successed_online`/`successed_ignore` | ⚠️ reference 定义的接口是**项目 push-gateway 的封装层**，不是 DCloud 原始返回。应明确区分原始返回与封装后的结构，避免后人混淆 |
| `uni-cloud-s2s` v1.0.1 的 bug | 提到 sha256 分支实际调 md5 | v1.0.0 → v1.0.1 的 changelog 明确写了"修复 方法名错误"，该 bug 可能已被修复。DCloud 论坛确认过 hash 方法标签错位问题 | 建议对当前已安装的 `uni_modules/uni-cloud-s2s` 源码重新审计，确认 v1.0.1 是否已修复 |

### 3.8 微信小程序

| 项目 | references 中的说法 | 官方文档实际 | 处理建议 |
|------|-------------------|-------------|---------|
| 订阅消息模板字段类型 | references 列出 5 种：`thing`, `character_string`, `phrase`, `time`, `amount` | 官方支持 **13 种**字段类型，还包括 `number`, `letter`, `symbol`, `date`, `name`, `phone_number`, `car_number`, `enum` | references 中列出的 5 种是项目实际使用的，正确但不够完整。如需扩展模板，参考全部 13 种类型 |
| 错误码 43101/47003 | references 描述为通用错误 | 这两个错误码是**服务端发消息 API** (`/cgi-bin/message/subscribe/send`) 的错误，不是客户端 `wx.requestSubscribeMessage` 的错误。客户端有自己的错误码体系 | references 中错误码的使用上下文正确（用于后端发消息失败排查），但应标注来源 |
| `getPhoneNumber` API | references 描述流程为 "调用 getPhoneNumber 获取手机号" | ⚠️ **微信已更换 getPhoneNumber 方案**：不再需要先 `wx.login()`，返回值从 `encryptedData+iv` 改为 `code`（5 分钟有效，单次使用），服务端用 `phonenumber.getPhoneNumber` 接口换号，自 2023-08-28 起收费 0.03 元/次（1000 次免费额度） | references 中的流程如果是旧方案（AES 解密 encryptedData），需要更新为新方案 |
| `requiredBackgroundModes: ["location"]` | references 正确列出 | 官方支持 `"audio"` 和 `"location"`。但后台定位需要**三层配置**：app.json 声明 + 后台接口审批 + 用户手势授权，且需要通过人工审核（需提供录屏证明使用场景） | ✓ 正确，但需注意人工审核要求 |
| 合法域名配置 | references 正确列出四种域名 | 需在微信公众平台「开发-开发设置-服务器域名」配置，仅支持 HTTPS/WSS，不支持 IP 和父域名，域名需中国大陆 ICP 备案 | ✓ 正确 |

### 3.9 其他重要发现

| 项目 | references 中的说法 | 官方文档实际 | 处理建议 |
|------|-------------------|-------------|---------|
| `app-plus.modules.Geolocation` | 权限检查清单中列为必查项 | **官方 manifest 模块列表中不存在 `Geolocation`**。有效模块名包括：Maps、Push、OAuth、Payment、Share 等 15 个。地图/定位能力对应 **`Maps`** 模块 | 已修正 references 中此处为 `Maps`，并添加说明 |
| manifest.json 中的厂商字段 | references 将 `hms: {}` 等空对象视为配置缺失 | **UniPush 2.0 的厂商参数在 DCloud 后台配置，manifest.json 中的这些字段是旧版遗留，不起作用** | manifest.json 中的空厂商对象是正常的，不应视为风险项。确认厂商配置状态应去 DCloud 开发者中心 |
| `pushRegisterMode` 所属节点 | references 多处写为 `android.pushRegisterMode` | ⚠️ 官方文档将 `pushRegisterMode` 放在 **`ios`** 节点下（`app-plus.distribute.ios.pushRegisterMode`），用于控制 iOS 通知权限弹窗时机。Android 的隐私合规通过 `androidPrivacy.json` template 模式实现，官方 manifest schema 中**不存在 `android.pushRegisterMode`** | 所有 references 中已统一标注，建议项目按官方位置配置：iOS 用 `ios.pushRegisterMode`，Android 走 `androidPrivacy.json` |

## 四、Reference 路由表

按任务类型加载对应 reference，不必全部读取：

### 新手入门（必读）

| 文档 | 什么时候读 | 内容摘要 |
|------|-----------|---------|
| [uni小程序+APP的全程经验案例分享](references/uni小程序+APP的全程经验案例分享.md) | **首次接触项目或 uni-app 跨平台开发** | 完整项目复盘：主体/账号/证书/权限准备清单、登录闭环、推送订阅、实时定位、支付、隐私合规、部署运维、27 个真实问题复盘 |
| [project-workflow](references/project-workflow.md) | 接任何任务前 | 项目结构、命令速查、首轮巡检清单、平台分支规则、依赖偏好 |
| [materials-and-permissions](references/materials-and-permissions.md) | 改 manifest.json 或配置权限前 | 各平台物料清单、H5/小程序/Android/iOS 配置检查项、登录/支付/推送/广告/隐私检查项 |

### 推送与通知

| 文档 | 什么时候读 | 内容摘要 |
|------|-----------|---------|
| [UniPush2.0配置小白文档](references/UniPush2.0配置小白文档.md) | **首次配置 UniPush 2.0** | DCloud 后台配置步骤、前端 manifest 确认项、后端环境变量、cid 上报链路、测试步骤 |
| [APP定位与UniPush2.0小白排查手册](references/APP定位与UniPush2.0小白排查手册.md) | **推送/定位收不到，给非技术人员排查** | 手机权限检查步骤、DCloud/Apple 后台检查步骤、验证标准、按角色分工的联系人指南 |
| [UniPush2.0整体跑通检查结论](references/UniPush2.0整体跑通检查结论.md) | 检查当前项目推送状态 | 前后端代码闭环确认、已通/未通项清单、风险评估、下一步排查建议 |
| [APP定位与UniPush2.0权限配置检查清单](references/APP定位与UniPush2.0权限配置检查清单.md) | **发包前** | sup-gpslocation 检查项、UniPush 2.0 检查项、隐私合规检查项、发包前最终核对表 |
| [DCloud官方通知方案源码级说明](references/DCloud官方通知方案源码级说明.md) | 理解推送架构底层或升级依赖 | 官方通知能力边界、源码级约束、升级检查清单、uni-cloud-s2s 行为说明、不采用方案说明 |
| [微信小程序订阅消息配置小白操作手册](references/微信小程序订阅消息配置小白操作手册.md) | **配置小程序订阅消息** | 模板申请步骤、AppID/AppSecret 获取、前后端配置、验证步骤、常见错误码处理 |

### 发布与验证

| 文档 | 什么时候读 | 内容摘要 |
|------|-----------|---------|
| [release-and-verification-sop](references/release-and-verification-sop.md) | 构建、打包、发布、验证时 | 最小编译验证命令、H5/小程序/Android/iOS 各平台验证步骤、发布前 SOP、变更报告模板 |

### 排障

| 文档 | 什么时候读 | 内容摘要 |
|------|-----------|---------|
| [pitfalls-and-debugging](references/pitfalls-and-debugging.md) | 遇到具体 Bug 时 | 证据优先调试循环、H5 uni.request 报错、定位权限缓存、实时追踪、支付宝登录、协议链接、原生打包缓存、日志规范 |

### 运维（非 uni-app 核心，按需取用）

| 文档 | 什么时候读 |
|------|-----------|
| [七牛云CDN证书自动同步操作指南](references/七牛云CDN证书自动同步操作指南.md) | 服务器证书管理 |

## 五、核心架构速查

### 5.1 技术栈

| 层 | 技术 |
|---|------|
| 前端框架 | uni-app (Vue 3 + Vite) |
| 状态管理 | Pinia |
| 状态机 | XState v5（全局定位会话管理） |
| 包管理 | pnpm |
| App 打包 | HBuilderX 云打包 |
| 小程序调试 | 微信开发者工具 |
| 后端 | NestJS + Prisma + PostgreSQL |
| 实时通信 | Socket.IO (WebSocket) |
| App 推送 | UniPush 2.0 → uniCloud push-gateway |
| 小程序通知 | 微信订阅消息 |
| 地图 | 高德地图 |
| 对象存储 | 七牛云 |

### 5.2 通知架构（重要）

```
订单业务状态变化
  → OrderEventOutbox（PostgreSQL）
  → OrderNotificationOrchestratorService（NestJS 编排）
  → 三路独立投递（一路不可用不阻断其他路）：
    ├── WebSocket：在线实时推送（Socket.IO）
    ├── APP 系统通知：uniCloud push-gateway → UniPush 2.0 → 厂商通道/APNs
    └── 微信订阅消息：NestJS 直调微信 API
  → OrderEventDelivery 记录每路投递状态
```

### 5.3 关键能力边界

| 能力 | 微信小程序 | Android/iOS APP | H5 |
|------|-----------|----------------|-----|
| 系统通知 | 订阅消息（用户主动触发） | UniPush 2.0（在线+离线） | 不适用 |
| 接收者标识 | openid + 模板 ID | cid / recipientUniId | - |
| 离线推送 | 微信服务通知 | 厂商通道 (Android) / APNs (iOS) | 不支持 |
| 后台定位 | 微信后台定位 API（受生命周期限制） | 原生后台定位 + 前台服务通知 | 仅前台尽力 |
| 登录方式 | 微信登录 + 手机号 | 微信/支付宝/Apple + 手机号 | 取决于业务配置 |
| 支付方式 | 余额 + 微信 JSAPI | 余额 + 微信 APP 支付 + 支付宝 APP 支付 | 取决于产品方案 |

## 六、开工前强制准备清单

> 跨平台项目（小程序 + APP）的失败大多不是代码问题，而是**账号、证书、权限、域名没提前准备好**。

### 6.1 公司/主体层面

- [ ] 企业主体、营业执照（微信、支付宝、DCloud、Apple、厂商推送、应用商店认证）
- [ ] 各平台主体尽量保持一致
- [ ] 应用中文名/英文名/简介/分类
- [ ] Android 包名（如 `com.parkrent.center`）
- [ ] iOS Bundle ID（如 `com.parkrent.center`）
- [ ] UniApp AppID（DCloud 分配，不可临时更换）
- [ ] URL Scheme（OAuth 回跳）
- [ ] Universal Links（iOS 微信登录/分享/支付回跳）
- [ ] 隐私政策 URL、用户协议 URL（统一走 CDN，不能是 `#` 或 "功能开发中"）
- [ ] SDK 清单（名称、开发者、隐私链接必须与官方公示完全一致）
- [ ] 各尺寸图标、启动图、截图、软著等应用商店物料

### 6.2 域名与服务器

- [ ] 正式/测试 API 域名、H5 域名、管理台域名
- [ ] HTTPS 证书 + 自动续期
- [ ] 微信小程序 request/socket/upload/download 合法域名
- [ ] 微信支付/支付宝支付公网回调地址
- [ ] Universal Links 对应域名及 Apple 关联文件
- [ ] CDN 协议页面地址
- [ ] PostgreSQL 数据库及备份

### 6.3 平台账号

- [ ] DCloud 开发者中心账号 + 团队权限
- [ ] 微信公众平台小程序账号（AppID + AppSecret）
- [ ] 微信开放平台移动应用账号（AppID + AppSecret，**与小程序是两套**）
- [ ] 微信支付商户号
- [ ] 支付宝开放平台账号
- [ ] Apple Developer Program 团队权限
- [ ] 各大厂商推送开发者账号（华为/荣耀/小米/OPPO/vivo/魅族）
- [ ] 高德地图 Key（Android/iOS/WebService 各一套）
- [ ] 七牛云 AccessKey/SecretKey

### 6.4 测试设备

- [ ] 至少 1 台 Android 国产厂商真机（覆盖 Android 11/13/14）
- [ ] 至少 1 台 iOS 真机（可安装 Ad Hoc/TestFlight 包）
- [ ] 微信开发者工具
- [ ] 普通用户 + 骑手两个测试账号
- [ ] 支付测试环境（微信商户测试能力 / 支付宝沙箱）

> **仅用模拟器无法验证：厂商离线推送、APNs、App OAuth、Android 后台定位、iOS Always 定位。真机验证不可省略。**

## 七、关键约束与易错点

### 7.1 配置不能混用的四组

1. **微信小程序 AppID/AppSecret ≠ 微信开放平台移动应用 AppID/AppSecret**（混用导致登录失败）
2. **APP 的 UniPush 系统通知 ≠ 微信小程序订阅消息**（两种完全不同的机制）
3. **前端 manifest.json 中的配置 ≠ 后端服务端密钥**（UniPush AppID 不等于 AppKey 或 MasterSecret）
4. **仓库模板中的配置 ≠ 服务器运行进程实际加载的配置**（上线结论必须回到真实配置）

### 7.2 UniPush 离线推送成立的完整条件链

```
包内包含 Push 模块
→ 用户允许通知权限
→ DCloud 应用与当前 AppID 一致
→ 厂商/APNs 通道在 DCloud 后台配置正确（不是代码仓库里）
→ 隐私协议同意后才初始化推送（Android: androidPrivacy.json template 模式；iOS: pushRegisterMode=manual）
→ 真机获取到 cid
→ cid 正确入库（PostgreSQL）
→ 服务端成功发送（UNIPUSH_* 环境变量齐全）
→ 厂商系统没有拦截通知
→ 真机能收到
```

### 7.3 Android 后台定位成立的完整条件链

```
包内权限完整（含 POST_NOTIFICATIONS + FOREGROUND_SERVICE_LOCATION）
→ 系统定位总开关已开
→ APP 已获前台定位权限
→ APP 已获后台定位权限（"始终允许"）
→ Android 13+ 已授予通知权限
→ 通知渠道未被用户手动关闭
→ 插件配置正确（sup-gpslocation 已落库）
→ 重新打包并安装新包（不是旧包）
→ 真机切后台/锁屏后仍可上报
```

### 7.4 常见混淆点

| 混淆 | 正确理解 |
|------|---------|
| 拿到 cid = 离线推送已通 | cid 只是必要条件之一，厂商通道/APNs/服务器配置缺一不可 |
| manifest.json 厂商参数为空 = 没配置 | 厂商参数在 DCloud 后台配置，不在仓库的 manifest.json 中 |
| 仓库代码存在 = 线上已生效 | 必须验证：真包 + 真机 + 真实后台配置 + 真实验收 |
| online push 正常 = offline push 也正常 | 在线走 Socket，离线走厂商/APNs，是两套独立通道 |
| WebSocket 收到消息 = 推送已通 | WebSocket 只保证在线实时性，不是离线通知替代 |

## 八、平台条件编译速查

```vue
<!-- App 专用 -->
<!-- #ifdef APP-PLUS -->
<!-- #endif -->

<!-- 微信小程序专用 -->
<!-- #ifdef MP-WEIXIN -->
<!-- #endif -->

<!-- H5 专用 -->
<!-- #ifdef H5 -->
<!-- #endif -->
```

- 条件编译必须成对出现，缺失 `#endif` 会导致编译错误
- 条件编译注释看似普通注释，实际会改变不同平台的最终源码
- 每次修改条件编译后，必须构建相关平台验证，不能只看编辑器 TypeScript

## 九、官方资源

### 核心文档

| 资源 | 地址 |
|------|------|
| uni-app 官方文档 | https://uniapp.dcloud.net.cn/ |
| manifest.json 完整配置 | https://uniapp.dcloud.net.cn/collocation/manifest.html |
| pages.json 配置 | https://uniapp.dcloud.net.cn/collocation/pages.html |
| 条件编译 | https://uniapp.dcloud.net.cn/tutorial/platform.html |
| API 文档入口 | https://uniapp.dcloud.net.cn/api/ |
| uni-app-x (UTS/鸿蒙) | https://uniapp.dcloud.net.cn/uni-app-x/ |

### 推送专题

| 资源 | 地址 |
|------|------|
| UniPush 2.0 概述 | https://uniapp.dcloud.net.cn/unipush-v2.html |
| UniPush 开通与配置（含厂商通道） | https://uniapp.dcloud.net.cn/uni-push/open.html |
| Push 客户端 API | https://uniapp.dcloud.net.cn/api/plugins/push.html |
| 隐私合规配置 | https://uniapp.dcloud.net.cn/tutorial/app-privacy-android.html |

### uniCloud

| 资源 | 地址 |
|------|------|
| uniCloud 文档 | https://doc.dcloud.net.cn/uniCloud/ |
| uni-cloud-s2s（服务间鉴权） | https://doc.dcloud.net.cn/uniCloud/uni-cloud-s2s.html |
| uni-cloud-push | https://doc.dcloud.net.cn/uniCloud/uni-cloud-push.html |

### 平台

| 资源 | 地址 |
|------|------|
| DCloud 开发者中心 | https://dev.dcloud.net.cn/ |
| 微信公众平台 | https://mp.weixin.qq.com/ |
| 微信开放平台 | https://open.weixin.qq.com/ |
| 支付宝开放平台 | https://open.alipay.com/ |
| Apple Developer | https://developer.apple.com/account/ |
| 官方示例仓库 | https://github.com/dcloudio/hello-uniapp |
| uni-app-x 示例 | https://gitcode.com/dcloud/hello-uni-app-x |

### 社区

| 资源 | 地址 |
|------|------|
| DCloud 问答社区 | https://ask.dcloud.net.cn/ |
| 插件市场 | https://ext.dcloud.net.cn/ |

## 十、输出规范

报告使用中文，包含以下结构：

```markdown
## 目标
- 子项目：code/frontend / code/backend / code/admin
- 目标平台：H5 / MP-WEIXIN / APP-ANDROID / APP-IOS / 跨平台
- 任务描述：...

## 改动范围
- 涉及文件：...
- 涉及配置层面：manifest / pages / 环境变量 / 平台后台

## 根因/依据
- 根因分析（排障时）：...
- 官方文档依据（配置时）：...
- 代码调用链证据：...

## 实际改动
- 文件路径 → 改动内容
- 配置变更（标注：仅仓库 / 需同步平台后台 / 需重新打包）

## 验证
- 验证命令与结果：...
- 涉及平台的真机验证结果：...

## 剩余风险
- 需要人工确认的第三方后台配置：...
- 无法静态验证的项目：...
- 仍待真机验收的场景：...
```