玩家卸载发生在加载条：996引擎资源下载器拆解

运营圈有句老话：玩家卸载游戏的高发时刻不在打不过 Boss，在等加载条。996 引擎的资源下载器 downloader/ResDownloader.lua 管的就是这条生死线——进游戏的头三分钟，玩家的耐心全押在它身上。这文件不到六百行，两个常量、一个对象池、一套静默下载，今天逐个拆给你看。

先交代它在整个资源链路里的位置：启动器管版本清单比对，比对出差集后把文件清单递给 ResDownloader，下载器管"从域名拉到本地"，落盘后动画管理器那套缓存体系接管。三段各司其职，出问题时先分清段位——清单对不上是启动器的账，下载失败是本篇的账，下完闪退是缓存的账。多少团队排查资源问题像无头苍蝇，就是因为没分段，所有症状都往一个函数里看。分段定位，是排查这类问题的第一刀。

一、先看门面：两个常量定生死

文件头两个常量，整个下载器的性格：

local RETRY_LIMIT  = 3     -- 单个任务重试上限
local DOWNLOAD_MAX = 3     -- 同时下载并发上限

并发为什么是 3 不是 30？新手都觉得并发越大下得越快，真机上是反的。家宽带宽就那么多，三十个并发互相抢，每个都慢，HTTP 连接建立的开销还翻十倍；更糟的是客户端边下边落盘，三十个文件同时写 SD 卡，IO 争抢把写入速度拖成个位数 KB/s。3 是实测出来的甜点值：带宽吃满、磁盘从容、服务端 CDN 也舒服。你要做"高速下载"卖点，正路是引导玩家开 Wi-Fi 后把并发调到 4~6，配合分时段限速，而不是无脑拉满——某服把并发开到 16，加载条看着欢腾，实际完成时间比并发 3 还慢了四成，被玩家截图群嘲了一礼拜。

重试上限 3 配套的是 _ignores 表加 _ignoreTime 冷却：重试打满的任务不销毁，进忽略名单歇一会儿，冷却过了自动回队。这个设计比"失败就弹窗"高明——大部分下载失败是网络抖动，两秒后自己就好了，玩家要的从来不是失败弹窗，是这件事最后成了。你观察一下自己手机的 App，凡是失败不弹窗、静默重试到底的，你都觉得它"稳"。

二、任务对象池：一百个备胎

每个下载任务一个对象，高峰期一秒建几十个，Lua 表的 GC 压力不能忍。引擎的解法和动画档案池一模一样——预建备胎：

local DownloadTaskCache = class("DownloadTaskCache")
function DownloadTaskCache:ctor()
    self._cache = {}
    for i = 1, 100, 1 do                      -- 启动时预建100个空任务对象
        table.insert(self._cache, DownloadTask.new())
    end
end

function DownloadTaskCache:Alloc()
    local notification = table.remove(self._cache) or DownloadTask.new()
    return notification                       -- 池里有就拿，没有才新建
end

function DownloadTaskCache:Recycle(task)
    table.insert(self._cache, task)           -- 用完塞回去，下个任务接着用
end

任务对象很轻：url、path、isFullURL、downloadCB 四个字段。但轻不等于可以随便造——Lua 的表创建走内存分配，高频路径上就是 GC 尖峰的燃料。池化的本质是把"创建销毁"变成"借还"， GC 看到的对象数恒定，曲线平得像镜面。判断你需不需要池：这个对象生命周期短于 5 秒、每秒创建超过 10 个，闭着眼睛上池子，错不了。

function DownloadTask:ctor(path, url, isFullURL, downloadCB)
    self.url        = url           -- 资源地址
    self.path       = path          -- 本地落盘路径
    self.isFullURL  = isFullURL     -- 是否完整地址（不走域名拼接）
    self.downloadCB = downloadCB    -- 完成回调
end

isFullURL 这个开关值得单独说：常规资源走 _downloadDomain 拼域名，走 CDN 的统一调度；个别特殊资源（活动临时图、紧急热修）直接给完整地址绕过拼接。一个布尔字段给运维留了后门，哪天 CDN 出事，改一个域名变量全网生效；哪天要发紧急补丁图，isFullURL 直连备用源。自由度藏在字段里，不藏在 if-else 里，这是好接口的样子。

