从21MB瘦身到4.53MB:Antigravity-Chinese-Localization的asar打包过滤与热升级注入机制详解
从21MB瘦身到4.53MB:Antigravity-Chinese-Localization的asar打包过滤与热升级注入机制详解
Antigravity-Chinese-Localization 是一款 Google Antigravity 一键汉化补丁工具,它通过 asar 打包过滤把汉化包体积从 21MB 精准压回官方标准的 4.53MB,再借助热升级注入机制让补丁可以反复覆盖更新而不出错。本文将从打包瘦身和注入升级两条主线,讲清楚这套机制背后的工程细节,帮助新手理解"轻量"与"可升级"是如何同时做到的。
一、问题起源:为什么汉化包会膨胀到 21MB?
Antigravity 是一个基于 Electron 的客户端,它的界面代码全部存放在 resources/app.asar 这个归档文件里。官方在发布时有一个关键设计:
- 官方原版
app.asar体积约为 4.53 MB,属于轻量级规格; - 体积较大的原生依赖(如
chrome-devtools-mcp,约 17MB)被存放在旁边的app.asar.unpacked/外置目录中,由运行时按标记直接读取,不进归档。
问题就出在这个"外置目录"上。汉化工具的工作方式是:先把 app.asar 整体解包 → 修改代码 → 再重新打包。如果重新打包时不做任何过滤,那些 17MB 的外置模块也会被压缩塞进新的 app.asar,结果体积直接膨胀到 21.4 MB——是官方原版的近 5 倍,还会和外置目录形成冗余拷贝。
💡 简单说:不是汉化代码很大,而是"打包时没过滤"导致了体积失控。
二、asar 打包过滤:一行参数守住 4.53MB 红线
解决膨胀的方法非常直接——在重新打包命令中注入一个过滤规则,告诉 asar 工具"遇到这些路径,继续标记为外置,不要压缩进归档":
npx asar pack "<extract_dir>" "<output_asar>" --unpack-dir "**/chrome-devtools-mcp/**"
这条命令在项目的完整汉化流程中对应 localize.js 的第 6 步"重新打包"。它的作用:
| 要素 | 说明 |
|---|---|
--unpack-dir |
asar 官方的"外置目录"参数,命中的路径会以解包形式保留并写入 app.asar.unpacked/ |
**/chrome-devtools-mcp/** |
通配规则,精准命中 17MB 级原生依赖 |
| 最终效果 | 输出包物理体积稳定在 4.53 MB,与官方规格完全一致 |
完整流程可以概括为一条流水线(见 localize.js 中的 runLocalizationWorkflow):
结束进程 → 备份官方原版(app.asar.bak) → 解包 app.asar
→ 注入汉化引擎 → 带过滤规则重新打包 → 部署覆盖
值得注意的是第 2 步的备份细节:脚本会用指纹检测(见 auto-restore.js 的 isLocalizedAsar)先判断当前文件是否已被汉化,只备份真正的官方原版,避免"用汉化包污染备份"导致永远无法还原的坑。
这套"打包瘦身与热升级机制"的完整工程剖析,可以在 docs/architecture.md 的第六章"打包瘦身与热升级机制"中阅读到更多细节。
三、热升级注入:injectOrUpdate 截断更新机制
如果说打包过滤解决了"体积"问题,那么注入策略解决的则是"可重复升级"问题。
1. 旧逻辑的致命缺陷:检测到标记就跳过
很多注入类脚本采用"若文件中已存在标记注释,则直接跳过"的策略。这在首次注入时没问题,但会导致一个严重后果:用户从 v2.1 升级到 v2.2 时,新词库、新规则根本写不进去——因为标记早已存在,整个文件被跳过,客户端停留在旧版汉化,甚至出现"新旧引擎混装"的白屏风险。
2. 正确做法:定位 + 截断 + 重写
项目改用"截断替换"技术实现真正的热升级,核心逻辑在 localize.js 的 injectOrUpdate 函数:
const markerIndex = existing.indexOf(startMarker);
if (markerIndex !== -1) {
// 已注入过:截掉旧引擎,整体替换为最新内容
existing = existing.substring(0, markerIndex).trimEnd() + '\n\n' + content;
} else {
// 首次注入:直接追加
fs.appendFileSync(filePath, '\n\n' + content, 'utf-8');
}
标记就是每段注入代码开头的注释 // Antigravity 2.0 Chinese Localization Engine。升级时:
- 找到旧引擎的起始标记位置;
- 把标记之后的所有旧代码全部截断丢弃;
- 写入最新版核心引擎与词库规则。
这样就保证了三种场景全部安全收敛:
- ✅ 全新安装 → 标记不存在,走追加注入;
- ✅ 同版本重复汉化 → 幂等覆盖,内容不变;
- ✅ 跨版本热升级 → 旧引擎被完整替换,无残留、无混装。
3. 注入目标不止一个文件
injectOrUpdate 被复用在多个关键入口(见 localize.js):
| 注入目标 | 作用 |
|---|---|
dist/preload.js |
Web 容器实时汉化引擎(界面文案) |
dist/ideInstall/wizardPreload.js |
新版向导界面的汉化 |
dist/menu.js / IPC 模块 |
原生菜单栏、右键菜单翻译映射 |
四、版本自检与自动恢复:让补丁"活着"
官方客户端每次自动更新都会静默覆盖 app.asar,汉化随即失效。为了应对这一点,项目还配了两件"保活"工具:
🔍 ASAR 版本精确读取:asar-version.js 直接解析 app.asar 文件头的 Pickle 结构,在不解包、不执行的前提下安全读出包内 package.json 的版本号,且对路径、大小、偏移做了严格校验,专防损坏归档或符号链接带来的误读。
🔄 更新后自动恢复:auto-restore.js 会比对"客户端当前版本"与"本地可用汉化包版本"(优先检查根目录 app.asar.ready,其次检查 downloads/ 缓存),版本匹配则自动备份并静默重装,配合 一键更新汉化.bat 实现"官方更新 → 汉化自动恢复"的闭环;不匹配则拦截,避免跨版本强覆盖造成白屏。
五、新手上手清单
理解了机制之后,实际使用只需要几步:
- 首次汉化:双击 双击运行汉化.bat,浏览器自动打开控制中心(
http://localhost:3388);Linux/macOS 用户执行./运行汉化.sh,或直接node localize.js --now; - 验证瘦身:汉化完成后可查看
resources/app.asar体积,应与官方标准一致(约 4.53MB),而非 21MB 膨胀版; - 官方更新后:双击
一键更新汉化.bat或执行node localize.js --auto-restore,补丁自动恢复; - 想反悔:执行
node localize.js --restore,从app.asar.bak毫秒级还原官方原版。
更多命令行参数与排错说明,参见 README.md 的"常用命令行参数"与 FAQ 章节;版本演进细节可翻阅 CHANGELOG.md。
总结
Antigravity-Chinese-Localization 的两个核心工程亮点可以浓缩为一句话:
- asar 打包过滤(
--unpack-dir)——守住 4.53MB 官方体积红线,拒绝 21MB 膨胀; - 热升级注入(
injectOrUpdate截断替换)——让"重复汉化、跨版本升级"都变成一次安全的整体重写。
两者配合,再加上版本自检与自动恢复闭环,才让这款汉化补丁既能保持轻量,又能长期"活"在快速迭代的官方客户端里。

