@guodun/ssh-deploy

前端项目 build 完成后，通过 SFTP 将 dist 部署到远程服务器。部署前自动备份远端当前目录（默认仅保留 1 份），再上传新版本。

安全说明：本包不包含任何默认 IP、账号或密码。所有连接信息必须在各项目的 ssh-deploy.config.ts 中自行配置，密码通过 .env 注入，禁止提交到 git。

安装

pnpm add -D @guodun/ssh-deploy
# 或
npm install -D @guodun/ssh-deploy

快速接入（3 步）

1. 生成配置文件

在项目根目录执行：

npx ssh-deploy init

会生成 ssh-deploy.config.ts，内容如下：

import { defineConfig } from '@guodun/ssh-deploy'

export default defineConfig({
  host: '${SSH_DEPLOY_HOST}',
  port: 22,
  username: '${SSH_DEPLOY_USERNAME}',
  password: '${SSH_DEPLOY_PASSWORD}',
  remotePath: '/path/to/remote/dir',
  localPath: 'dist',
  backup: { enabled: true, keep: 1 },
})

2. 配置凭证（.env）

复制环境变量模板并填写：

cp .env.example .env

.env 示例（不要提交 git）：

SSH_DEPLOY_HOST=192.168.1.72
SSH_DEPLOY_USERNAME=root
SSH_DEPLOY_PASSWORD=your_password_here

将 .env 加入 .gitignore：

.env

配置文件中 ${SSH_DEPLOY_HOST} 等占位符会自动从环境变量替换。

3. 添加 postbuild 脚本

package.json：

{
  "scripts": {
    "build": "vite build",
    "postbuild": "ssh-deploy deploy"
  }
}

之后执行 pnpm build 会在打包完成后自动部署。

配置说明

必填项

| 字段 | 说明 | 示例 | |------|------|------| | host | 服务器 IP 或域名 | 192.168.1.72 | | username | SSH 用户名 | root | | password | 密码（建议用 ${ENV} 占位符） | '${SSH_DEPLOY_PASSWORD}' | | remotePath | 远端部署目录 | /home/user/www/my-app |

可选项

| 字段 | 默认值 | 说明 | |------|--------|------| | port | 22 | SSH 端口 | | localPath | dist | 本地打包目录 | | useFastput | true | 加速单文件上传 | | backup | true | 上传前是否备份远端 | | backup.keep | 1 | 保留备份份数 | | privateKey | — | 密钥登录（与 password 二选一） |

方式 A：环境变量占位符（推荐）

ssh-deploy.config.ts：

import { defineConfig } from '@guodun/ssh-deploy'

export default defineConfig({
  host: '${SSH_DEPLOY_HOST}',
  username: '${SSH_DEPLOY_USERNAME}',
  password: '${SSH_DEPLOY_PASSWORD}',
  remotePath: '/home/view-oaexpert/dev/ops-admin',
})

.env：

SSH_DEPLOY_HOST=192.168.1.72
SSH_DEPLOY_USERNAME=root
SSH_DEPLOY_PASSWORD=xxx

方式 B：直接在配置文件中引用 process.env

import { defineConfig } from '@guodun/ssh-deploy'

export default defineConfig({
  host: process.env.SSH_DEPLOY_HOST!,
  username: process.env.SSH_DEPLOY_USERNAME!,
  password: process.env.SSH_DEPLOY_PASSWORD!,
  remotePath: '/home/view-oaexpert/dev/ops-admin',
})

方式 C：CLI 临时覆盖（一次性）

ssh-deploy deploy \
  --host 192.168.1.100 \
  --username deploy \
  --password 'xxx' \
  --remote-path /path/to/dir

CLI 参数优先级最高，会覆盖配置文件中的同名字段。

CLI 命令

# 部署（build 后 postbuild 会自动调用）
ssh-deploy deploy

# 预览：不实际上传，只打印备份路径和文件列表
ssh-deploy deploy --dry-run

# 生成配置模板
ssh-deploy init

# 指定工作目录（monorepo 子包）
ssh-deploy deploy --cwd apps/my-app

上传策略

1. 连接 SFTP
2. 若远端目录有内容 → 先备份到 {remotePath}/copy_{时间}（例如 /home/user/dev/test-ssh/copy_2026-06-30_143025）
3. 删除旧备份（默认仅保留 1 份）
4. 清空远端目录
5. 上传本地 dist

上传失败时 CLI 会输出备份路径，便于手动回滚。

发布到 npm（维护者）

在本目录执行：

# 预览 tarball 内容（应仅含 dist + README.md）
pnpm release:dry-run

# 确认已登录 npm 且对 @guodun 有 publish 权限
npm whoami

# 一键发布：patch 升版 + test + build + publish
pnpm release

# 其他版本
pnpm release:minor
pnpm release:major

发布前确认仓库内无 .env、无真实密码、无内置凭证。

常见问题

Q: 报错 Missing host / Missing credentials？

A: 说明项目根目录缺少 ssh-deploy.config.ts，或 .env 未配置。执行 ssh-deploy init 并填写 .env。

Q: 不同项目用不同服务器？

A: 每个项目各自维护 ssh-deploy.config.ts，互不影响。本包不会共享或内置任何服务器信息。

Q: 不想每次 build 都上传？

A: 去掉 postbuild，改为手动脚本：

{
  "scripts": {
    "deploy:dev": "ssh-deploy deploy"
  }
}

License

MIT