安装包从臃肿到精悍：键盘小鹿基于 AST 与图集引用追踪的运行时资产剪枝与四渠道同源构建

一、 客户端包体积失控的三大隐蔽物理陷阱

很多团队认为只要配置了 Webpack 或 Vite 的常规 Tree-Shaking，打包出来的安装包就自然是最小的。然而在桌面教育客户端开发中，由于涉及海量图片、音效、旧版题库与不同分发渠道的原生链接库（DLL），传统的构建工具对非代码资产（Static Assets）的追踪存在巨大的盲区：

打包器在面对这种变量插值表达式时，默认策略通常是将 ../assets/badges/ 下所有的几百张图片全盘打包。如果美术在目录中存放了未采用的草稿或废弃徽章，它们将被一股脑打进生产环境客户端。

• A & B & C & D -> KeyDeerPruningEngine
• KeyDeerPruningEngine -> PureRelease["输出 42MB 极致精悍安装包"]
• 1. 致命的 public/ 盲区陷阱： 在 Vite 或 Webpack 体系下，放置在 public/ 或 static/ 目录下的所有文件会无条件原样拷贝到最终的输出目录中。当教研团队迭代关卡、美术重构小游戏UI时，旧版的序列帧切图由于没有显式被删除，长年累月堆积在目录中，成为无主但永远霸占安装包体积的“幽灵资产”。
• 2. 动态模板字符串导致打包器“全量妥协”： 打字训练界面中存在大量按星级、关卡或输入状态动态切换的资源，例如：
• 3. 多渠道商业分发包的原生依赖污染： 键盘小鹿不仅提供官网通用的绿色纯净免安装版，同时还面向 360 软件管家渠道、360 Plus 专版以及联想应用商店定制了不同的渠道包。不同渠道引入了特定的原生支付库、特权通信动态链接库（.dll）。如果缺乏严密的构建隔离，标准版会被迫携带这些与它无关的 DLL，不仅包体积徒增 30MB+，更会导致标准版在无对应环境的电脑上启动时出现 DLL 缺失报错。

二、 键盘小鹿基于 AST 的运行时资产审计引擎架构

为了实现对全量资产的“精准追踪、动态识别、自动隔离”，我们在代码库中研发了专属的静态资产审计器 scripts/runtimeAssetAudit.ts：

• ScanCode -> ParseAST
• ParseAST & ScanPhysical -> Reachability["4. 构建双向可达性引用拓扑图 (Reachability Graph)"]
• Reachability -> InUse{"被代码实际引用?"}
• InUse -- 确定引用 -> Bundle["保留在输出清单中 (In-Bundle)"]
• InUse -- 孤立无主 -> AutoArchive["自动迁移至隔离归档区<br>(design/archived-runtime-assets)"]
• AutoArchive -> CIGate["CI 强制拦截并输出审计报告"]
• 1. 核心审计器实现代码（runtimeAssetAudit.ts）： 审计器结合了精确的 AST 语法分析与动态字符串模式反向推导，支持智能识别 badge_${idx}.png 等变量插值表达式：

三、 四渠道同源构建与特权依赖物理隔离

针对不同分发场景，键盘小鹿设计了 TYPEDEER_BUILD_VARIANT 环境变量矩阵，配合 electron-builder.config.cjs 实施动态依赖切片：

四渠道打包策略与体积对比清单：

在 electron-builder.config.cjs 中，我们通过函数式配置根据渠道动态过滤外部打包文件：

• BuildTrigger -> EnvDetector
• EnvDetector -> |standard| V1["官方标准版: 排除所有第三方渠道 DLL / 启用通用免费与会员引导"]
• EnvDetector -> |360| V2["360安全渠道版: 注入 360 认证通道 / 排除 Plus 特权库"]
• EnvDetector -> |360plus| V3["360 Plus 专版: 注入 360 Plus 专有通信桥与原生特权 DLL"]
• EnvDetector -> |lenovo| V4["联想专版: 注入联想应用中心原生支付插件"]
• V1 & V2 & V3 & V4 -> BuilderConfig["electron-builder 动态配置映射层"]
• BuilderConfig -> OutputZip["输出精确剪枝的独立渠道 ZIP / 安装包"]

四、 工业级排查复盘：动态引用误杀排查实录

在推进自动化资产审计的早期阶段，我们遭遇了一次由于动态引用导致的误删生产事故：

由于代码中没有直接写出 badge_1.webp 到 badge_40.webp 的完整字面量，早期的审计脚本将其扫描后判定为“0 引用”，直接把 40 张精美勋章切图全部隔离到了归档目录，导致生产包打包后荣誉墙页面一片空白！

function getBadgeIcon(badgeId: number) {
  return new URL(`../assets/badges/badge_${badgeId}.webp`, import.meta.url).href
}

• 1. 故障复盘：动态徽章图片被脚本判为“无主垃圾”： 在星星小屋系统中，共有 40 枚成长勋章。前端展示代码为了写得简洁，采用了如下写法：
• 2. 根因解决与第一性原理重构： 我们坚决不靠人工“临时写死白名单”来打补丁，而是从第一性原理重构了规范与引擎双向对齐： - 第一步（规范收敛）：要求所有多枚举资产必须在静态清单配置表（如 src/features/badges/catalog.ts）中显式使用 import 声明数组，或者列出合法 ID 枚举； - 第二步（审计器升级）：审计引擎增加模式通配符（Glob Pattern）检测能力。若代码中存在 badge_${string}.webp，审计器会自动提取前缀 badge_ 与后缀 .webp，在物理目录中匹配同一组规律性资产，并校验其连续性（如编号是否从 1 到 40 完整无缺），一旦发现缺号立即报警，既防止了误删，又反向倒逼了美术素材的规范交付。

五、 资产治理前后工程指标对比