H5 转 App 打包平台 使用说明书
适用版本：当前线上
frontend主分支 文档定位：面向业务客户 / 站长 / 运营的"GUI 上手速查"，不是开发者文档 全部操作在浏览器内完成，无需写代码
目录
- 使用前必读
- 整体流程与界面结构
- 首页：提交打包请求 3.1 基本信息（URL / App 名 / 平台 / 包名 / 图标） 3.2 高级选项：SDK & Tracking 面板 3.3 提交与表单校验
- SDK 详解 4.1 Custom JS（自定义脚本） 4.2 Sentry（错误监控） 4.3 AppVue（拉新归因） 4.4 Umeng（友盟统计） 4.5 Firebase（统计 + 崩溃） 4.6 51LA（网站统计） 4.7 Network Proxy（网络代理 + 备选域名）
- 进度页：等待打包完成
- 下载与分发
- 历史记录与失败重试
- 常见使用问答
1. 使用前必读
- 整套流程全部在网页上完成：填表 → 提交 → 等待 → 下载，不需要本地装开发环境。
- 浏览器建议使用最新版 Chrome / Edge / Firefox / Safari。
- 必须准备好的素材：
- 要打包的 H5 站点 URL（线上 https 地址，不能是 localhost / 内网地址）
- App 显示名称
- 图标 PNG：正方形 + 至少 1024×1024 像素
- 若打包 Android：合法包名（形如
com.公司.应用） - 若需要接 SDK：各 SDK 平台的 Key / Secret / DSN / MaskId 等凭据
- iOS 包目前输出未签名
.app.zip，需要你自己在 Mac 上用 Xcode + Apple 开发者证书重新签名才能上架/分发；没有苹果开发者账号请暂时跳过 iOS。 - 同一个 H5 URL / 同一个 App 名 / 同一个 Android 包名全局唯一（按"非失败"维度判定），已存在排队中或成功的请求时不能重复提交。
2. 整体流程与界面结构
平台只有三个页面，导航在每页右上角：
| 页面 | 路径 | 用途 |
|---|---|---|
| 首页（New Build） | / |
填表提交一次新的打包请求 |
| 进度页（Build Status） | /task/:id |
每 3 秒自动刷新，查看各平台进度、下载产物、失败重试 |
| 历史记录（History） | /history |
最近 50 条任务列表，按状态着色，可重进进度页或重新打包 |
完整流程：
首页填表
↓
点 Start Packaging → 自动跳转到 进度页
↓
每 3 秒刷新
↓
┌─────────────────────────────┐
│ 各平台卡片状态： │
│ Queued → Building → Ready │
│ └→ Failed │
└─────────────────────────────┘
↓
点 Download 下载产物
↓
(失败时点"重新打包")
任何时候都可以从右上角 History 进入历史记录页继续未完成的任务。
3. 首页：提交打包请求
打开首页（默认 http://你的服务器域名/），看到一张白色卡片，从上到下依次填写。
3.1 基本信息
| 字段 | 必填 | 说明 |
|---|---|---|
| H5 URL | ✅ | 要打包的网页地址，必须以 http:// 或 https:// 开头；不能填 localhost / 127.0.0.1 / 公司内网地址（用户手机访问不到） |
| App Name | ✅ | App 在桌面/应用列表中显示的名字，中英文均可，最多 64 字符 |
| Target Platforms | ✅ | 至少勾一个：Android / iOS (unsigned) / macOS / Windows；多选越多打包时间越长 |
| Android Package Name | 条件 | 仅当勾选 Android 时出现；必须全小写 + 至少一个点号，形如 com.example.myapp；上架后不能修改，命名务必慎重 |
| App Icon | ✅ | 点 Choose File 选 PNG；正方形 + 至少 1024×1024；建议主体居中、四周留约 10% 空白；系统会自动缩放出各平台所需小尺寸 |
平台说明：
| 平台选项 | 输出产物 | 是否可直接分发 |
|---|---|---|
| Android | android.apk（已签名） |
✅ 可直接发给用户安装或上架 |
| iOS (unsigned) | ios-unsigned.app.zip（未签名） |
❌ 必须本地 Xcode 重新签名 |
| macOS | macos.dmg |
✅ 用户双击挂载后拖入 Applications |
| Windows | windows-setup.exe |
✅ 双击运行向导式安装 |
3.2 高级选项：SDK & Tracking 面板
如果只要纯壳 App，可跳过本节直接提交。
如需第三方统计 / 错误监控 / 拉新归因 / 网络代理，点首页中部 SDK & Tracking 一栏右侧 Show 展开，里面分两块：
- Custom JS：自定义脚本注入，在 H5 加载前执行（详见 4.1）
- SDK 列表：6 个可选 SDK，每个都是"勾选 → 展开 → 填字段"模式（详见 4.2 – 4.7）
面板里的通用规则：
- 每个 SDK 卡片标记了支持平台；如果你勾的目标平台里有不支持的，面板会出现一行琥珀色提示 Not supported on: xxx (will be skipped)，那部分平台会跳过这个 SDK 而不报错，其他平台正常生效
- 标
*号的字段为必填 - 密钥类字段以密码框样式显示，输入时遮挡
3.3 提交与表单校验
确认信息无误，点底部蓝色按钮 Start Packaging。
- 按钮变成 Submitting… 表示正在提交
- 提交成功后自动跳转到进度页
常见提交报错对照表
| 提示文字 | 原因 | 处理 |
|---|---|---|
| H5 URL is required | URL 没填 | 补填 |
| App name is required | App Name 没填 | 补填 |
| App icon is required | 没选图标 | 选 PNG |
| Icon must be a PNG image | 图标不是 PNG | 换 PNG |
| Icon must be a square image | 图标不是正方形 | 裁成正方形 |
| Icon must be at least 1024x1024 pixels | 图标太小 | 换大图 |
| Android package name must look like com.example.app | 包名格式不对 | 全小写 + 至少一个点 |
| duplicate_url / duplicate_app_name / duplicate_package | 同 URL / 同名 / 同包名已有排队或成功记录 | 去 History 查看，不要重复提交 |
4. SDK 详解
4.1 Custom JS（自定义脚本）
一个大文本框，你写的 JS 会在 App 打开 H5 页面之前自动注入到 WebView。
典型用途：
- 粘贴第三方统计代码（Google Analytics、百度统计、Mixpanel 等）
- 注入品牌标识或运行环境标记：
window.__APP_BRAND__ = "your-brand"; window.__APP_VERSION__ = "1.0.0";
限制与注意：
- 最多 50,000 字符（文本框右下角实时计数）
- 注入时机早于 H5 自己的脚本，需要操作 DOM 时先包一层
DOMContentLoaded - ⚠️ 严禁在里面写密钥 / token / 后台密码：客户端可见，所有用户都能读取
4.2 Sentry（错误监控）
| 项 | 内容 |
|---|---|
| 支持平台 | Android · iOS · macOS · Windows |
| 必填字段 | DSN —— Sentry 控制台 → 项目 → Settings → Client Keys (DSN)，形如 https://[email protected]/456 |
| 何时启用 | 需要监控线上 JS 报错和原生崩溃时 |
4.3 AppVue（拉新归因）
| 项 | 内容 |
|---|---|
| 支持平台 | Android · iOS |
| 必填字段 | App Key / App Secret —— AppVue 控制台为你的 App 申请并复制 |
| 何时启用 | 做新用户拉新归因、渠道效果监测时 |
⚠️ App Secret 属于敏感凭据，请妥善保管，不要外泄。
4.4 Umeng（友盟统计）
| 项 | 内容 |
|---|---|
| 支持平台 | Android · iOS |
| Android App Key | 仅勾选 Android 时显示，友盟控制台为 Android 应用单独申请 |
| iOS App Key | 仅勾选 iOS 时显示，友盟控制台为 iOS 应用单独申请 |
| Channel | 可选；渠道号如 official / huawei / xiaomi，便于后台分渠道统计 |
表单会只展开你当前用得到的字段：没勾 iOS 就不会出现 iOS App Key 一栏。
4.5 Firebase（统计 + 崩溃）
| 项 | 内容 |
|---|---|
| 支持平台 | Android · iOS |
| google-services.json (base64) | 仅 Android 时显示，把 Firebase 给你的整份文件转 base64 后粘进来 |
| GoogleService-Info.plist (base64) | 仅 iOS 时显示，把 plist 整份文件转 base64 后粘进来 |
怎么把整份配置文件转 base64：
| 系统 | 命令 |
|---|---|
| macOS / Linux | base64 -i google-services.json | tr -d '\n' |
| Windows PowerShell | [Convert]::ToBase64String([IO.File]::ReadAllBytes("google-services.json")) |
| 不会命令行 | 浏览器搜 "base64 file encoder online"，把整段输出复制粘贴 |
结果是一长串字母数字串，全部粘进对应字段即可（系统对长度无硬限制，但 sdk_configs 整体不超过 50 KB）。
4.6 51LA（网站统计）
| 项 | 内容 |
|---|---|
| 支持平台 | Android · iOS · macOS · Windows |
| MaskId ✅ | 1–32 位字母数字；在 v6.51.la 应用管理页复制 |
| Auto Event Tracking | 可选复选框；勾上 = 自动采集点击/浏览等通用事件 |
| SPA Hash Routing | 可选复选框；只有你的 H5 是单页应用 + 使用 #/ Hash 路由时才勾，否则页面切换会重复统计或漏计 |
4.7 Network Proxy（网络代理 + 备选域名）⭐ 重点
支持平台：Android · macOS · Windows（iOS 暂不支持）
适用场景：
- H5 在某些地区/网络下访问慢或被封，需让 App 内自动走代理
- 主域名可能被屏蔽，需让 App 自动切到备选域名继续访问
- 想让 App 自带一组兜底节点，即使云端配置全部拉不到也能保底联通
下面 6 项至少填一项（六个全空提交会报错），其余按需选填：
| 字段 | 类型 | 说明 |
|---|---|---|
| OSS Proxy Node URLs | 多行字符串（每行一个 https URL） | App 定期去这些地址拉最新代理节点池；改完节点不用重新打包，App 端自动更新；必须 https，否则会被拒绝 |
| Domain Failover Config URLs | 多行字符串（每行一个 https URL） | 远端返回纯文本，按行罗列 H5 备选域名；主域名失败时 App 自动切换；必须 https |
| Cloud Update Interval (hours) | 数字 | 云端更新周期，单位小时；范围 0.1 – 168，默认 1（每小时一次） |
| DNS TXT Domains | 多行字符串（每行一个域名，不要带 https://） | 兜底发现：上面两个 https 地址都拉不到时，App 会查这些域名的 TXT 记录恢复连接 |
| Built-in Proxies | 多行字符串 | 预先打进 App 包的离线节点；每行一个节点；敏感字段，妥善保管（详见下表） |
| Disable Direct Connection | 复选框 | 不勾（默认） = 优先直连，失败再走代理；勾上 = 强制全部走代理 |
Built-in Proxies 的两种行格式
| 格式 | 示例 | 说明 |
|---|---|---|
| Shadowsocks 链接 | ss://[email protected]:8388#hk-node |
@ 前面是 加密方式:密码 的 base64；已有现成 SS 链接直接复制粘贴最方便 |
| JSON 节点对象（单行） | {"name":"hk","type":"ss","server":"1.2.3.4","port":8388,"cipher":"aes-256-gcm","password":"yourpwd","udp":true} |
必须整段写在一行内，不能换行 |
JSON 节点字段含义：
| 字段 | 必填 | 取值 |
|---|---|---|
type |
✅ | 当前仅支持 ss（Shadowsocks）；vmess / trojan 等暂不支持 |
server |
✅ | 节点 host |
port |
✅ | 1–65535 |
cipher |
✅ | SS 加密方式，常用 aes-256-gcm / chacha20-ietf-poly1305 |
password |
✅ | 节点密码 |
name |
可选 | 节点显示名 |
udp |
可选 | 是否启用 UDP 转发，默认 false |
代理 SDK 完整填写示例
OSS Proxy Node URLs:
https://cdn.example.com/nodes.json
https://backup.example.com/nodes.json
Domain Failover Config URLs:
https://cdn.example.com/domains.txt
Cloud Update Interval (hours): 2
DNS TXT Domains:
config.example.com
backup.example.org
Built-in Proxies:
ss://[email protected]:8388#hk
{"name":"sg","type":"ss","server":"5.6.7.8","port":443,"cipher":"aes-256-gcm","password":"x"}
Disable Direct Connection: ☐ (不勾)
5. 进度页：等待打包完成
提交成功后自动跳转，页面标题 Build Status。
布局：
- 顶部：H5 URL + 左上角 ← New Build / History 链接
- 中部：每个目标平台一张状态卡，每 3 秒自动刷新
- 底部：构建完成提示；若有失败显示红色 重新打包 按钮
状态卡四种状态：
| 卡片显示 | 颜色 | 含义 | 用户操作 |
|---|---|---|---|
| Queued | 灰 | 排队中，还没轮到 | 等待 |
| Building… | 蓝（闪动） | 正在打包 | 等待 |
| Ready to download | 绿 | 完成 | 点右侧 Download |
| Build failed | 红 | 失败，下方一行错误概要 | 看错误或点底部"重新打包" |
典型耗时参考：
| 平台 | 单次耗时 |
|---|---|
| Android | 2–5 分钟 |
| iOS | 1–3 分钟 |
| macOS | 3–5 分钟 |
| Windows | 3–5 分钟 |
关于离开页面：
- 打包过程中可以关闭浏览器，任务在服务器端继续跑
- 后续从右上角 History 进入找到这条任务，点状态徽章重新进入进度页查看 / 下载
- 不推荐在多个标签页同时打开同一进度页，会重复请求
6. 下载与分发
进度页绿色 Download 按钮直接下载到本地。
| 平台 | 文件名 | 怎么用 |
|---|---|---|
| Android | android.apk |
直接发给用户安装；上架应用商店；放官网下载页 |
| iOS | ios-unsigned.app.zip |
未签名，不能直装；解压后用 Xcode + Apple 开发者证书重新签名 → TestFlight / App Store |
| macOS | macos.dmg |
用户双击挂载后拖进 Applications；上架 Mac App Store 需自行处理公证 (notarize) |
| Windows | windows-setup.exe |
NSIS 安装包，双击运行向导式安装；可放官网下载页 |
关于 Android 签名：
当前网页表单没有提供"上传自定义 keystore"入口，打包出的 android.apk 使用平台默认 keystore，仅适合内部测试和开发分发；正式上架应用商店请联系运维替换为你公司的正式签名证书后再打包。
7. 历史记录与失败重试
7.1 历史记录页
右上角 History 链接进入，可看到：
- 一行一条任务，按时间倒序，最近 50 条
- 每行显示：H5 URL（截断显示，悬停看完整）、提交时间、目标平台
- 右侧状态徽章颜色：
| 徽章 | 颜色 | 含义 |
|---|---|---|
done |
绿 | 成功完成 |
running |
蓝 | 打包中 |
pending |
灰 | 排队中 |
failed |
红 | 失败 |
- 点徽章 → 跳进对应进度页（继续下载或查看错误）
- 失败任务额外有红色 重新打包 按钮
7.2 失败重试
两个位置可以点 重新打包：
- 进度页底部：失败后红色按钮
- 历史页右侧：失败任务行后红色小按钮
点击后服务器用原参数（URL / App 名 / 平台 / 包名 / 图标 / SDK / 自定义脚本 / 签名）完整复用一遍创建新任务，并自动跳转到新进度页 —— 你不需要重新填表。
⚠️ 图标已被清理时：若原图标文件已被运维清理或过期，重新打包会提示 icon_missing_resubmit，此时只能回首页重新上传图标后再提交一个新请求。
8. 常见使用问答
Q：能用同一个 H5 URL 打包两次吗？
A：可以，但前一次必须是 done 或 failed 状态。如果上一次还在排队 / 构建中，再次提交会被拒绝并提示 duplicate_url。App Name 和 Android 包名同理。
Q：图标我手头只有 512×512 怎么办？ A：必须重新做到至少 1024×1024。系统只会按需缩小，不会自动放大模糊的小图。可以用 Figma / Sketch / Keynote / PPT 把原图等比放大后再导 PNG。
Q：iOS 包能直接装到手机吗？
A：不能。我们输出的是 ios-unsigned.app.zip，必须本地用 Xcode + 你公司的 Apple 开发者证书重新签名。如果你没有 Apple 开发者账号，建议暂时跳过 iOS 平台。
Q：选了不支持代理的 iOS，加上代理 SDK 会怎么样？ A：对 iOS 跳过这个 SDK 而不报错；Android / macOS / Windows 正常生效。面板上会出现 Not supported on: ios (will be skipped) 提示。
Q：自定义签名 keystore 能在网页上传吗？ A：当前网页表单没有此入口，使用平台默认 keystore（仅适合开发测试）。如需自定义签名，请联系运维。
Q：SDK 的 key / secret 会被泄露吗？ A：传输由 HTTPS 加密；在服务器端按 App 一对一存储；最终注入到你这一个 App 内，仅在该 App 用户的设备上使用。但 Custom JS 注入的内容嵌入到 H5 中所有用户可见，绝不要往里写密钥。
Q：打包过程能取消吗？ A：当前 UI不提供取消按钮。打包失败或不再需要时，等任务自然失败/完成后忽略即可，不会重复计费。
Q：打包失败错误看不懂？
A：把进度页里那行错误概要截图，连同浏览器地址栏 URL 末尾的任务 ID（/task/xxx 后面那串）一起反馈给运维处理。
Q：怎么看打包大约还要等多久？ A：提交后进度页没有显式倒计时，参考第 5 节的"典型耗时"即可；排队时长取决于当前服务器繁忙程度，高峰期可能要再等几分钟。
Q：History 看不到我前几天的任务？ A：History 只显示最近 50 条，更早的任务不会显示，但产物文件仍在服务器上保留（直到运维清理）。若需要找回，把当时的 H5 URL / 提交时间发给运维。
附：一份完整操作示例
场景：为一家电商 H5 打包，需求：
- 站点：
https://shop.example.com - App 名：
Demo 商城 - 目标：Android + macOS
- 接 51LA 统计、Sentry 错误监控
- 中国部分地区访问慢，需要内置一组兜底代理
操作步骤：
- 首页 H5 URL：
https://shop.example.com - App Name：
Demo 商城 - Target Platforms：勾选
Android和macOS - Android Package Name：
com.example.shop - App Icon：选一张 1024×1024 PNG
- 展开 SDK & Tracking
- 勾 51LA Analytics：填 MaskId（从 v6.51.la 后台复制），勾 Auto Event Tracking
- 勾 Sentry：填 DSN
- 勾 Network Proxy：在 Built-in Proxies 里粘一行 SS 链接，其它留空
- 点 Start Packaging
- 跳转后等约 5 分钟，两张卡变绿
- 分别点 Download，拿到
android.apk和macos.dmg - 把
android.apk发给安卓用户，macos.dmg上传到自己的下载站
完成 ✅
