前端构建构建工具开发工具【免费下载链接】farmExtremely fast Vite-compatible web build tool written in Rust项目地址https://gitcode.com/gh_mirrors/fa/farm点击查看免费下载Farm 从v0.14.0起支持将编译结果持久化到磁盘通过compilation.persistentCache开启后热启动hot start与热构建hot build可显著提速官方文档给出的实测数据显示编译时间最高可减少80%。本文将基于 website/docs/advanced/persistent-cache.md 的完整内容结合 packages/core/src/config/normalize-config/normalize-persistent-cache.ts 与 crates/core/src/config/persistent_cache.rs 等源码系统讲解持久化缓存的开关方式、失效校验规则、缓存键生成策略、构建依赖追踪以及插件适配注意事项帮助你在真实项目中安全、高效地开启并使用这一能力。一、为什么需要持久化缓存冷启动与热启动的差距Farm 本身是基于 Rust 编写的高性能构建工具单次编译已经很快但面对大型项目如 Ant Design Pro 级别的应用每次启动都重新解析、加载、转换全部模块仍然耗时。持久化缓存的核心思路是把上一次编译得到的模块转换结果、依赖图信息、资源产物等序列化到磁盘下次启动时直接复用跳过可跳过的构建阶段。官方文档使用 examples/arco-pro 项目给出了冷启动无缓存与热启动有缓存的对比数据阶段冷启动无缓存热启动有缓存提升幅度start启动1519ms371ms减少 75%build构建3582ms562ms减少 84%从源码实现看Farm 的缓存体系由 crates/core/src/cache/mod.rs 中的CacheManager统一管理内部包含module_cache模块及模块依赖图的缓存resource_cache最终资源资源束的缓存plugin_cache各插件自定义数据的缓存custom / lazy_compile_store自定义缓存与懒编译缓存。CacheManager在构造时会根据配置创建CacheType::Disk磁盘缓存或CacheType::Memory内存缓存磁盘缓存通过DiskCacheFactory落地到指定目录crates/core/src/cache/mod.rs。二、开启与关闭缓存persistentCache 配置2.1 一键开启使用compilation.persistentCache即可开启/关闭缓存import { defineConfig } from farmfe/core; export default defineConfig({ compilation: { persistentCache: true, }, });注意persistentCache配置在compilation字段下而buildDependencies示例中出现了直接写在顶层的情况实际使用时请统一放在compilation.persistentCache内。2.2 默认值展开true 等价于完整对象官方文档明确persistentCache: true等价于以下完整配置({ persistentCache: { // 缓存存储目录 cacheDir: node_modules/.farm/cache, // 缓存命名空间 namespace: farm-cache, buildDependencies: [ farm.config.ts, farmfe/core, farmfe/plugin-react, // ... 其他所有依赖 ], moduleCacheKeyStrategy: { timestamp: true, hash: true, }, }, });这一展开逻辑在 Rust 侧有直接印证。在 crates/core/src/config/persistent_cache.rs 中get_default_config返回的默认对象正是namespace: farm-cachecache_dir: node_modules/.farm/cache基于 root 解析为绝对路径module_cache_key_strategy: { timestamp: true, hash: true }envs、build_dependencies为空后者由 Node 侧填充而PersistentCacheConfig::default()返回Bool(true)即不配置时默认开启。配置为false则完全禁用缓存。此外在 normalize-persistent-cache.ts 中还有一个细节当检测到禁用缓存的环境开关isDisableCache()时persistentCache会被强制置为false。2.3 完整配置项速查依据 compilation-options.mdpersistentCache的类型定义如下export type PersistentCache | boolean | { namespace?: string; // 默认 farm-cache cacheDir?: string; // 默认 node_modules/.farm/cache buildDependencies?: string[];// 默认 farm.config 及其全部深层依赖 moduleCacheKeyStrategy?: { timestamp?: boolean; // 默认 true hash?: boolean; // 默认 true }; envs?: Recordstring, string; // 默认 Farm Env见环境变量与模式 globalBuiltinCacheKeyStrategy?: { define?: boolean; // 默认 true buildDependencies?: boolean; // 默认 true lockfile?: boolean; // 默认 true packageJson?: boolean; // 默认 true env?: boolean; // 默认 true }; };三、缓存校验Cache Validation什么情况会导致缓存失效缓存并非无条件复用。Farm 在尝试复用缓存前会按以下条件校验任一条件发生变化全部缓存立即失效Env 对象由persistentCache.envs配置默认为Farm Env Mode即process.env.NODE_ENV、process.env.DEV、process.env.PROD详见 Environment Variables and Modes。lockfile如果package-lock.json、yarn.lock或pnpm-lock.yaml发生变化意味着依赖集合有变动缓存整体失效。构建依赖Build Dependencies由persistentCache.buildDependencies配置任一构建依赖文件发生变化全部缓存失效。缓存命名空间Cache Namespace不同namespace下的缓存互不通用。想强制清空全部缓存时换一个新的namespace即可。内部缓存版本Internal Cache VersionFarm 内部维护一个缓存版本号当 Farm 自身版本变化且可能影响输出例如渲染优化时会提升缓存版本号触发全部缓存失效。该版本号在 crates/core/src/cache/store/constant.rs 中以常量FARM_CACHE_VERSION当前为0.9.1定义并作为缓存目录的组成部分。如果发现缓存不生效请优先排查以上条件若缓存已损坏可直接删除node_modules/.farm/cache目录手动清除。3.1 缓存目录的磁盘结构从 crates/core/src/cache/store/disk.rs 可以看到缓存目录的层级组织方式{cacheDir}/{FARM_CACHE_VERSION}-{cacheDir 末级目录名}/{namespace}/{development 或 production}/...即在cacheDir基础上追加FARM_CACHE_VERSION前缀目录 →namespace子目录 → 按开发/生产模式区分的子目录。这从实现层面印证了「内部缓存版本 命名空间 环境模式」共同参与缓存隔离的设计也解释了为何手动清缓存时删掉node_modules/.farm/cache即可。3.2 自定义环境变量参与缓存键envs使用persistentCache.envs指定额外的环境变量键值对参与缓存键计算。当其中任一值变化时全部缓存失效import { defineConfig } from farmfe/core; export default defineConfig({ compilation: { persistentCache: { envs: { MY_API_URL: process.env.MY_API_URL ?? , }, }, }, });在 persistent_cache.rs 中所有envs键会先排序再拼接成keyvaluekeyvalue...字符串经sha256哈希后作为一条「配置哈希」追加到buildDependencies中最终参与全局缓存键计算——因此任何 env 值的变化都会改变哈希进而使整份缓存失效。3.3 全局内置缓存键策略globalBuiltinCacheKeyStrategypersistentCache.globalBuiltinCacheKeyStrategy控制哪些内置键参与缓存失效判断。默认情况下define、buildDependencies、lockfile、packageJson、env这五类变化都会让整份缓存失效可针对已知不会影响构建的键选择性关闭import { defineConfig } from farmfe/core; export default defineConfig({ compilation: { persistentCache: { globalBuiltinCacheKeyStrategy: { define: true, // define 配置变化时失效缓存 buildDependencies: true, // 构建依赖变化时失效缓存 lockfile: true, // lockfile 变化时失效缓存 packageJson: true, // package.json 变化时失效缓存 env: true, // env 模式变化时失效缓存 }, }, }, });源码中的默认值在 normalize-persistent-cache.ts 中定义随后与用户配置浅合并且该策略字段不会透传给 Rust 侧会在归一化时删除见第 54 行。其底层行为是env: true时把已解析的用户 env 全部并入persistentCache.envs第 56-61 行define: true时把config.define的每个键值非字符串值会先JSON.stringify并入envs第 63-81 行——这也解释了为什么源码注释写明「所有 define 选项都应进入 envs」packageJson: true时读取 root 下package.json中type、name、exports、browser、main、module六个关键字段作为package.json[键名]形式的 env 键值第 86-107 行lockfile: true时自动把package-lock.json、yarn.lock、pnpm-lock.yaml追加进buildDependencies第 113-124 行。四、构建依赖Build Dependencies构建依赖是指可能影响编译过程或编译产物的依赖例如插件或配置文件。任一构建依赖发生变化全部缓存即失效。buildDependencies中的每一项可以是文件路径也可以是包名例如import { defineConfig } from farmfe/core; import path from node:path; export default defineConfig({ compilation: { persistentCache: { buildDependencies: [ // 一个文件路径 path.resolve(process.cwd(), ./plugins/my-plugin.js), // 一个包名注意该包必须暴露 package.json farm-plugin-custom-xxx, ], }, }, });默认情况下所有配置文件及其依赖都会被纳入如果希望额外添加一些文件或依赖来触发缓存失效通过buildDependencies追加即可一旦这些文件变化全部缓存失效。从 normalize-persistent-cache.ts 可以看到默认追踪逻辑的完整实现若存在configFileDependencies直接复用否则调用traceDependencies深度追踪配置文件的依赖绝对路径的依赖直接加入buildDependencies以字符串/数组形式声明的 Rust 插件plugins中类型为string或数组的项会通过require.resolve(${p}/package.json)解析为包名版本号形式的依赖键如farmfe/plugin-react1.x.x版本号变化即触发缓存失效。在 Rust 侧persistent_cache.rs 会把全部构建依赖排序拼接后统一做sha256哈希并将该哈希追加到cacheDir后面作为最终实际使用的缓存目录——构建依赖变了哈希就变等于换了一个全新的缓存目录这就是「全部缓存失效」在实现层面的具体体现。五、模块缓存键策略Module Cache Key StrategyFarm 提供两种策略控制模块缓存键的生成方式timestamp检查模块的更新时间戳若时间戳未变化则跳过该模块的构建性能最优hash在load与transform之后检查内容哈希若内容未变化则跳过该模块后续的构建阶段。默认两者同时开启即{ timestamp: true, hash: true }。两种策略的取舍在于timestamp最快但依赖文件系统时间戳的准确性hash更严谨但需要先执行load/transform才能拿到内容做比对。更细化的行为可参考 compilation-options.mdtimestamp: true且模块时间戳未变化时load、transform等构建阶段钩子全部跳过直接复用缓存的模块hash: true且内容未变化时仍会调用load和transform获取转换后的内容其余钩子跳过并复用缓存模块。5.1 Node 目标下的自动降级Farm 会在output.targetEnv为node时自动将timestamp置为false。该逻辑在 normalize-persistent-cache.ts 中实现——因为 Node 环境下模块文件可能由外部进程写入或热更新时间戳判断不可靠必须依赖内容哈希保证正确性。六、插件适配注意事项Caveats For Plugins这是持久化缓存最容易踩坑的地方当timestamp开启时load、transform等所有构建阶段钩子都不会被调用。因此如果插件依赖load/transform收集信息却未实现plugin_cache_loaded与write_plugin_cache钩子插件行为可能不符合预期。典型反例某插件在load与transform中收集信息、在finish钩子中统一输出就必须实现plugin_cache_loaded加载缓存与write_plugin_cache写入缓存两个钩子否则热启动时拿不到数据。这两个钩子在 Rust 侧是Plugintrait 的一部分crates/core/src/plugin/mod.rs 与 crates/core/src/plugin/mod.rsplugin_cache_loaded(self, cache: Vecu8, context)命中缓存时把插件缓存字节数据交还给插件write_plugin_cache(self, context) - OptionVecu8构建结束时插件返回自己的序列化缓存数据。调用链位于 plugin_driver.rs 与 plugin_driver.rsplugin_cache_loaded会在构建开始时遍历所有插件从PluginCacheManager读取以插件名非字母数字字符替换为_为键的缓存并逐个回调write_plugin_cache则在结束时收集各插件返回的数据写入缓存。底层存储由 crates/core/src/cache/plugin_cache.rs 的PluginCacheManager负责写盘前还会对缓存内容再做一次sha256摘要参与键管理。另外Plugintrait 还提供了handle_persistent_cached_module钩子crates/core/src/plugin/mod.rs命中持久化缓存的模块会先经过该钩子返回false即可主动失效该模块的缓存——这是插件在缓存命中时进行二次校验如自定义校验逻辑的扩展点。七、实战排查与调优建议确认开启检查配置文件中compilation.persistentCache是否为true默认即为 true或完整对象并确认没有禁用缓存的环境开关生效。看缓存目录构建后查看node_modules/.farm/cache下是否出现以FARM_CACHE_VERSION前缀命名的目录目录中包含 namespace 子目录与farm-cache.json清单文件constant.rs。缓存不生效按「缓存校验」一节逐条排查——env 是否变化、lockfile 是否变化、buildDependencies 指向的文件是否变化、namespace 是否被改动、Farm 版本是否升级。手动清缓存删除node_modules/.farm/cache目录或直接换一个namespace。Node/SSR 场景output.targetEnv为node时 timestamp 自动关闭属预期行为不必手动干预。开发自定义插件只要插件依赖load/transform且需要跨构建保留状态就必须成对实现plugin_cache_loaded与write_plugin_cache否则请在缓存策略或插件逻辑上做出取舍。参考资源官方文档原文website/docs/advanced/persistent-cache.md配置参考website/docs/config/compilation-options.mdpersistentCache小节环境变量与模式website/docs/features/env.md配置归一化实现packages/core/src/config/normalize-config/normalize-persistent-cache.tsRust 侧配置与默认值crates/core/src/config/persistent_cache.rs缓存管理器与磁盘存储crates/core/src/cache/mod.rs、crates/core/src/cache/store/disk.rs插件缓存机制crates/core/src/cache/plugin_cache.rs、crates/core/src/plugin/plugin_driver.rs赞分享前端构建构建工具开发工具【免费下载链接】farmExtremely fast Vite-compatible web build tool written in Rust项目地址https://gitcode.com/gh_mirrors/fa/farm点击查看免费下载相关推荐JAX 持久化编译缓存Persistent Compilation Cache配置与原理完全指南JAX 持久化编译缓存Persistent Compilation Cache配置与原理完全指南 JAX 的编译缓存Persistent Compilat机器学习深度学习Dragonfly 高级技巧5个实用方法优化你的附件处理流程Dragonfly 高级技巧5个实用方法优化你的附件处理流程 Dragonfly 是一款强大的 Ruby gem专为动态处理附件而设计特别适合在 Rail人工智能机器学习深度学习编译器高性能计算vllm-ascend 持久化增量 csrc 构建缓存Persistent Incremental Csrc Build Cache设计全解析vllm ascend 持久化增量 csrc 构建缓存Persistent Incremental Csrc Build Cache设计全解析 导读 本文基人工智能大模型模型推理服务AscendCANN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考