flowchart TD
A[业务请求资源] --> B{本地已存在且版本匹配?}
B -->|是| C[直接回调, 零下载]
B -->|否| D[对象池 Alloc 任务]
D --> E[入下载队列]
E --> F{并发 < DOWNLOAD_MAX=3?}
F -->|是| G[发起下载, LOADING]
F -->|否| H[排队等槽位]
G --> I{成功?}
I -->|是| J[落盘 → 回调 → 对象回池]
I -->|失败且 retries<3| K[重试计数+1 回队]
I -->|重试打满| L[进 _ignores 冷却]
L --> M[冷却结束自动回队]
K --> F

三、路径与版本：热更新的地基

初始化里的三行决定资源放哪、从哪下：

self._downloadDomain = moduleGameEnv:GetGMWebResUrl()      -- 资源域名，运营可配
self._gmWebResVer    = moduleGameEnv.GetGMWebResVer
                       and moduleGameEnv:GetGMWebResVer() or ""
self._storagePath    = global.WritablePath .. modulePath   -- 落盘：可写目录+模块子目录

-- GM 自定义搜索路径（Windows调试用）
local gmCachePath = global.L_GameEnvManager:GetGMCachePath()
if global.isWindows and gmCachePath and string.len(gmCachePath) > 0 then
    self._storagePath = gmCachePath
end

三段各管一事：域名从游戏环境配置读——换 CDN、切加速线路都是改配置热生效，客户端不用动；版本号参与本地缓存比对——同 URL 不同版本，靠它判断要不要重下；落盘路径 = 可写目录加模块子目录，手机上各 App 的沙盒互不干扰。Windows 那段 GM 路径是调试后门：本机开发时把资源缓存指到固定目录，反复清包不用重新下载，一行配置救半小时，小功能大幸福。

版本号机制再往深说一层，它是整套"增量更新"的基石。客户端本地存着一份"我有哪些版本的哪些文件"的清单，服务端挂着最新清单，两边一对，差集就是要下的包——只下变化的部分。做过全量更新的团队都懂那个痛：改一张贴图，玩家重下 800 兆；有了版本对账，同样改动玩家只下 2 兆。这份对账逻辑不在下载器内部，但下载器的 path 字段就是为它铺的路：文件按"模块/版本"目录规整地落在沙盒里，清单才有账可对。基础层的每一条纪律，都是在给上层的省流量方案打地基。

这套结构的热修思路值得记住：下载器自己不知道资源是什么，它只知道"域名、版本、路径"三个变量。出过这样的事：某 CDN 供应商半夜抽风，运维改一行配置把 _downloadDomain 切到备用源，玩家侧零感知。如果域名散落在代码各处，这种切换就是一次紧急发版。

四、静默下载：审核与体验的平衡术

initBackgroundRes 开头有两道闸，很多二开没看懂就给拆了：

function ResDownloader:initBackgroundRes()
    -- 审核服，不触发
    if global.L_GameEnvManager:IsReview() then
        return false
    end
    -- 静默下载标记：已完成的不再来第二遍
    local userData = UserData:new("silentDownload")
    self._silentComplted = (userData:getStringForKey("silentCompleted", "") == "1")
    if self._silentComplted then
        return false
    end
    ...

第一道闸，审核服（IsReview）不跑后台静默下载——应用商店审核期间偷偷下东西，审核员看见就是一票否决，这合规红线碰不得。第二道闸，静默下载完成一次就写本地标记，之后永不再跑——它下的是"未来可能用到的资源"（预载的活动包），下完一遍就够了，反复跑是纯流量税。

静默下载的队列 _slientTasks 和正常队列分开，优先级天然靠后：玩家主动触发的下载永远插队，静默包只在带宽空闲时蹭流量。这套"让位机制"的观感收益巨大——玩家手动点下载时永远全速，没人觉得游戏在偷偷吃流量，但他进游戏五分钟后，活动资源已经悄悄躺本地了。用户研究的结论从来都是一致的：玩家反感的是失控感，不是流量本身。

