Aptos Core Rebase 指南：处理 cached-packages 框架工件冲突的完整实战

Aptos Core Rebase 指南处理 cached-packages 框架工件冲突的完整实战【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core导读在 Aptos 仓库aptos-core中修改 Move 框架并执行 git rebase 时最容易卡住的不是.move源码冲突而是aptos-move/framework/cached-packages/src/下被检入仓库的编译产物冲突——二进制文件head.mrb与自动生成的 SDK builder 文件既无法三路合并也无法用 mergetool 手工解决。本文以仓库自带的 rebase-framework SKILL 文档 为主线结合 cached-packages 目录、构建脚本 与 aptos-framework CLI 源码 的底层实现系统讲解「冲突识别 → 单侧解锁 → 一次性重建 → amend/fixup 收尾 → CI 校验」的完整工作流。读完你将掌握一套可复制的 rebase 姿势避免在 PR 中被Cached framework artifacts are out-of-date反复打回。一、为什么 cached-packages 工件无法合并先理解它是什么1.1head.mrb序列化的编译产物根据 cached-packages/README.mdaptos-move/framework/cached-packages/src/head.mrb是一个BCS 序列化的ReleaseBundle其中包含所有已编译的 Move 框架包move-stdlibaptos-stdlibaptos-frameworkaptos-tokenaptos-token-objectsaptos-tradingaptos-experimental它的作用是让仓库内其他 crate 直接依赖这份预编译产物不必每次构建都重新编译整个 Move 框架从而大幅缩短编译时间。这一点从 lib.rs 的实现可见一斑该文件通过include_bytes!(head.mrb)把二进制字节静态嵌入再用bcs::from_bytes::ReleaseBundle(...)反序列化并通过once_cell::sync::Lazy缓存为进程级单例最终以head_release_bundle()对外提供只读访问const HEAD_RELEASE_BUNDLE_BYTES: [u8] include_bytes!(head.mrb); static HEAD_RELEASE_BUNDLE: LazyReleaseBundle Lazy::new(|| { bcs::from_bytes::ReleaseBundle(HEAD_RELEASE_BUNDLE_BYTES).expect(bcs succeeds) });1.2 同目录下的 SDK builder 文件除head.mrb外同目录下还有从框架代码生成的 Rust 文件文件内容aptos_framework_sdk_builder.rsaptos-framework 的 Rust SDK 绑定aptos_token_sdk_builder.rsaptos-token 的 Rust SDK 绑定aptos_token_objects_sdk_builder.rsaptos-token-objects 的 Rust SDK 绑定aptos_stdlib.rsstdlib 辅助模块lib.rscrate 入口与head_release_bundle()访问器这些文件同样在 lib.rs 中被声明为模块导出。它们与head.mrb的共同点是内容完全由 Move 源码和编译选项决定任何一方的变更都会让另一方「过期」。1.3 核心结论工件不能合并只能重建由于head.mrb是二进制 blob、builder 文件是机械生成的代码两者都不存在有意义的“三方合并”语义。SKILL 文档给出的铁律是不要尝试对 cached-packages 工件做 3-way merge。取任意一侧先解锁 git完成 rebase最后在终点用scripts/cargo_build_aptos_cached_packages.sh一次性重新生成。二、识别触发场景什么时候该调用这套流程SKILL 文档列出了需要触发本流程的典型信号包括 git 输出与 CI 报错CONFLICT (content): Merge conflict in aptos-move/framework/cached-packages/src/head.mrbwarning: Cannot merge binary files: ...head.mrbCONFLICT出现在任意aptos-move/framework/cached-packages/src/*.rsrebase 后 CI 报错ERROR: Cached framework artifacts are out-of-date.2.1 先分清冲突类型源码冲突 ≠ 工件冲突关键判别如果冲突发生在框架源码如aptos-move/framework/aptos-framework/sources/*.move必须先用常规方式手工解决——因为源码是真正的「事实来源」工件重建只是它的投影。只有工件本身head.mrb与生成的.rs的冲突才适用“取一侧、末尾重建”的策略。2.2 什么改动会让工件过期根据 cached-packages/README.md以下三类改动都会改变编译输出、进而要求重建aptos-move/framework/下的 Move 源文件如aptos-framework/sources/、aptos-stdlib/sources/、move-stdlib/sources/等Move 编译器实现或编译选项third_party/move/下的 crateaptos-move/framework/src/aptos.rs 中create_release_options相关的构建选项。三、标准操作流程五步完成带框架工件的 Rebase以下步骤完整继承自 SKILL.md并补充了底层原理说明。步骤 1先解决真实源码冲突用「单侧解锁」放行工件走完整个 rebase逐一手工解决.move、.rs、Cargo.toml的冲突。对于 cached-packages 工件不要尝试合并直接取一侧让 git 继续# 取 incoming/current 侧皆可内容反正会被重新生成。 git checkout --ours aptos-move/framework/cached-packages/src/head.mrb git checkout --ours aptos-move/framework/cached-packages/src/*.rs git add aptos-move/framework/cached-packages/src/head.mrb \ aptos-move/framework/cached-packages/src/*.rs git rebase --continue为什么--ours/--theirs无所谓因为这些文件马上就会被覆盖选哪一侧只影响 git 能否继续前进不影响最终结果。步骤 2继续完成 rebase遇到工件冲突就重复步骤 1后续提交若再次出现 cached-packages 冲突重复步骤 1 即可。切记不要在提交之间重建工件——每次重建耗时以分钟计而且是纯浪费。步骤 3rebase 结束后基于最终树一次性重建scripts/cargo_build_aptos_cached_packages.sh该脚本内部执行两件事见 cargo_build_aptos_cached_packages.shcargo run --profileci -p aptos-framework -- update-cached-packages以 CI profile带调试信息的优化构建运行aptos-framework的 CLI 子命令cargo nightly fmt -- aptos-move/framework/cached-packages/src/*.rs格式化生成的 builder 文件使其通过cargo nightly fmt --check。脚本注释特别强调必须用优化构建--profileci否则编译会非常慢。步骤 4把重建产物 amend/fixup 进框架提交保持历史干净目标字节码变更必须和引起它的 Move 源码变更待在同一提交里避免出现独立的“rebuild framework”垃圾提交。git status aptos-move/framework/cached-packages/src/ # 找出触碰框架源码的那个提交然后 git add aptos-move/framework/cached-packages/src/head.mrb \ aptos-move/framework/cached-packages/src/*.rs # 如果改动框架的提交就是 HEAD git commit --amend --no-edit # 否则用 fixup autosquash git commit --fixupframework-commit-sha GIT_SEQUENCE_EDITOR: git rebase -i --autosquash framework-commit-sha^GIT_SEQUENCE_EDITOR:让交互式 rebase 不弹编辑器直接按 autosquash 规则把 fixup 提交并入目标提交。步骤 5推送前用--check自检scripts/cargo_build_aptos_cached_packages.sh --check从脚本源码可以看到--check模式的实现先重新执行构建与格式化再用git status --porcelain -uno aptos-move检测是否有未提交变更若有则打印ERROR: Cached framework artifacts are out-of-date.并exit 1。这正是 CI 使用的同一道闸门本地先过一遍可避免 PR 打回往返。四、快速参考表情境动作rebase 中途head.mrb二进制冲突git checkout --ours head.mrb git add ...先别重建cached-packages/src/下生成的.rs冲突同样取一侧末尾统一重建rebase 中有多个改框架的提交逐个按上述方式解锁rebase --continue全部完成后只重建一次冲突在框架.move源码正常手工解决末尾的重建步骤照常执行推送后 CI 报工件过期重跑脚本amend/fixup 进框架提交force-push五、常见错误与规避尝试用 mergetool 手工合并head.mrb它是二进制 blob没有可合并的内容必须重新生成。在每个冲突提交后都重建一次每个提交浪费数分钟正确做法是末尾只重建一次。把重建产物提交成独立的 “rebuild framework” 提交评审者期望字节码变更与 Move 源码变更同提交请用--amend或--fixup归并。推送前跳过--checkCI 跑的是同一检查跳过等于把失败留给 CI徒增 PR 往返。遗漏生成的.rs文件脚本会同时重建head.mrb与cached-packages/src/*.rs两个都要 stage。六、底层原理构建脚本与update-cached-packages命令6.1 脚本如何定位仓库根目录cargo_build_aptos_cached_packages.sh 通过dirname $0推导SCRIPT_DIR再取上一级得到仓库根目录并cd进去因此可以在仓库内任意目录执行这也是 README 中 run from anywhere in the repo 的原因。6.2 CLI 子命令与head.mrb的生成update-cached-packages是aptos-framework二进制提供的 clap 子命令实现在 aptos-move/framework/src/main.rsstruct UpdateCachedPackages { /// When set, compiles the framework with #[test_only] code included. #[clap(long, default_value_t false)] with_test_mode: bool, } impl UpdateCachedPackages { fn execute(self) - anyhow::Result() { let crate_dir PathBuf::from(env!(CARGO_MANIFEST_DIR)); let filename if self.with_test_mode { cached-packages/src/head-test-only.mrb } else { cached-packages/src/head.mrb }; let output crate_dir.join(filename); ReleaseTarget::Head.create_release(true, Some(output), self.with_test_mode) } }可以看到默认生成head.mrb传入--with-test-mode时生成head-test-only.mrb供 e2e-move-tests 的move-harness-with-test-onlyfeature 使用见 cached-packages/Cargo.toml 中对该 feature 的注释。最终由ReleaseTarget::Head.create_release(...)完成框架编译与ReleaseBundle的 BCS 序列化输出。6.3 CI 校验是“建议性”还是“阻塞性”cached-packages/README.md 特别说明CI 的--check是advisory建议性、非阻塞检查因为并发合并 PR 会让检入的工件看起来过期即使单个 PR 本身是正确的。但即便 CI 不阻塞本地推送前跑一遍--check、并把产物归并进框架提交仍是保持主干干净、减少评审噪音的最佳实践。七、相关资源SKILL 原文档本流程的权威出处含冲突信号与完整命令。cached-packages/README.md工件内容、过期条件与更新方式的官方说明。构建脚本重建与--check校验的完整实现。cached-packages/src/lib.rshead.mrb的加载与ReleaseBundle反序列化。aptos-framework CLIupdate-cached-packages子命令及--with-test-mode选项。仓库 CLAUDE.md 中的提示修改aptos-move/framework/下 Move 代码后的日常流程是cargo build -p aptos-cached-packages本 SKILL 覆盖的是 rebase 场景下的变体——冲突解锁 末尾一次性重建。【免费下载链接】aptos-coreAptos is a layer 1 blockchain built to support the widespread use of blockchain through better technology and user experience.项目地址: https://gitcode.com/GitHub_Trending/ap/aptos-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考