为什么资源清单比散落 URL 更可靠
把图片地址写在代码里，会导致三类问题：旧客户端继续请求已删除资源、发布过程中读到半套资源、缓存命中错误版本。解决方案是发布一个不可变的 manifest.json，客户端只信任清单里的路径和哈希。
{
"version": "2026.08.10-01",
"assets": [
{
"name": "player", "url": "assets/player.webp", "sha256": "...", "bytes": 18420 },
{
"name": "level-01", "url": "levels/01.json", "sha256": "...", "bytes": 3200 }
]
}
清单本身也应带版本号和缓存控制。上传顺序是“资源 -> 清单 -> 切换指针”，不要先发布指针再上传资源。
下载器：并发有限、失败可重试
小游戏运行时通常有网络和内存限制，不能一次并发下载全部资源。下面的伪平台实现将并发数固定为 3，并对单项资源重试两次：
type Asset = {
name: string; url: string; sha256: string };
export async function preload(assets: Asset[], download: (url: string) => Promise<Uint8Array>) {
const queue = [...assets];
const done = new Map<string, Uint8Array>();
async function worker() {
while (queue.length) {
const asset = queue.shift()!;
let last: unknown;
for (let attempt = 0; attempt < 3; attempt++) {
try {
const bytes = await download(asset.url);
if (sha256(bytes) !== asset.sha256) throw new Error('hash mismatch');
done.set(asset.name, bytes);
last = undefined;
break;
} catch (error) {
last = error; }
}
if (last) throw new Error(`asset failed: ${
asset.name}`);
}
}
await Promise.all(Array.from({
length: Math.min(3, assets.length) }, worker));
return done;
}
生产实现还要把失败项写入诊断信息，但不要把用户隐私或完整 URL 查询参数上传到日志。
缓存与回滚
缓存键必须包含清单版本，例如 asset:v2026.08.10-01:player。新版本预加载完成并通过哈希校验后，再原子地更新当前版本指针。任何一项失败，都继续使用上一个完整版本；不要混用新旧资源，否则关卡 JSON 和贴图可能不匹配。
离线或弱网环境下，可按优先级分层：首屏背景、玩家和第一关为必需；其余关卡和音效延迟加载。首屏仍应有明确的加载超时和重试按钮，不要让用户面对无响应的空白画布。
多端适配边界
平台 API 差异集中在下载、文件系统和生命周期。业务层只接收 AssetStore 接口，微信、抖音和 H5 分别提供适配器：
interface AssetStore {
get(name: string): Promise<Uint8Array | undefined>;
put(name: string, bytes: Uint8Array): Promise<void>;
}
这样可以在浏览器用 Cache Storage，在小游戏端用平台文件系统；测试时注入内存实现即可。不要在游戏逻辑中到处判断平台名称。
验证清单
- 发布脚本检查清单中每个文件都存在，哈希由构建产物计算。
- 下载器测试超时、断网、错误哈希和重复调用。
- 真机测试冷启动、切后台恢复和清理缓存后的首次启动。
- 资源回滚演练一次，确认旧清单仍可访问且指针切换是原子的。
- 主包只保留必需资源，超过平台限制时构建直接失败。
总结
小游戏的体验上限常由资源工程决定。不可变清单保证版本一致，哈希校验避免损坏，有限并发控制内存，完整版本回滚防止半更新。把平台差异收口到适配器后，Canvas 业务就能在多个端稳定复用。
