增量打包到底解决什么痛点
在 HelloWorld IDE 的 Micro-Deploy 场景里，每次推送 main 函数都会生成一个可运行 URL。早期版本采用全量镜像，哪怕只改一行日志，也要重新上传 80 MB WASM 包，云端冷启动 3-4 秒。增量打包把「差分」提前到构建侧：只替换变更的函数级字节码，其余资源复用云端缓存，部署体积平均下降 60% 以上，冷启动缩短到亚秒级。
核心关键词「增量打包」首次出现，后面你会看到它与「部署体积」「差分包」「WASM 裁剪」如何联动，以及什么时候反而该关掉它。
功能定位与官方边界
HelloWorld IDE 2026.4 LTS 把增量打包做成「零开关」特性：只要在 Micro-Deploy 面板里勾选「启用差分」（默认开启），构建流水线就会自动走 wasm-split → wasm-merge → zstd 压缩 三步。官方文档明确三点边界：
- 仅支持 WASM 目标（wasm32-wasi-m2、wasm32-wasi-clang），Native Docker 镜像仍走全量。
- 差分包与基包保留 7 天，过期后自动回退全量，防止缓存膨胀。
- 单函数 patch 上限 4 MB，超过后自动拆分为「多函数组」再合并，避免浏览器单文件缓存失败。
换句话说，如果你用的是树莓派离线包或纯 Python 脚本，增量打包不会触发，也看不到相关菜单。
操作路径：桌面端与移动端差异
桌面端（Win/macOS/Linux）
- 打开项目后，右侧边栏找到「Micro-Deploy」图标（火箭形状）。
- 目标平台选「WASM-Cloud-Run」，此时会出现「启用差分」复选框（默认已勾）。
- 点击「生成分享链接」，底部状态条会先显示「Computing delta…」约数十秒，随后提示「Δ 体积 1.3 MB / 基包 78 MB」。
- 如果首次构建，系统会提示「无基包，走全量」，第二次起才享受增量。
移动端（Android/iPad）
由于屏幕限制，Micro-Deploy 被折叠到「运行」按钮的长按菜单。长按 → 选择「发布为在线 Demo」→ 底部弹出「差分优化」开关。路径更深，但流程与桌面一致。经验性观察：同一项目在手机端构建耗时比桌面多 15-25%，建议只在紧急演示时使用。
如何验证增量包真的变小
官方在构建日志里给出三行关键数据：
baseSize: 78.4 MB deltaSize: 1.2 MB patchRatio: 1.5%
你可以复制 patchRatio 到「性能监控」面板，连续观察 10 次提交。若 patchRatio 突然跳到 40% 以上，说明改动了公共依赖（如把 libc.a 升级），此时建议手动「强制全量」一次，把新依赖压成基包，否则后续差分会越来越臃肿。
常见分支与回退方案
警告：差分包损坏
现象：访客打开 URL 报「wasm instantiation failed」。
原因：本地缓存的基包与云端不一致（多设备同时发布）。
处置：在 Micro-Deploy 面板 → 高级 → 清除基包缓存，再「强制全量」一次即可恢复。
回退按钮藏在「高级」折叠页，官方故意多一步，防止新手误点。回退后，旧差分包会立即失效，已嵌入博客的 iframe 会走 404，需要重新复制链接。
不适用场景清单
- 单文件竞赛脚本（<100 行）：差分头部开销 80 KB，反而比全量大。
- 需要离线运行：树莓派镜像默认关闭 WASM 差分，走本地全量 ELF。
- 合规要求「可重复构建」：差分包依赖云端缓存，无法保证 100% 字节一致。
- 多人协作白板 + 实时调试：50 人同时推送，基包版本冲突概率指数上升。
经验性观察：当项目依赖超过 200 MB（如 OpenCV+LLVM）时，patchRatio 容易突破 30%，此时增量优势被压缩，可考虑直接走 Docker 全量镜像。
与第三方 CI 的协同
HelloWorld IDE 提供 hw-cli deploy --delta 命令，可在 GitHub Actions 里调用。最小权限只需 repo & read:packages，不会触碰代码内容。示例工作流：
- name: Delta Deploy
run: |
npx hw-cli@latest deploy --delta --base-url https://wasm.example.com
echo "patchRatio=$(cat .hw/logs/patchRatio.txt)" >> $GITHUB_OUTPUT
把 patchRatio 当成指标，配合 Action 的 if 条件，可在体积异常时自动阻断合并请求。
性能、费用与副作用
| 维度 | 全量 | 增量 | 备注 |
|---|---|---|---|
| 上传体积 | ~80 MB | 1-4 MB | 首次仍全量 |
| 冷启动 | 2.8-3.5 s | 0.6-0.9 s | 边缘节点缓存命中 |
| 免费额度 | 200 vCPU·h/月 | 相同 | 差分不计额外费用 |
| 副作用 | 无 | 缓存失效 404 | 需回退或重发 |
最佳实践 10 条速查表
- 把稳定依赖锁进
Cargo.lock/package-lock.json，减少基包漂移。 - 每 7 天或依赖升级后手动「强制全量」一次，防止 patch 链过长。
- 在 README 放置「全量回退」按钮链接，访客 404 时可自助刷新。
- CI 中把
patchRatio>30% 当成红线，自动改走全量。 - 教育网用户先换 DNS 再上传，避免 403 被当成异常流量。
- 大于 4 MB 的静态资源（模型文件）放 CDN，不走差分。
- 多人协作时，用
--base-tag给分支打标签，避免基包冲突。 - 移动端发布前，先在桌面端跑一次「强制全量」，手机只做增量补充。
- 把
.hw/cache写进.gitignore，防止队友误提交旧基包。 - 监控「冷启动」而非「上传时间」，用户体验瓶颈在前者。
故障排查速查
现象：patchRatio 突然 99%
可能原因：你把 .hw/cache 删了，本地找不到基包。验证：看构建日志是否提示 base not found, fallback to full。处置：从回收站恢复缓存或重新「强制全量」。
现象：访客端控制台报「zstd decompress fail」
原因：浏览器扩展（如旧版 Tampermonkey）劫持了 wasm 流。验证：无痕模式打开正常。处置：提示访客关闭扩展或换浏览器。
版本差异与迁移建议
2025.12 之前的老项目用的是 wasm-opt + gzip 差分，基包保留 30 天，升级 2026.4 LTS 后会自动迁移，但第一次构建会强制全量。官方保证旧链接 30 天内仍可访问，之后彻底下线老域名。建议：升级当晚就手动点一次「强制全量」，把新域名写进博客，避免读者 404。
FAQ（结构化数据）
差分包会泄漏源码吗？
不会。上传的是编译后 WASM 字节码，且通过 AES-256 端到端加密，云端只保存加密流。
免费额度用完还能增量吗？
可以。差分不额外计费，但冷启动会排队，峰值可能延迟 5-10 秒。
如何彻底关闭增量？
Micro-Deploy → 高级 → 关闭「启用差分」并「强制全量」一次，随后 .hw/config.json 会写入 "delta": false，CI 也会同步生效。
总结与下一步行动
HelloWorld IDE 的增量打包把「差分」下沉到 WASM 字节码层，让 Micro-Deploy 的冷启动进入亚秒级，上传体积缩小一个量级，却几乎不需要你多做一个配置。只要记住「首次全量、七日强制、30% 红线」三条口诀，就能在免费额度内跑出演示级别的极致体验。
下一步：打开你正在写的 Demo，长按「运行」→「发布为在线 Demo」，观察 patchRatio 是否低于 5%。如果超标，按本文清单检查依赖锁文件，再跑一次强制全量。把最终链接丢到评论区，让读者实测冷启动速度——这就是你验证增量打包成果的最直接方式。
