Webpack 构建后如何自动部署？用 scp2 和 rsync 一键传输文件到服务器

前端项目每次发布都要经历打包、打开FTP工具、手动拖拽dist目录到服务器这套流程，操作繁琐不说，还经常因为忘记删旧文件或者漏传某个目录导致线上版本异常。其实Webpack本身支持在构建生命周期的末尾执行自定义逻辑，完全可以把上传这一步自动化，打包完成后自动把产物推送到服务器，一条命令完成从构建到上线的全过程。

目前主流的自动上传方案有两种：一种是通过scp2这个Node库，用JavaScript代码控制SSH文件传输，跨平台兼容性好；另一种是在构建完成后调用系统的rsync命令做增量同步，传输效率高，特别适合文件数量多的项目。两种方案各有适用场景，下面分别展开讲。

方案一：使用 scp2 插件实现构建后自动上传

scp2是一个基于ssh2封装的Node.js库，提供了简洁的异步API来执行SFTP传输。它的最大优势是不依赖服务器和本机的任何命令行工具，只要Node环境能跑，Windows、macOS、Linux都能正常工作，对于团队里有Windows同事的项目来说非常友好。

安装方式很简单，由于部署属于开发期操作，建议安装在devDependencies中：

npm install scp2 --save-dev

scp2本身不与Webpack直接集成，通常配合一个自定义插件来触发。Webpack提供了afterEmit或done钩子，前者在文件输出到磁盘后触发，后者在整个构建完全结束后触发。用afterEmit可以更早开始上传，缩短整体等待时间。下面是一个完整的自定义插件实现：

const Client = require('scp2').Client;

function DeployPlugin(options) {
  this.options = options;
}

DeployPlugin.prototype.apply = function (compiler) {
  compiler.hooks.afterEmit.tapAsync('DeployPlugin', (compilation, callback) => {
    const client = new Client();
    // options中包含host、username、password、path等配置
    client.scp('./dist', this.options, (err) => {
      if (err) {
        console.error('部署失败：', err);
        process.exit(1);
      } else {
        console.log('部署完成，文件已上传到服务器');
      }
      callback();
    });
  });
};

module.exports = DeployPlugin;

在webpack.config.js中引入并配置即可。服务器地址、账号等敏感信息不要写死在代码里提交到仓库，推荐放到环境变量或者本地的配置文件中：

const DeployPlugin = require('./DeployPlugin');

module.exports = {
  // ...其他配置
  plugins: [
    new DeployPlugin({
      host: '192.168.0.100',
      port: 22,
      username: 'deploy',
      password: process.env.DEPLOY_PASSWORD,
      path: '/var/www/html/my-app'
    })
  ]
};

需要注意scp2默认是全量上传，每次都会把dist目录整个推过去。如果服务器上保留了日志文件或其他非构建产物，直接覆盖目录可能造成误删，建议在服务器上单独划一个部署目录，通过Nginx指向该目录，避免构建产物与其他文件混在一起。

方案二：使用 rsync 做增量同步，速度更快

rsync是Linux世界经典的数据同步工具，它会对比源目录和目标目录的文件差异，只传输有变化的部分，对于每次构建只改动少量文件的前端项目来说，上传时间可以从几分钟缩短到几秒钟。它的缺点是Windows原生环境没有rsync命令，需要借助WSL、Git Bash或者cwRsync等工具。

在Node环境中可以通过child_process执行rsync命令，同样封装成Webpack插件的形式：

const { exec } = require('child_process');

function RsyncPlugin(options) {
  this.options = options;
}

RsyncPlugin.prototype.apply = function (compiler) {
  compiler.hooks.done.tap('RsyncPlugin', (stats) => {
    if (stats.hasErrors()) {
      console.error('构建存在错误，跳过部署');
      return;
    }
    // -a 保留属性 -v 显示详情 -z 压缩传输 --delete 删除目标端多余文件
    const cmd = `rsync -avz --delete ${this.options.source} ${this.options.user}@${this.options.host}:${this.options.dest}`;
    exec(cmd, { stdio: 'inherit' }, (err) => {
      if (err) {
        console.error('rsync部署失败：', err);
        process.exit(1);
      }
      console.log('rsync增量同步完成');
    });
  });
};

module.exports = RsyncPlugin;

其中--delete参数会让目标目录与本地dist完全一致，服务器上多出来的文件会被删除，这个行为要谨慎使用，确认部署目录里只有构建产物再开启。还有一点容易被忽略：rsync默认会在每次构建时生成带时间戳的新哈希文件名的js和css文件，旧版本文件如果没有清理，服务器上会积累大量历史文件，占用磁盘空间，可以配合--delete或在服务器端写定时清理脚本来处理。

如果想省去手写命令的麻烦，也可以直接使用社区的webpack-rsync-plugin等现成插件，配置项大同小异，原理都是一样的。

免密登录配置与安全性建议

无论用哪种方案，都建议使用SSH密钥认证代替密码认证。密码写明文既不安全，也容易在换密码后导致部署脚本批量失效。配置方法是在本机生成密钥对，然后把公钥追加到服务器的authorized_keys文件里：

# 本机生成密钥对（如果已有可跳过）
ssh-keygen -t rsa -b 4096

# 把公钥上传到服务器
ssh-copy-id deploy@192.168.0.100

# 验证免密登录是否生效
ssh deploy@192.168.0.100 "echo ok"

配置完成后，scp2的连接选项中改用privateKey字段指定私钥路径，rsync则直接免密执行，CI/CD环境中部署脚本不会再卡在交互式输入密码这一步。另外建议为部署创建专用系统账号，通过sshd配置限制其权限，只允许写入部署目录，即使密钥泄露也能把损失控制在最小范围。

在多环境场景下，可以在npm scripts中区分开发和生产目标，配合cross-env传递环境变量：

{
  "scripts": {
    "build": "webpack --mode production",
    "deploy:test": "webpack --mode production --env target=test",
    "deploy:prod": "webpack --mode production --env target=prod"
  }
}

总的来说，如果团队以Windows环境为主、项目体积不大，scp2方案零依赖开箱即用；如果项目构建产物大、文件多，且服务器或本机具备rsync条件，增量同步带来的速度提升非常明显。把部署逻辑固化到Webpack构建流程中之后，发布就简化成执行一条npm命令，出问题的概率也随之大幅降低，这是每个前端团队都值得做的一次小改造。

Webpack自动部署scp2rsync修改时间：2026-09-03 19:36:08