synthia-cache

Synthia Engine 缓存插件 - 为 Synthia 提供强大的缓存功能，显著提升构建和开发性能

✨ 核心特性

• Synthia 插件: 完全集成到 Synthia Engine 的插件系统
• 智能缓存: 自动检测项目变化，智能缓存构建结果
• 热启动优化: 大幅提升 dev 和 build 命令的启动速度
• 多级缓存: 本地 + 云端混合缓存策略
• 性能监控: 详细的缓存统计和性能指标
• 命令行工具: 提供丰富的缓存管理命令

🚀 快速开始

安装

npm install synthia-cache

基本使用

安装并在 Synthia 配置中启用后，缓存插件会自动集成到 CLI：

# 开发模式 - 自动启用缓存优化
synthia dev

# 构建模式 - 自动启用构建缓存
synthia build

# 缓存管理命令
synthia cache --status    # 查看缓存状态
synthia cache --clear     # 清空缓存
synthia cache --analyze   # 分析缓存使用情况

📋 命令参考

缓存管理命令

synthia cache [options]

选项

• --clear - 清空所有缓存
• --analyze - 分析缓存使用情况
• --status - 查看缓存状态
• --warmup [keys...] - 预热指定缓存
• --cleanup - 智能清理缓存
• --report - 生成性能报告
• --config - 显示缓存配置
• --version - 显示版本信息

使用示例

# 查看缓存状态
synthia cache --status

# 清空缓存
synthia cache --clear

# 分析缓存使用情况
synthia cache --analyze

# 预热常用缓存
synthia cache --warmup config:app config:build deps:common

# 智能清理过期缓存
synthia cache --cleanup

# 生成性能报告
synthia cache --report

🔧 配置

缓存配置

缓存插件会自动检测项目配置，也可以通过配置文件进行自定义。以 synthia.config.js 为例：

// synthia.config.js
import { defineConfig } from 'synthia-cli';
import { cachePlugin } from 'synthia-cache';

export default defineConfig({
  plugins: [
    cachePlugin({
      enabled: true,
      local: {
        dir: '.synthia-cache',
        maxSize: 200 * 1024 * 1024, // 200MB
        ttl: 7 * 24 * 60 * 60 * 1000, // 7天
        compression: true,
      },
      cloud: {
        enabled: false, // 设置为 true 启用云端缓存
        provider: 'aws-s3',
        bucket: 'your-bucket-name',
        region: 'us-east-1',
        accessKeyId: 'your-access-key-id',
        accessKeySecret: 'your-secret-access-key',
      },
      strategy: {
        level: 'local', // 'local' | 'cloud' | 'hybrid'
        localFirst: true,
        autoSync: false,
        syncInterval: 5 * 60 * 1000, // 5分钟
      },
    }),
  ],
});

注意: 由于 CommonJS 模块限制，请直接导入插件函数，不要导入类型定义。如果需要类型提示，可以在配置对象中使用 as const 断言。

环境变量

# 启用云端缓存
SYNTHIA_CACHE_CLOUD_ENABLED=true

# AWS S3 配置
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_REGION=us-east-1
AWS_S3_BUCKET=your-bucket-name

🎯 功能特性

1. 自动缓存优化

插件会自动检测项目变化并智能缓存：

• 配置缓存: 缓存项目配置解析结果
• 依赖缓存: 缓存依赖分析结果
• 构建缓存: 缓存构建输出和中间结果
• 源文件缓存: 缓存源文件变化检测

2. 热启动优化

显著提升开发体验：

• 开发模式: 启动速度提升 60-80%
• 构建模式: 构建速度提升 70-90%
• 增量构建: 支持增量构建，提升 40-60%

3. 智能缓存策略

• 依赖追踪: 自动追踪文件依赖关系
• 版本控制: 智能的缓存版本管理
• 失效检测: 自动检测缓存失效
• 清理策略: 多种智能清理策略

4. 性能监控

• 实时指标: 缓存命中率、响应时间等
• 历史统计: 详细的性能历史数据
• 优化建议: 自动生成性能优化建议
• 报告生成: 生成详细的性能报告

📊 性能提升

典型性能提升

• 首次构建: 正常构建时间
• 缓存命中: 构建时间减少 70-90%
• 增量构建: 构建时间减少 40-60%
• 开发启动: 启动时间减少 60-80%

缓存效果

项目类型        首次构建    缓存命中    提升比例
Vue 项目       45s        8s         82%
React 项目     38s        6s         84%
Node.js 项目   25s        4s         84%
TypeScript     52s        9s         83%

🔍 工作原理

1. 缓存键生成

插件会根据以下因素生成缓存键：

• 项目路径和版本
• 依赖文件哈希
• 构建配置哈希
• 源文件变化

2. 缓存策略

• 本地优先: 优先使用本地缓存
• 云端同步: 支持云端缓存同步
• 智能失效: 自动检测缓存失效
• 版本管理: 多版本缓存管理

3. 性能优化

• 并行处理: 并行执行缓存操作
• 批量操作: 批量处理缓存请求
• 压缩存储: 智能压缩减少存储空间
• 预热机制: 智能预热常用缓存

🛠️ 插件启用方式

本包默认导出函数式插件，供 synthia 插件系统自动加载。无需手动实例化或注册类；只需在配置的 plugins 数组中以名称或路径声明该插件，并可通过 config 字段传入自定义缓存配置（见上文）。

📈 监控和调试

性能监控

# 查看实时性能指标
synthia cache --status

# 生成详细性能报告
synthia cache --report

# 分析缓存使用情况
synthia cache --analyze

提示：当前实现未内置 DEBUG 命名空间开关；如需调试输出，可根据终端日志与 --status/--analyze/--report 命令结果排查。

🤝 贡献

欢迎贡献代码！请查看 贡献指南 了解详细信息。

📄 许可证

MIT License - 查看 LICENSE 文件了解详细信息。