Sync-Hub

智能文件同步枢纽 - 一源多目标，链接优先，智能降级

特性

• 一源多目标: 从单一源目录同步到多个目标，像枢纽一样管理文件分发
• 链接优先: 首先尝试使用符号链接，零空间占用
• 智能降级: 链接失败时自动切换到增量复制模式
• 实时同步: 支持文件变化自动同步，无需手动触发
• 跨平台: 自动适配 Windows/macOS/Linux
• 灵活配置: 支持忽略模式、删除孤儿文件等选项

安装

npm install sync-hub

什么是 Sync-Hub？

Sync-Hub 是一个文件同步枢纽，就像交通枢纽连接多条线路一样，它将单一源目录连接到多个目标目录。核心价值：

• 一源多目标: 维护一个源目录，自动同步到多个目标（如 dist、backup、staging）
• 零空间占用: 优先使用符号链接，避免重复存储
• 智能降级: 链接不可用时自动切换到增量复制，确保同步始终成功
• 自动分发: 源文件变更时，自动分发到所有目标目录

典型场景：

• 开发时同步代码到多个构建目录
• 一键部署到多个环境（dev/staging/production）
• 备份到多个位置
• 资源文件分发到不同项目

使用方式

CLI 命令行工具

安装后可使用 sync-hub 或 syncer 两个命令（功能一致）。

基本同步：

sync-hub -s ./src -t ./dist

同步到多个目录：

sync-hub -s ./src -t ./dist,./backup,./staging

启用文件监听：

sync-hub -s ./src -t ./dist -w

删除目标目录中多余的文件：

sync-hub -s ./src -t ./dist --delete-orphaned

自定义忽略模式：

sync-hub -s ./src -t ./dist -i "node_modules/**,.git/**,*.log"

禁用符号链接（直接复制）：

sync-hub -s ./src -t ./dist --no-link

API 使用

基本使用

const SmartFileSyncer = require('sync-hub');

const syncer = new SmartFileSyncer('./src', ['./dist'], {
  preferLink: true,
  fallbackToCopy: true
});

await syncer.sync();

启用监听

const syncer = new SmartFileSyncer('./src', ['./dist', './backup']);

await syncer.sync();
syncer.watch();

// 停止监听
await syncer.stopWatch();

高级配置

const syncer = new SmartFileSyncer('./src', ['./dist'], {
  preferLink: true,
  fallbackToCopy: true,
  deleteOrphaned: true,
  ignorePatterns: [
    'node_modules/**',
    '.git/**',
    '**/.DS_Store',
    '*.log',
    'dist/**',
    'build/**'
  ]
});

await syncer.sync();

加载配置文件

const { loadConfig, createSyncer } = require('sync-hub');

const config = await loadConfig('./config/custom.json');
const syncer = createSyncer('./src', ['./dist'], config);

await syncer.sync();

便捷方法

const { sync } = require('sync-hub');

await sync('./src', ['./dist', './backup']);

配置选项

选项	类型	默认值	说明
preferLink	Boolean	true	优先使用符号链接
fallbackToCopy	Boolean	true	链接失败时降级到复制
deleteOrphaned	Boolean	false	删除目标目录中多余的文件
ignorePatterns	Array	见下文	忽略的文件模式

默认忽略模式

[
  'node_modules/**',
  '.git/**',
  '**/.DS_Store',
  '**/Thumbs.db'
]

CLI 命令参数

参数	简写	说明
--source <dir>	-s	源目录（必选）
--targets <dirs>	-t	目标目录（逗号分隔，必选）
--watch	-w	启用文件监听
--delete-orphaned		删除目标目录中多余的文件
--no-link		禁用符号链接
--no-fallback		链接失败时不降级
--ignore <patterns>	-i	忽略模式（逗号分隔）

工作原理

同步策略

┌─────────────┐
│  开始同步    │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ 尝试符号链接方案  │ ← 优先方案（零空间占用）
└──────┬──────────┘
       │
       ├─成功→ 完成
       │
       ├─失败
       │
       ▼
┌─────────────────┐
│ 增量复制方案      │ ← 降级方案（智能对比）
│ - 比较文件大小    │
│ - 比较修改时间    │
│ - 只同步变化文件  │
└─────────────────┘

跨平台处理

• Windows: 使用 Junction 链接
• macOS/Linux: 使用符号链接（symlink）

增量同步规则

文件需要同步的条件：

1. 目标文件不存在
2. 文件大小不同
3. 修改时间不同（精确到秒）

示例

开发环境同步

# 开发时实时同步代码到 dist 目录
sync-hub -s ./src -t ./dist -w

多环境部署

# 同步代码到多个部署目录
sync-hub -s ./dist -t /var/www/app,/var/www/backup,/var/www/staging

备份脚本

const { sync } = require('sync-hub');

async function backup() {
  await sync('./important-data', [
    './backup/local',
    './backup/remote'
  ], {
    ignorePatterns: ['*.tmp', '*.log']
  });

  console.log('备份完成');
}

backup();

故障排除

符号链接权限问题

如果在 Windows 上遇到权限问题，可能需要管理员权限或使用 --no-link 参数。

监听不工作

监听模式只在使用复制模式时有效。符号链接模式下，文件会自动同步，无需监听。

文件被锁定

如果文件被其他程序占用，同步可能会失败。尝试关闭相关程序后重试。

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！