ws-sftp-deploy

一个用于前端项目构建后自动部署到服务器的 SFTP 工具，支持自动备份和 TypeScript 类型安全。

特性

• ✅ 自动备份 - 上传新版本前自动备份现有文件
• ✅ TypeScript 支持 - 完整的类型定义
• ✅ 多格式输出 - 支持 CommonJS 和 ES Module
• ✅ 智能部署 - 自动创建目录，处理部署流程
• ✅ 历史保留 - 备份文件带时间戳，不会被覆盖

安装

```bash npm install ws-sftp-deploy ```

或使用 yarn:

```bash yarn add ws-sftp-deploy ```

或使用 pnpm:

```bash pnpm add ws-sftp-deploy ```

快速开始

基本使用

```typescript import { backupAndUpload } from 'ws-sftp-deploy';

// 配置部署参数 const config = { host: "your-server.com", port: 22, username: "your-username", password: "your-password", localPath: "./dist", remotePath: "/var/www/html" };

// 执行部署 backupAndUpload(config); ```

使用 SSH 密钥认证

```typescript import { backupAndUpload } from 'ws-sftp-deploy'; import fs from 'fs';

const config = { host: "your-server.com", port: 22, username: "your-username", privateKey: fs.readFileSync('/path/to/your/private/key'), localPath: "./dist", remotePath: "/var/www/html" };

backupAndUpload(config); ```

配置选项

DeployConfig 类型

```typescript type DeployConfig = ConnectOptions & { localPath: string; // 本地打包目录路径 remotePath: string; // 服务器目标路径 }; ```

ConnectOptions 常用字段

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | `host` | `string` | 是 | 服务器 IP 或域名 | | `port` | `number` | 否 | SFTP 端口，默认 22 | | `username` | `string` | 是 | 登录用户名 | | `password` | `string` | 否 | 登录密码（与 privateKey 二选一） | | `privateKey` | `Buffer` | 否 | SSH 私钥（与 password 二选一） | | `passphrase` | `string` | 否 | 私钥密码 | | `localPath` | `string` | 是 | 本地打包目录 | | `remotePath` | `string` | 是 | 服务器目标路径 |

部署流程

1. 连接服务器 - 使用 SFTP 连接到目标服务器
2. 检查目录 - 检查远程目录是否存在，不存在则创建
3. 创建备份 - 创建带时间戳的备份目录（格式：`_backup_YYYY-MM-DDTHH-MM-SS-mmmZ`）
4. 备份现有文件 - 将远程目录中的所有文件移动到备份目录
5. 上传新版本 - 上传本地打包好的文件到远程目录
6. 完成部署 - 显示部署结果

在构建脚本中使用

创建部署脚本

创建 `scripts/deploy.ts` 或 `scripts/deploy.js`:

```typescript // scripts/deploy.ts import { backupAndUpload } from 'ws-sftp-deploy';

const config = { host: process.env.DEPLOY_HOST || "", port: Number(process.env.DEPLOY_PORT) || 22, username: process.env.DEPLOY_USER || "", password: process.env.DEPLOY_PASSWORD || "", localPath: "./dist", remotePath: process.env.DEPLOY_PATH || "" };

backupAndUpload(config).catch(console.error); ```

配置 package.json

```json { "scripts": { "build": "vite build", "deploy": "npm run build && tsx scripts/deploy.ts" } } ```

环境变量配置

创建 `.env` 文件（请将此文件添加到 `.gitignore`）:

```env DEPLOY_HOST=your-server.com DEPLOY_PORT=22 DEPLOY_USER=your-username DEPLOY_PASSWORD=your-password DEPLOY_PATH=/var/www/html ```

错误处理

工具内置了完善的错误处理机制：

• 连接失败会显示错误信息
• 单个文件备份失败不会中断整个流程
• 所有错误都会在控制台输出详细信息

```typescript import { backupAndUpload } from 'ws-sftp-deploy';

try { await backupAndUpload(config); console.log('部署成功！'); } catch (error) { console.error('部署失败：', error); process.exit(1); } ```

注意事项

⚠️ 安全提示

• 不要将服务器密码提交到代码仓库
• 建议使用环境变量或配置文件存储敏感信息
• 优先使用 SSH 密钥认证而非密码认证
• 将 `.env` 文件添加到 `.gitignore`

⚠️ 备份说明

• 备份目录命名格式：`backup[时间戳]`
• 历史备份不会被自动删除，需要手动清理
• 备份目录会被跳过，不会被再次备份

导出的 API

```typescript // 函数 export { backupAndUpload };

// 类型 export type { ConnectOptions, FileInfo }; ```

TypeScript 支持

本工具使用 TypeScript 开发，提供完整的类型定义：

```typescript import type { ConnectOptions, FileInfo } from 'ws-sftp-deploy';

// 完整的类型检查支持 const config: ConnectOptions = { host: "server.com", username: "user", // TypeScript 会提示所有可用的配置项 }; ```

开发

构建项目

```bash npm run build ```

开发模式（监听文件变化）

```bash npm run dev ```

技术栈

• tsup - 快速的 TypeScript 打包工具
• ssh2-sftp-client - SFTP 客户端
• TypeScript - 类型安全

License

ISC

贡献

欢迎提交 Issue 和 Pull Request！