静默包的内容选择也是门学问，别什么都往里塞。我们定的准入标准三条：两周内大概率用到（下个活动、常打副本的图集）、单包不超过 30 兆、失败完全无感（不重试不补下）。按这三条筛完，常规服的静默包就五六个，总重三四十兆，Wi-Fi 下四分钟下完，玩家零感知。有个团队把全部地图资源 1.2G 都塞进静默队列，玩家流量账单一夜爆雷，被应用商店差评置顶——静默下载是甜品，当主食上就砸场子。

下面这个演示把下载队列跑给你看：并发滑块对应 DOWNLOAD_MAX，失败率拉高观察重试三次进冷却、冷却完自动回队的全过程；右侧数字是对象池的借还记录，24 个任务跑完池子纹丝不动——这就是池化的直观样子：

skill-res-download-1003b

五、实战案例：CDN 故障夜的自愈改造

去年双十一档期，某服的资源 CDN 供应商故障了两小时，失败率飙到 35%。老版本客户端的表现：重试三次全失败的任务直接卡死在队列里，玩家加载条永远停在 87%，客服电话打爆。事后复盘，我们在下载层做了三件事，数字都留了档。

第一件，域名多源轮换。_downloadDomain 从单值改成数组，连续 2 次失败自动切下一个源，当前源标记冷却 10 分钟。改造后同款故障演练：失败率 35% 掉到 0.4%，玩家全程无感。工时一天半，这是下载器上性价比最高的投资，没有之一。

第二件，失败可视化。加载条卡住时给一行小字"网络波动，正在自动恢复"，别看只有一句话，客服工单量直接砍半——玩家能接受等，不能接受"死了没解释"。技术问题沟通到位，体验就到位了一半。

第三件，断点续传。原版任务重试是从头再来，大资源（百兆级客户端补丁包）反复从零开始，弱网玩家永远下不完。按字节偏移续传改造用了三天，弱网完成率从 61% 提到 96%。这三天是我们全年 ROI 最高的三天。

三件事的共同点：全在下载器内部闭环，业务层一行没改。这就是基础设施层的福气——只要接口当初留对了，后面所有的修缮都是里子工程，面子永远体面。

补充一个那次故障里学到的沟通经验。故障当晚我们没等修完才发声，第一小时就在公告里给了进度条式的说明："已切换备用线路，历史资源自动补下，预计两小时内恢复"。玩家的怒气值和"未知时长"成正比，和"已知进度"成反比——同样两小时的故障，有进度播报的那次没有一条骂帖。技术团队容易低估"被看见的努力"的价值，运维动作配上玩家语言的白话播报，是故障处理的一半工作量，也是最便宜的那一半。后来我们把这套"故障话术模板"存进了运维手册，谁值班谁套用，情感的坑不需要每次重新踩。

六、常见疑问

问：并发 3 太慢，大版本更新能不能临时调大？
能，但要分场景：Wi-Fi 且充电状态下提到 6 收益为正，蜂窝网络反而要降到 2 省流量防发热。固定值是给"平均场景"的，聪明的做法是按网络类型分档，配置表控制，别硬编码。

问：重试应该立刻还是等冷却？
第一次失败立刻重试（大概率是瞬时抖动），第二次起翻倍退避（2秒、4秒），三次打满进长冷却。立刻无间隔连打三次是最差策略——网络抖动的时间尺度通常是一两秒，三连发全撞在同一朵浪花上。

问：怎么监控线上下载质量？
在成功、重试、打满失败三个点各埋一个计数，按版本和网络类型上报。健康线参考值：失败率 < 1%、平均重试次数 < 0.3。曲线异常先看分母——新版本发布当天失败率自然抬头，那是大包在跑，别误诊。

问：下载任务的回调里能不能做重活？
不能。回调跑在下载完成的串联路径上，你塞个"解析大表+建两百个节点"进去，表现为"下载完成瞬间卡一下"，锅还背在下载器头上。回调里只做入队和通知，重活转交给业务侧的消息循环分帧消化——下载器的职责到"把文件放进本地"为止，一寸都不多管。

👉 完整课程入口：996 全套课程体系（千余节课录） ｜ 想跟浮生梦老师系统学的，看 LUA 高并发商业架构路径。