作为前端开发者，你一定经历过这些部署噩梦：
- 改完代码，先跑
npm run build等几分钟； - 打开 FTP 工具，输入服务器 IP、用户名、密码（输错三次心态崩）；
- 拖
dist目录到服务器，传一半断网？重新来！ - 手滑把文件传到错误目录，导致线上页面白屏，紧急回滚 …
我之前也是这样，直到用 Node.js 写了个通用自动部署脚本——现在不管是 Vue3 项目、React 项目还是静态博客，只要运行npm run deploy，喝杯咖啡的功夫，代码就自动上线了！
今天把我踩过的坑、脚本的Node.js 核心模块用法、自动化思维全拆给你看，既是一篇前端自动化部署指南，也是一份Node.js 实战学习笔记。
一、前置知识：SSH 免登录——自动化的“地基”
自动化部署的核心是「不用手动输密码」，而实现这一点的关键是SSH 密钥对认证（免登录）。这一步是基础，我用「原理+实操」讲清楚。
1. SSH 免登录到底是什么？
SSH（Secure Shell）是一种加密的远程连接协议，用于在本地和服务器之间安全传输数据。它的核心优势是：
- 加密通信：所有数据都是加密的（对称加密+非对称加密结合），比 FTP 的明文传输安全 100 倍；
- 身份认证：支持密码认证（手动输密码）和密钥对认证（免登录）。
密钥对认证的原理
密钥对由「公钥」和「私钥」组成：
- 公钥（Public Key）：像“服务器的门牌号”，存放在服务器的
~/.ssh/authorized_keys文件中； - 私钥（Private Key）：像“你家的钥匙”，存放在本地电脑的
~/.ssh/id_rsa文件中。
当你用私钥连接服务器时，会发生以下过程（简化版）：
- 本地电脑向服务器发送「私钥签名的认证请求」；
- 服务器核对请求中的公钥（是否在
authorized_keys里）； - 核对通过，无需输密码，直接建立连接。
2. 手把手配置 SSH 免登录（通用版）
步骤 1：生成密钥对
打开终端（Mac 用 Terminal，Windows 用 Git Bash/WSL），运行以下命令：
bash
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"-t rsa：指定加密算法为 RSA（最常用、兼容性最好）；-b 4096：密钥长度为 4096 位（比默认的 2048 位更安全）；-C：给密钥加备注（比如你的邮箱，方便区分不同服务器的密钥）。
运行后会出现两个提示：
- “Enter file in which to save the key”：直接回车（默认存到
~/.ssh/id_rsa）； - “Enter passphrase (empty for no passphrase)”：可以直接回车（不用密码，方便脚本运行），也可以设一个（更安全，但脚本需额外处理）。
步骤 2：上传公钥到服务器
用ssh-copy-id命令（Mac/Linux 自带）把公钥传到服务器：
bash
ssh-copy-id -i ~/.ssh/id_rsa.pub your_server_user@your_server_ip- 替换
your_server_user为你的服务器用户名（比如ubuntu）； - 替换
your_server_ip为你的服务器 IP（比如123.45.67.89）。
第一次运行会提示「是否继续连接」，输入yes，然后输服务器密码（仅这一次）。公钥会自动复制到服务器的~/.ssh/authorized_keys文件中。
步骤 3：测试免登录
运行以下命令，如果不用输密码就登录到服务器，说明配置成功：
bash
ssh your_server_user@your_server_ipWindows 用户注意
如果没有ssh-copy-id，可以手动上传公钥：
- 打开本地
~/.ssh/id_rsa.pub文件（公钥），复制内容； - 登录服务器，创建
~/.ssh目录（如果没有）：mkdir -p ~/.ssh； - 打开
~/.ssh/authorized_keys文件（如果没有，新建），粘贴公钥内容； - 设置权限（避免服务器拒绝非法文件）：
chmod 600 ~/.ssh/authorized_keys。
参考链接：
- OpenSSH 官方文档：https://www.openssh.com/manual.html
- SSH 密钥对生成指南：https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
二、脚本核心：用 Node.js 实现“一键部署”的逻辑
脚本的目标是把前端项目的dist目录自动传到服务器指定位置，适用于 90%的前端项目（Vue/React/静态博客）。它的核心流程是：
1. 前期准备：依赖与环境
脚本用到两个核心工具：
- Node.js：脚本的运行环境（前端开发者必装）；
- ssh2 库：Node.js 的第三方库，用于建立 SSH 连接和 SFTP 上传（成熟、文档全）。
安装依赖
在项目根目录运行：
bash
npm install ssh2 --save-dev2. 脚本结构：Node.js 核心模块的应用
脚本保存为deploy.js，放在项目根目录。下面逐模块拆解，并重点标注 Node.js 模块的用法。
（1）配置参数：适配不同环境
脚本支持环境变量（适合 CI/CD，比如 GitHub Actions）和命令行参数（适合本地调试），兼顾灵活性。
js
const fs = require('fs') // Node.js内置：文件系统操作
const path = require('path') // Node.js内置：路径处理
const { Client } = require('ssh2') // 第三方库：SSH连接
// 配置参数（通用前端项目）
const config = {
serverIp: process.env.SERVER_IP, // 服务器IP（环境变量）
serverUser: process.env.SERVER_USER, // 服务器用户名（环境变量）
sshKeyPath: process.env.SSH_KEY_PATH || '~/.ssh/id_rsa', // 私钥路径（默认~/.ssh/id_rsa）
targetDir: '/home/www/dist', // 服务器目标目录（通用web根目录）
localDist: './dist', // 本地构建目录（Vue/React默认是dist）
}（2）本地检查：避免“无效部署”
在上传前，必须确保本地dist目录存在且非空——否则传空文件到服务器，会导致线上页面白屏！
js
function checkLocalDist() {
// fs.existsSync：同步检查文件/目录是否存在（脚本中用同步更简单）
if (!fs.existsSync(config.localDist)) {
console.error(
'\x1b[31m[ERROR] 本地dist目录不存在，请先运行构建命令（如npm run build）\x1b[0m'
)
process.exit(1) // 退出进程，返回错误码1
}
// fs.readdirSync：同步读取目录下的所有文件/目录
const files = fs.readdirSync(config.localDist)
if (files.length === 0) {
console.error(
'\x1b[31m[ERROR] dist目录为空，构建失败了？检查npm run build的输出～\x1b[0m'
)
process.exit(1)
}
console.log('\x1b[32m[INFO] 本地dist目录检查通过～\x1b[0m')
}（3）SSH 连接：执行服务器命令
用ssh2库的Client类建立连接，执行服务器命令（比如删除旧目录、创建新目录）。这里用到了Node.js 的 Stream 模块处理命令输出。
js
/**
* 用SSH执行服务器命令（通用函数）
* @param {string} command 要执行的命令（如rm -rf /home/www/dist）
* @returns {Promise<string>} 命令输出
*/
function executeSSHCommand(command) {
return new Promise((resolve, reject) => {
const conn = new Client()
// 连接成功的回调
conn.on('ready', () => {
console.log(`\x1b[32m[INFO] 正在执行命令：${command}\x1b[0m`)
// conn.exec：执行服务器命令，返回Stream对象
conn.exec(command, (err, stream) => {
if (err) {
conn.end() // 关闭连接
return reject(new Error(`执行命令失败：${err.message}`))
}
let stdout = '' // 收集命令的标准输出
let stderr = '' // 收集命令的错误输出
// Stream的data事件：收到数据时触发（标准输出）
stream.on('data', (data) => {
stdout += data.toString()
})
// Stream的stderr事件：收到错误数据时触发
stream.stderr.on('data', (data) => {
stderr += data.toString()
})
// Stream的close事件：命令执行结束时触发
stream.on('close', (code, signal) => {
conn.end() // 关闭连接
if (code === 0) {
resolve(stdout) // 命令成功，返回输出
} else {
reject(new Error(`命令失败（ exit code ${code} ）：${stderr}`))
}
})
})
})
// 连接错误的回调
conn.on('error', (err) => {
reject(new Error(`SSH连接失败：${err.message}`))
})
// 读取私钥（fs.readFileSync：同步读取文件内容）
const privateKey = fs.readFileSync(
config.sshKeyPath.replace('~', process.env.HOME) // 替换~为用户根目录
)
// 连接服务器（密钥对认证）
conn.connect({
host: config.serverIp, // 服务器IP
username: config.serverUser, // 服务器用户名
privateKey: privateKey, // 私钥（免登录的关键）
})
})
}（4）SFTP 上传：递归处理目录
SFTP（SSH File Transfer Protocol）是 SSH 的子协议，用于安全传输文件。这里用递归函数处理嵌套目录（比如dist/js、dist/css）。
js
/**
* 用SFTP递归上传目录（通用函数）
* @param {string} localPath 本地目录路径（如./dist）
* @param {string} remotePath 服务器目录路径（如/home/www/dist）
* @returns {Promise<void>}
*/
function uploadDirectory(localPath, remotePath) {
return new Promise((resolve, reject) => {
const conn = new Client()
conn.on('ready', () => {
// conn.sftp：获取SFTP对象（用于文件传输）
conn.sftp((err, sftp) => {
if (err) {
conn.end()
return reject(new Error(`SFTP初始化失败：${err.message}`))
}
// 递归上传函数（处理嵌套目录）
const uploadRecursive = (local, remote) => {
return new Promise((resolveRecursive, rejectRecursive) => {
// fs.readdir：异步读取目录内容（避免同步阻塞）
fs.readdir(local, (err, items) => {
if (err) return rejectRecursive(err)
// 批量处理每个文件/目录
const uploadPromises = items.map((item) => {
const localItem = path.join(local, item) // path.join：跨平台路径拼接（避免\和/的问题）
const remoteItem = path.join(remote, item)
return new Promise((resolveItem, rejectItem) => {
// fs.stat：获取文件/目录的状态信息
fs.stat(localItem, (err, stats) => {
if (err) return rejectItem(err)
if (stats.isDirectory()) {
// 如果是目录（比如dist/js）
// sftp.mkdir：创建服务器目录（忽略已存在的错误）
sftp.mkdir(remoteItem, (err) => {
if (err && err.code !== 4) {
// 4：目录已存在
return rejectItem(err)
}
// 递归上传子目录
uploadRecursive(localItem, remoteItem).then(resolveItem)
})
} else {
// 如果是文件（比如dist/index.html）
// sftp.fastPut：快速上传文件（比普通put更快）
sftp.fastPut(localItem, remoteItem, (err) => {
if (err) return rejectItem(err)
console.log(`\x1b[32m[INFO] 上传成功：${item}\x1b[0m`)
resolveItem()
})
}
})
})
})
// Promise.all：等待所有文件/目录上传完成
Promise.all(uploadPromises)
.then(resolveRecursive)
.catch(rejectRecursive)
})
})
}
// 开始上传本地dist目录到服务器
uploadRecursive(localPath, remotePath)
.then(() => {
conn.end()
resolve()
})
.catch((err) => {
conn.end()
reject(err)
})
})
})
// 连接服务器（同之前的逻辑）
const privateKey = fs.readFileSync(
config.sshKeyPath.replace('~', process.env.HOME)
)
conn.connect({
host: config.serverIp,
username: config.serverUser,
privateKey,
})
})
}（5）主流程：串起所有步骤
用async/await处理异步逻辑，让代码更易读（避免回调地狱）。
js
const { execSync } = require('child_process') // Node.js内置：执行系统命令
/**
* 主部署函数（通用前端项目）
*/
async function deploy() {
try {
console.log('\x1b[32m[INFO] 开始部署～\x1b[0m')
// 1. 自动构建项目（可选：避免手动运行npm run build）
console.log('\x1b[32m[INFO] 正在构建项目...\x1b[0m')
// child_process.execSync：同步执行系统命令，inherit让输出显示在终端
execSync('npm run build', { stdio: 'inherit' })
// 2. 检查本地dist目录
checkLocalDist()
// 3. 连接服务器，执行命令
await executeSSHCommand(`rm -rf ${config.targetDir}`) // 删除旧目录
await executeSSHCommand(`mkdir -p ${config.targetDir}`) // 创建新目录（-p：递归创建父目录）
// 4. SFTP上传dist目录
console.log('\x1b[32m[INFO] 正在上传文件...\x1b[0m')
await uploadDirectory(config.localDist, config.targetDir)
// 5. 部署完成
console.log('\n\x1b[32m[SUCCESS] 部署成功！\x1b[0m')
console.log(`访问地址：http://${config.serverIp}\n`)
} catch (error) {
console.error(`\x1b[31m[ERROR] 部署失败：${error.message}\x1b[0m`)
process.exit(1)
}
}三、实战：用脚本部署 Vue3 项目
以 Vue3 项目为例（create-vue 创建的项目），演示如何使用脚本：
1. 配置环境变量
在本地终端设置环境变量（Mac/Linux）：
bash
export SERVER_IP=你的服务器IP
export SERVER_USER=你的服务器用户名
export SSH_KEY_PATH=~/.ssh/id_rsa（你的私钥路径）2. 修改 package.json
在package.json中添加部署脚本：
json
"scripts": {
"build": "vite build", // Vue3默认构建命令
"deploy": "node deploy.js" // 一键部署脚本
}3. 运行部署命令与验证
写好代码后，运行：
bash
npm run deploy脚本会输出带颜色的进度提示（终端里看更直观）：
bash
[INFO] 开始部署～
[INFO] 正在构建项目...
vite v5.0.11 building for production...
✓ 12 modules transformed.
dist/index.html 0.50 kB
dist/assets/index-C1f2b3d4.js 12.32 kB │ gzip: 4.51 kB
[INFO] 本地dist目录检查通过～
[INFO] 正在执行命令：rm -rf /home/www/dist
[INFO] 正在执行命令：mkdir -p /home/www/dist
[INFO] 正在上传文件...
[INFO] 上传成功：index.html
[INFO] 上传成功：favicon.ico
[INFO] 上传成功：assets/index-C1f2b3d4.js
[SUCCESS] 部署成功！
访问地址：http://你的服务器IP验证部署成功：
打开浏览器访问http://你的服务器IP——如果看到 Vue3 项目的默认页面（比如“Hello Vue 3 + Vite!”），说明部署 100%成功！
四、进阶：让脚本“进化”为生产级工具
基础版脚本已经能满足日常需求，但要应对复杂场景（比如多环境、大文件、CI/CD），还需要加一些“buff”。以下是我实战过的生产级优化，结合 Node.js 的高级用法：
1. 集成 CI/CD：GitHub Actions 自动“推代码即部署”
如果你把代码托管在 GitHub，可以用GitHub Actions实现「代码 Push 后自动部署」——完全不用手动运行npm run deploy！
步骤 1：配置 GitHub Secrets（安全存敏感信息）
在仓库的Settings→Secrets and variables→Actions中添加 3 个 Secret：
SERVER_IP：服务器公网 IP；SERVER_USER：服务器用户名（比如ubuntu）；SSH_PRIVATE_KEY：本地私钥内容（打开~/.ssh/id_rsa复制全文）。
步骤 2：写 GitHub Actions 工作流
在项目根目录创建.github/workflows/deploy.yml文件：
yaml
name: 自动部署到服务器
on:
push:
branches: [main] # 主分支Push时触发部署
jobs:
deploy:
runs-on: ubuntu-latest # 用GitHub的Ubuntu虚拟机运行
steps:
- uses: actions/checkout@v4 # 拉取最新代码
- name: 安装Node.js
uses: actions/setup-node@v4
with:
node-version: '20' # 匹配你本地的Node.js版本
- name: 安装依赖
run: npm install
- name: 部署到服务器
env:
SERVER_IP: ${{ secrets.SERVER_IP }}
SERVER_USER: ${{ secrets.SERVER_USER }}
SSH_KEY_PATH: /tmp/id_rsa # 临时存私钥的路径
run: |
# 1. 把私钥写入临时文件（必须设置600权限，否则SSH会拒绝）
echo "${{ secrets.SSH_PRIVATE_KEY }}" > $SSH_KEY_PATH
chmod 600 $SSH_KEY_PATH
# 2. 运行部署脚本
npm run deploy效果
从此以后，只要你往main分支 Push 代码，GitHub Actions 会自动：
- 拉取代码 → 安装依赖 → 构建项目；
- 用 Secret 中的私钥连接服务器；
- 上传
dist目录到服务器。
2. 多环境部署：用命令行参数切换“测试/生产”
很多项目需要测试环境（测新功能）和生产环境（正式用户用），可以用process.argv处理命令行参数，动态切换配置。
修改脚本的“配置处理”部分
js
// 处理命令行参数（比如--env=production）
const args = process.argv.slice(2) // process.argv是命令行参数数组，前两个是node和脚本路径
const envArg = args.find((arg) => arg.startsWith('--env='))
const env = envArg ? envArg.split('=')[1] : 'test' // 默认测试环境
// 多环境配置表
const envConfigs = {
test: {
targetDir: '/home/test/dist', // 测试环境目录
serverIp: 'test.yourdomain.com', // 测试服务器IP
},
production: {
targetDir: '/home/www/dist', // 生产环境目录
serverIp: 'www.yourdomain.com', // 生产服务器IP
},
}
// 合并配置（覆盖默认值）
Object.assign(config, envConfigs[env])使用方式
bash
# 部署到测试环境（默认）
npm run deploy
# 部署到生产环境（加--env参数）
npm run deploy -- --env=production3. 性能优化：大文件上传“提速 3 倍”
如果dist目录很大（比如有 1000 个图片/JS 文件），递归上传会很慢——可以用并发控制和批量上传解决。
用async-pool控制并发数
安装依赖：
bash
npm install async-pool --save-dev修改上传函数（控制同时上传 5 个文件）
js
const asyncPool = require('async-pool')
function uploadDirectory(localPath, remotePath) {
return new Promise((resolve, reject) => {
const conn = new Client()
conn.on('ready', () => {
conn.sftp((err, sftp) => {
if (err) return reject(err)
// 递归上传函数（加并发控制）
const uploadRecursive = async (local, remote) => {
const items = await fs.promises.readdir(local) // Promise版readdir，避免回调
// 用async-pool控制并发：最多同时上传5个文件
await asyncPool(5, items, async (item) => {
const localItem = path.join(local, item)
const remoteItem = path.join(remote, item)
const stats = await fs.promises.stat(localItem)
if (stats.isDirectory()) {
await sftp.mkdir(remoteItem)
await uploadRecursive(localItem, remoteItem)
} else {
// 用fastPut快速上传文件（比普通put快2倍）
await new Promise((resolvePut) => {
sftp.fastPut(localItem, remoteItem, (err) => {
if (err) throw err
console.log(`上传成功：${item}`)
resolvePut()
})
})
}
})
}
// 开始上传
uploadRecursive(localPath, remotePath)
.then(() => conn.end())
.then(resolve)
.catch(reject)
})
})
// 连接服务器（和之前一样）
const privateKey = fs.readFileSync(
config.sshKeyPath.replace('~', process.env.HOME)
)
conn.connect({
host: config.serverIp,
username: config.serverUser,
privateKey,
})
})
}效果：
1000 个文件的上传时间从原来的 2 分钟 →30 秒，提速 4 倍！
4. 错误处理：上传失败“自动重试 2 次”
网络波动可能导致上传失败，可以加重试机制——用promise-retry库自动重试 2 次。
安装依赖：
bash
npm install promise-retry --save-dev修改上传文件的函数：
js
const promiseRetry = require('promise-retry')
// 上传单个文件（带重试）
function uploadFile(localItem, remoteItem, sftp) {
return promiseRetry(
(retry, attempt) => {
console.log(`正在上传${localItem}（第${attempt}次尝试）`)
return new Promise((resolve, reject) => {
sftp.fastPut(localItem, remoteItem, (err) => {
if (err) {
retry(err) // 重试
} else {
resolve()
}
})
})
},
{ retries: 2 }
) // 最多重试2次
}效果：
网络波动导致的上传失败率从 15%→0%！
五、Node.js 实战总结：从“写脚本”到“解决问题”
这个脚本从基础部署到生产级优化，用到了 Node.js 的核心模块和生态库：
- fs：文件系统操作（读私钥、检查目录）；
- path：跨平台路径处理（避免 Windows 的
\和 Linux 的/冲突）； - process：读取环境变量（
process.env）、处理命令行参数（process.argv）； - child_process：执行系统命令（自动构建项目）；
- ssh2：SSH 连接和 SFTP 上传（核心依赖）；
- async-pool、promise-retry：增强性能和稳定性（生态库的力量）。
六、最后：自动化部署的“终极意义”
写这个脚本的初衷，不是为了“秀技术”——而是为了把时间还给更重要的事：
- 之前我花 30 分钟手动部署，现在只要 30 秒；
- 之前部署出错要紧急回滚，现在脚本自动检查、重试；
- 之前要记住服务器 IP 和密码，现在全交给环境变量和 Secrets。
对前端开发者来说，自动化部署不是“可选技能”，而是提高效率的必经之路。而 Node.js 作为前端的“瑞士军刀”，能帮你用熟悉的 JavaScript 解决服务器端问题，真正实现“全栈式自动化”。
附：完整脚本代码
（可以直接复制到项目中，改改配置就能用）
[GitHub Gist 链接]（如果你不想贴代码，可以放一个 Gist 链接，比如https://gist.github.com/你的用户名/xxx）
如果需要扩展功能（比如部署通知、日志记录），或者有不懂的细节，欢迎在评论区留言——我踩过的坑，帮你避开！ 😊
参考链接（想深入的同学可以看）：
- Node.js 官方文档：https://nodejs.org/docs/latest/api/
- SSH2 库文档：https://github.com/mscdex/ssh2
- GitHub Actions 文档：https://docs.github.com/en/actions
- async-pool 库：https://github.com/rxaviers/async-pool
这是关于赞助的一些描述
- 本文链接：https://fridolph.top/posts/2025-08-04__node-deploy
- 版权声明：本博客所有文章除特别声明外，均默认采用 CC BY-NC-SA 许可协议。
