@frame/sftp

一个简单好用的 SFTP 打包上传 CLI：在本地将指定目录压缩为 .tar.gz，上传到服务器后解压并删除压缩包。支持交互/非交互模式、忽略规则、上传进度、上传前清空目录、后置命令以及超时/保活等配置。

• Node 版本要求：>= 14
• 支持操作系统：macOS / Linux / Windows（PowerShell/CMD 下也可执行）

安装

• 全局安装（推荐）

npm i -g @frame/sftp

• 项目内安装（npx 调用）

npm i -D @frame/sftp
npx @frame/sftp

安装后，全局命令名为 frame-sftp（包名为 @frame/sftp）。

快速开始（交互模式）

1. 在你的项目根目录创建 sftp.json（纯 JSON，不要注释）：

{
  "host": "127.0.0.1",
  "port": 22,
  "username": "root",
  "password": "******",
  "localDir": "dist",
  "remoteDir": "/var/www/app",
  "cleanupRemote": false,
  "gzipLevel": 6,
  "excludes": [
    "node_modules/**",
    ".git/**",
    "*.log"
  ],
  "postExtractCommand": "echo 'deploy done'",
  "readyTimeout": 20000,
  "keepaliveInterval": 10000,
  "keepaliveCountMax": 3,
  "dryRun": false
}

2. 运行命令并按提示操作：

frame-sftp

非交互模式（CI/CD）

• 直接使用配置并跳过交互提示：

frame-sftp --no-prompt

• 覆盖目录或清空选项：

frame-sftp --no-prompt --dir dist --remote /var/www/app --cleanup

• 指定自定义配置文件（默认读取当前目录下的 sftp.json）：

frame-sftp --config ./config/prod.json
# or
frame-sftp -f ./config/staging.json

• 仅打包不上传（检查打包内容）：

frame-sftp --dry-run

提示：非交互模式且 remoteDir 为 / 时，出于安全会自动禁用“清空目录”。

配置说明（sftp.json）

• host: 服务器地址或 IP
• port: SFTP/SSH 端口，默认 22
• username: 登录用户名
• password: 登录密码
• localDir: 需要压缩并上传的本地目录（相对于当前执行目录）
• remoteDir: 服务器目标目录（建议使用业务目录，例如 /var/www/app）
• cleanupRemote: 是否在上传前清空 remoteDir 内的所有文件（不删除目录本身）
• gzipLevel: 压缩等级 1-9（越大越小但更耗时）
• excludes: 打包排除规则（minimatch 语法），例如 node_modules/**、.git/**、*.log
• postExtractCommand: 远端解压完成后在 remoteDir 执行的命令（例如 pm2 reload app）
• readyTimeout: SSH 连接就绪超时（毫秒）
• keepaliveInterval: SSH 保活间隔（毫秒）
• keepaliveCountMax: SSH 保活失败最大次数
• dryRun: 仅打包不上传

更多字段说明见 CONFIG.md。

命令行参数

• --dir, -d：本地目录（优先于配置）
• --remote, -r：远程目录（优先于配置）
• --cleanup, -c：是否清空远端目录（优先于配置）
• --dry-run, -n：仅打包不上传
• --no-prompt：非交互运行
• --config, -f：指定配置文件路径（默认 sftp.json）

环境变量（可选）

• SFTP_HOST、SFTP_PORT、SFTP_USERNAME、SFTP_PASSWORD
• SFTP_LOCAL_DIR、SFTP_REMOTE_DIR、SFTP_CLEANUP_REMOTE
• SFTP_GZIP_LEVEL、SFTP_POST_EXTRACT_COMMAND
• SFTP_READY_TIMEOUT、SFTP_KEEPALIVE_INTERVAL、SFTP_KEEPALIVE_COUNT_MAX
• SFTP_DRY_RUN

说明：布尔环境变量支持 1/true/yes 表示 true。

忽略规则

• 在 sftp.json.excludes 中配置一组排除规则（minimatch 语法）
• 或在本地目录 localDir 根下创建 .frame-sftpignore 文件（每行一条规则，# 为注释；兼容旧名 .ssh-zipignore）
• 二者任一命中即排除

示例 .frame-sftpignore：

node_modules/**
.git/**
.cache/**
*.log
*.tmp

日志与流程

• 压缩 →（可选）清空远端目录 → 上传（展示进度）→ 删除本地压缩包 → 远端解压并删除压缩包 →（可选）执行 postExtractCommand → 输出耗时汇总
• 中断/异常时会尝试清理本地临时压缩包

常见问题

• 远端需要安装 tar 和 gzip
• 若账号仅允许 SFTP 无法执行命令，则远端解压与 postExtract 可能失败
• Windows 本地路径会自动转换为 POSIX 形式上传

安全提示

• 请勿将真实的 sftp.json 提交到公开仓库
• remoteDir 为 / 时，清空操作会有二次确认或自动禁用
• postExtractCommand 为你自定义命令，请注意安全性与幂等性

许可

ISC License