首先来了解 scp-next 这个包。虽然名称中包含 SCP，但其底层实际采用 SFTP 协议，不会为了普通文件传输而执行远程 Shell 命令。它同时提供命令行工具和程序库，专用于通过 SSH 实现安全的文件传输。对于 Node.js 开发者来说，这是一个开箱即用的方案。

适合哪些用户

如果你需要在部署脚本、CI 流程或 Node.js 应用中传输文件，scp-next 能帮你减少重复封装工作。常见的应用场景包括：将本地构建产物上传到远程服务器、从服务器下载日志或构建产物、通过配置文件管理不同服务器环境、在应用代码中复用同一个传输客户端实例。

安装方式

如果希望全局使用命令行工具：

npm install --global scp-next

如果需要在项目代码中调用 API，则作为项目依赖安装：

npm install scp-next

当然，也可以将它安装到项目依赖中，然后通过 npx scp-next 或 npm scripts 来调用，灵活性很高。

先理解传输方向

命令行统一使用 两个位置参数：

scp-next upload   [options]
scp-next download   [options]
scp-next run  [source] [destination] [options]

方向规则非常直观：

命令行快速上手

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

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

它会解析配置并检查本地路径，但不会连接远程服务器，也不会修改任何文件。

推荐的凭据写法

命令行密码参数适合本地快速试用：

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

但在共享环境和生产环境下，更推荐使用环境变量。这样可以降低密码进入 Shell 历史记录或进程列表的风险：

export SCP_NEXT_HOST="your-host"
export SCP_NEXT_USERNAME="your-username"
export SCP_NEXT_PASSWORD="your-password"
scp-next upload ./dist /var/www/example --recursive

也可以使用受保护的私钥文件：

scp-next upload ./dist /var/www/example --host your-host --username your-username --private-key-file ~/.ssh/id_ed25519 --recursive

常用命令选项

配置文件用法

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 值 → 内部默认值。

有一点需要特别注意：不要把包含真实密码的配置文件提交到公共仓库。共享仓库和部署环境应优先使用 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。

主机验证

scp-next 支持通过 hostFingerprint 或 knownHostsFile 验证主机。如果没有显式配置，它会读取 ~/.ssh/known_hosts。

在 CI 或部署环境中，如果没有可用的 known-hosts 文件，建议配置 hostFingerprint。如果无法建立主机验证，scp-next 会失败退出，安全性上做得比较到位。

新人接手清单

接手项目时，按以下顺序验证会比较顺畅：

• 确认 Node.js 版本不低于 18.18.0。
• 使用 npm install --global scp-next 安装 CLI。
• 用 scp-next upload ... --dry-run 验证参数和路径。

掌握这几项后，就可以把 scp-next 用于日常部署脚本、日志下载任务和 Node.js 文件传输流程中了。