这是什么

ssh-fast-deploy 是一个 npm CLI 工具，把前端项目部署的三个步骤——打包 → 上传 → 远程解压——合并为一行命令。

1
2
旧流程：npm run build → 手动打包 → scp 上传 → ssh 解压
新流程：npx sfp

安装

1
npm install ssh-fast-deploy -D

快速开始

1. 生成配置文件

1
npx sfp init

会在项目根目录生成 .deployrc.json：

1
2
3
4
5
6
7
8
9
{
  "host": "your-server.com",
  "port": 22,
  "username": "root",
  "privateKey": "~/.ssh/id_rsa",
  "remotePath": "/www/wwwroot/your-site",
  "localDir": "dist",
  "backup": false
}

配置文件支持 // 行注释，填入实际信息即可。

2. 部署

1
npx sfp

一行搞定。也可以加到 package.json：

1
2
3
4
5
{
  "scripts": {
    "deploy": "sfp"
  }
}

然后 npm run deploy。

配置的四种方式

ssh-fast-deploy 支持多层配置，优先级从高到低：

1
CLI 参数 > .deployrc.json > package.json#deploy > 环境变量
方式 适用场景
CLI 参数 一次性部署、测试不同服务器
.deployrc.json 项目固定配置，团队共享
package.json#deploy 不想多一个配置文件
环境变量 CI/CD 流水线

CLI 参数

1
sfp --host 192.168.1.100 --user root --pass xxx --remote-path /www/wwwroot/my-site

支持参数：--host、--port、--user、--pass、--key、--remote-path、--local-dir。

环境变量

1
2
3
4
5
export SSH_HOST=192.168.1.100
export SSH_USER=root
export SSH_PASSWORD=xxx
export DEPLOY_REMOTE_PATH=/www/wwwroot/my-site
npx sfp

适合 CI/CD 中避免明文密码出现在代码里。

双认证方式

支持密码和 SSH 密钥两种认证：

1
2
3
4
5
6
7
8
9
// 推荐：SSH 密钥（更安全）
{
  "privateKey": "~/.ssh/id_rsa"
}

// 备选：密码
{
  "password": "your-password"
}

多目录打包

localDir 支持单个或多个目录：

1
2
3
4
5
6
7
8
{
  "localDir": "dist"
}

// 或
{
  "localDir": "dist,public"
}

CLI 中也可以：

1
sfp --local-dir dist,public

API 编程调用

除了命令行，也可以在 Node.js 脚本中编程调用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { deploy } from 'ssh-fast-deploy';

// 使用项目中的 .deployrc.json
await deploy();

// 完全通过代码传参
await deploy({
  host: '192.168.1.100',
  port: 22,
  username: 'root',
  password: 'your-password',
  remotePath: '/www/wwwroot/my-site',
  localDir: ['dist', 'public'],
  silent: false,
});

打包与上传分离

如果需要在打包和上传之间插入自定义逻辑（比如先执行测试、上传前备份等），可以把两步拆开用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { packFiles, uploadAndExtract } from 'ssh-fast-deploy';

// 1. 先打包
const zipPath = await packFiles(['dist'], '.upload.zip');

// 2. 做点别的事情（比如跑测试、生成 release notes）
// ...

// 3. 再上传
await uploadAndExtract(
  { host: '...', username: 'root', password: '...' },
  zipPath,
  '/www/wwwroot/my-site',
);

工作原理

流程非常直接：

1
2
3
4
5
6
7
8
9
10
packFiles()
  ├── 校验 localDir 目录是否存在
  ├── archiver 打包为 zip (level 9 最高压缩)
  └── 返回 zip 文件路径

uploadAndExtract()
  ├── ssh2 建立 SSH 连接
  ├── SFTP fastPut 上传 zip 到远程
  ├── exec('unzip -o xxx.zip -d /target && rm -f xxx.zip')
  └── 关闭 SSH 连接

技术栈：

依赖 作用
ssh2 SSH 连接 + SFTP 上传 + 远程命令执行
archiver 本地文件打包
commander CLI 参数解析
ora 终端 spinner 动画
fs-extra 文件操作增强

适用场景

场景 是否适合
前端静态站点（Vue/React/Hexo） ✅ 最适合
小团队快速部署 ✅
Docker / K8s 环境 ❌ 不适合，应走容器化流程
需要 CDN 加速的大规模站点 ❌ 应走 CI/CD + CDN 方案

与自定义部署脚本的区别

写项目的时候最早也是手写了一个 deploy-sftp.js，后来抽出来做成这个通用工具。对比：

手写脚本 ssh-fast-deploy
配置管理 硬编码 .deployrc.json / CLI / env 四层
跨项目复用 要复制粘贴 npm i -D 即可
参数校验 自己写 内置必填校验 + 友好提示
注释支持 — JSON 文件支持 // 注释
CLI 体验 — commander + ora spinner
代码量 数百行 零行，配置即用

开源