scp-next v1.0.19 项目介绍: 面向 Node.js 开发者的 SSH 文件传输工具

原创

除除

发布于 2026-07-06 14:33:11

150

文章被收录于专栏：除除的专栏除除的专栏

scp-next 是一个 SCP 风格的 npm 包。他同时提供命令行工具和库，用于通过 SSH 安全传输文件。虽然包名包含 SCP，实际使用 SFTP，不会为普通传输执行远程 Shell 命令。

适合谁使用

如果你需要在部署脚本、CI 流程或 Node.js 应用中传输文件，scp-next 可以减少重复封装。常见场景如下:

将本地构建产物上传到服务器。
从服务器下载日志或产物。
用配置文件管理不同服务器环境。
在应用代码中复用同一个传输客户端。

安装方式

全局安装后，可以直接使用 scp-next 命令。

npm install --global scp-next

作为项目依赖安装后，可以在 Node.js 代码中导入 API。

npm install scp-next

如果一个项目只在脚本里调用命令行工具，也可以把他安装到项目依赖中，再通过 npx scp-next 或 npm scripts 调用。

先理解传输方向

命令行统一使用 <source> <destination> 两个位置参数。

scp-next upload <source> <destination> [options]
scp-next download <source> <destination> [options]
scp-next run <job> [source] [destination] [options]

方向规则如下:

Operation	Source	Destination
Upload	Local	Remote
Download	Remote	Local

命令行快速开始

上传本地目录到远程服务器。

scp-next upload ./dist /var/www/example \
  --host your-host \
  --username your-username \
  --password your-password \
  --recursive

下载远程文件到本地目录。如果目标目录不存在，scp-next 默认会创建目录。这符合日常 cp 和 scp 风格的使用习惯。可以用 --no-create-directories 关闭该行为。

scp-next download /var/log/example.log ./logs/example.log \
  --host your-host \
  --username your-username \
  --password your-password

先预览上传计划，而不连接服务器。--dry-run 会解析配置并检查本地路径。他不会连接远程服务器，也不会修改本地或远程文件。

scp-next upload ./dist /var/www/example \
  --host your-host \
  --username your-username \
  --password your-password \
  --recursive \
  --dry-run

常用命令选项

选项	作用
`--host <host>`	SSH 服务器地址。
`--port <port>`	SSH 服务器端口，默认值为 `22`。
`--username <username>`	SSH 用户名。
`--password <password>`	SSH 密码。
`--private-key-file <privateKeyFile>`	私钥文件路径，支持 `~`。
`--passphrase <passphrase>`	加密私钥的口令。
`--config <path>`	指定配置文件路径。
`--profile <name>`	选择配置文件中的服务器配置。
`--recursive`	递归传输目录，默认关闭。
`--overwrite`	允许覆盖已有目标文件。
`--create-directories`	创建缺失的目标目录，默认开启。
`--no-create-directories`	关闭目标目录自动创建。
`--dry-run`	只解析和验证，不执行传输。
`--timeout <milliseconds>`	SSH 握手超时时间，单位为毫秒。
`--quiet`	关闭进度和非错误输出。
`--verbose`	输出不含敏感信息的诊断内容。

配置文件用法

CLI 会自动查找以下配置文件。

scp-next.config.json
.scp-nextrc
.scp-nextrc.json

也可以显式指定路径。

scp-next upload ./dist /var/www/example \
  --config ./scp-next.config.json \
  --profile production

下面是一个包含服务器配置和任务的示例。

{
  "profiles": {
    "production": {
      "host": "your-host",
      "username": "your-username",
      "privateKeyFile": "~/.ssh/id_ed25519"
    }
  },
  "jobs": {
    "deploy": {
      "operation": "upload",
      "profile": "production",
      "source": "./dist",
      "destination": "/var/www/example",
      "recursive": true,
      "overwrite": true
    },
    "download-logs": {
      "operation": "download",
      "profile": "production",
      "source": "/var/log/example",
      "destination": "./logs",
      "recursive": true
    }
  }
}

运行配置好的上传任务。

scp-next run deploy

运行配置好的下载任务。

scp-next run download-logs

run 命令也支持临时覆盖路径。

scp-next run deploy ./dist-canary /var/www/canary

配置优先级从高到低如下。

显式 CLI 选项
位置参数
环境变量
选中的配置 profile
根级配置值
配置的 job 值
内部默认值

不要把包含真实密码的配置文件提交到 Public 仓库。共享仓库和部署环境应优先使用 SCP_NEXT_PASSWORD 或受保护的密钥文件。

库 API 用法

ESM 项目可以直接导入 upload。

import { upload } from "scp-next";

await upload({
  host: process.env.SCP_NEXT_HOST,
  username: process.env.SCP_NEXT_USERNAME,
  password: process.env.SCP_NEXT_PASSWORD,
  localPath: "./dist",
  remotePath: "/var/www/example",
  recursive: true,
  overwrite: true
});

CommonJS 项目可以使用 require。

const { download } = require("scp-next");

async function main() {
  await download({
    host: process.env.SCP_NEXT_HOST,
    username: process.env.SCP_NEXT_USERNAME,
    password: process.env.SCP_NEXT_PASSWORD,
    remotePath: "/var/log/example.log",
    localPath: "./logs/example.log"
  });
}

main().catch((error) => {
  console.error(error.message);
  process.exitCode = 1;
});

如果一次连接内要执行多个操作，可以创建可复用客户端。

import { createClient } from "scp-next";

const client = createClient({
  host: process.env.SCP_NEXT_HOST,
  username: process.env.SCP_NEXT_USERNAME,
  password: process.env.SCP_NEXT_PASSWORD
});

try {
  await client.connect();
  await client.upload("./dist", "/var/www/example", { recursive: true });
  await client.download("/var/log/example.log", "./logs/example.log");
} finally {
  await client.close();
}

主要导出如下。

upload(options);
download(options);
createClient(options);
copy(options);

错误类型包含稳定的 code、可读的 message 和经过脱敏的上下文。常见错误包括 ConfigurationError、AuthenticationError、ConnectionError、TransferError 和 HostVerificationError。