外观
VuePress 部署脚本和 Nginx 配置详解
本文档详细介绍 VuePress 博客项目中的核心部署工具:deploy.sh 自动化部署脚本和 nginx.conf.example Nginx 配置文件。通过本文档,你将了解这些工具的工作原理、使用方法以及如何根据实际需求进行定制。
deploy.sh 部署脚本详解
deploy.sh 是一个自动化部署脚本,用于将本地构建的 VuePress 博客项目部署到远程 Linux 服务器。
功能特性
- ✅ 自动构建项目:自动执行
pnpm install和pnpm docs:build - ✅ SSH 私钥支持:支持使用 SSH 私钥进行安全认证
- ✅ 自动检测环境:自动检测并安装服务器上的 rsync
- ✅ 增量同步:使用 rsync 进行增量同步,只上传更改的文件
- ✅ 自动清理:自动清理服务器上的旧文件
- ✅ 错误处理:完善的错误检查和提示信息
使用方法
基本用法
# 基本格式
./deploy.sh [server_user@server_host:/path/to/deploy] [--key /path/to/private_key]
# 示例 1:使用 SSH 私钥部署
./deploy.sh user@your-server-ip:/var/www/vuepress-blog --key ~/.ssh/id_rsa
# 示例 2:使用环境变量指定私钥(推荐)
export SSH_KEY_PATH=~/.ssh/id_rsa
./deploy.sh user@your-domain.com:/var/www/vuepress-blog
# 示例 3:只构建不部署(不提供服务器地址)
./deploy.sh参数说明
| 参数 | 说明 | 是否必需 | 示例 |
|---|---|---|---|
server_user@server_host:/path/to/deploy | 服务器地址和部署路径 | 否 | user@your-server-ip:/var/www/vuepress-blog |
--key /path/to/private_key | SSH 私钥文件路径 | 否 | --key ~/.ssh/id_rsa |
参数格式说明:
server_user:服务器用户名(如root、ubuntu、www-data等,请替换为实际用户名)server_host:服务器 IP 地址或域名(如192.168.x.x或your-domain.com,请替换为实际地址)/path/to/deploy:服务器上的目标路径,通常是 Nginx 配置的root目录--key:SSH 私钥文件路径(如果服务器需要私钥访问)
工作流程
脚本执行流程如下:
1. 检查依赖(pnpm、rsync)
↓
2. 安装项目依赖(pnpm install)
↓
3. 构建项目(pnpm docs:build)
↓
4. 检查构建产物是否存在
↓
5. 如果指定了部署目标:
├─ 检查服务器 SSH 连接
├─ 检查服务器 rsync 是否安装(未安装则自动安装)
├─ 使用 rsync 上传构建产物
└─ 验证部署结果详细功能说明
1. 自动构建
脚本会自动执行以下构建步骤:
# 安装依赖
pnpm install
# 构建项目(构建产物在 docs/.vuepress/dist 目录)
pnpm docs:build构建产物默认位于 docs/.vuepress/dist 目录。
2. SSH 私钥处理
如果指定了 SSH 私钥,脚本会:
- 检查私钥文件是否存在
- 自动设置私钥文件权限为 600(rsync 要求)
- 使用私钥进行 SSH 连接
# 脚本内部处理
chmod 600 "$SSH_KEY_PATH"
SSH_CMD="ssh -i $SSH_KEY_PATH -o StrictHostKeyChecking=no"3. 自动安装 rsync
如果服务器未安装 rsync,脚本会自动尝试安装:
# 自动检测系统类型并安装
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y rsync
# CentOS/RHEL
sudo yum install -y rsync
# Fedora
sudo dnf install -y rsync如果自动安装失败,脚本会提供详细的手动安装说明。
4. 增量同步
使用 rsync 进行增量同步,具有以下优势:
- 只上传更改的文件:提高部署速度
- 自动清理旧文件:使用
--delete参数 - 排除不需要的文件:自动排除
.git和node_modules - 压缩传输:使用
-z参数压缩传输数据
rsync -avz --delete \
--exclude='.git' \
--exclude='node_modules' \
"$LOCAL_DIST/" "$DEPLOY_TARGET"环境变量配置
支持通过环境变量配置:
# 设置 SSH 私钥路径
export SSH_KEY_PATH=~/.ssh/id_rsa
# 运行部署脚本(请替换 user 和 server 为实际值)
./deploy.sh user@your-server-ip:/var/www/vuepress-blog错误处理
脚本包含完善的错误处理机制:
- 依赖检查:检查 pnpm 和 rsync 是否安装
- 构建验证:检查构建产物是否存在
- SSH 连接测试:验证服务器连接
- 权限检查:检查私钥文件权限
- 部署验证:检查部署是否成功
常见问题
Q1: 提示 "pnpm 未安装"
解决: 安装 pnpm
npm install -g pnpmQ2: 提示 "SSH 私钥文件不存在"
解决: 检查私钥路径是否正确
# 检查私钥文件
ls -la ~/.ssh/id_rsa
# 如果不存在,生成新的 SSH 密钥对
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"Q3: 提示 "无法自动安装 rsync"
解决: 手动在服务器上安装 rsync
# SSH 登录服务器(请替换 user 和 server 为实际值)
ssh -i ~/.ssh/id_rsa user@your-server-ip
# 安装 rsync
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install rsync
# CentOS/RHEL
sudo yum install rsyncQ4: 部署后文件权限不正确
解决: 在服务器上设置正确的文件权限
# SSH 登录服务器(请替换 user 和 server 为实际值)
ssh -i ~/.ssh/id_rsa user@your-server-ip
# 设置权限
sudo chown -R www-data:www-data /var/www/vuepress-blog
sudo chmod -R 755 /var/www/vuepress-blog完整脚本代码
以下是 deploy.sh 的完整源代码,你可以复制并保存为 deploy.sh 文件:
#!/bin/bash
# VuePress 博客部署脚本
#
# 使用方法:
# ./deploy.sh [server_user@server_host:/path/to/deploy] [--key /path/to/private_key]
#
# 参数说明:
# server_user: 服务器用户名(如 root, ubuntu, www-data 等)
# server_host: 服务器 IP 地址或域名(请替换为实际地址)
# /path/to/deploy: 服务器上的目标路径,通常是 Nginx 配置的 root 目录
# 例如: /var/www/vuepress-blog
# --key: SSH 私钥文件路径(可选,如果服务器需要私钥访问)
#
# 示例:
# ./deploy.sh user@your-server-ip:/var/www/vuepress-blog
# ./deploy.sh user@your-domain.com:/var/www/blog --key ~/.ssh/id_rsa
# ./deploy.sh user@your-server-ip:/var/www/vuepress-blog --key /path/to/server_key
#
# 环境变量方式(推荐):
# export SSH_KEY_PATH=~/.ssh/id_rsa
# ./deploy.sh user@your-server-ip:/var/www/vuepress-blog
#
# 注意:
# - 如果不提供参数,脚本只会构建项目,不会上传到服务器
# - 如果服务器配置了 SSH 密钥(在 ~/.ssh/config 中),可能不需要指定私钥
set -e # 遇到错误立即退出
# 颜色输出
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# 配置(可以通过参数覆盖)
DEPLOY_TARGET=""
SSH_KEY_PATH="${SSH_KEY_PATH:-}"
LOCAL_DIST="docs/.vuepress/dist"
# 解析命令行参数
while [[ $# -gt 0 ]]; do
case $1 in
--key)
SSH_KEY_PATH="$2"
shift 2
;;
*)
if [ -z "$DEPLOY_TARGET" ]; then
DEPLOY_TARGET="$1"
fi
shift
;;
esac
done
# 打印带颜色的消息
print_info() {
echo -e "${GREEN}[INFO]${NC} $1"
}
print_warn() {
echo -e "${YELLOW}[WARN]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# 检查命令是否存在
check_command() {
if ! command -v $1 &> /dev/null; then
print_error "$1 未安装,请先安装 $1"
exit 1
fi
}
# 构建项目
build_project() {
print_info "开始构建项目..."
# 检查 pnpm 是否安装
check_command pnpm
# 安装依赖
print_info "安装依赖..."
pnpm install
# 构建项目
print_info "构建项目..."
pnpm docs:build
# 检查构建是否成功
if [ ! -d "$LOCAL_DIST" ]; then
print_error "构建失败:找不到 dist 目录"
exit 1
fi
print_info "构建完成!"
}
# 部署到服务器
deploy_to_server() {
if [ -z "$DEPLOY_TARGET" ]; then
print_warn "未指定部署目标,跳过部署步骤"
print_info "构建产物位于: $LOCAL_DIST"
print_info "如需部署,请使用: ./deploy.sh user@host:/path/to/deploy"
return
fi
print_info "准备部署到服务器..."
# 检查 rsync 是否安装
check_command rsync
# 解析部署目标
if [[ ! "$DEPLOY_TARGET" =~ ^[^@]+@[^:]+:.+$ ]]; then
print_error "部署目标格式错误,应为: user@host:/path/to/deploy"
exit 1
fi
# 构建 SSH 命令(用于检查服务器环境)
SSH_CMD="ssh"
if [ -n "$SSH_KEY_PATH" ]; then
if [ ! -f "$SSH_KEY_PATH" ]; then
print_error "SSH 私钥文件不存在: $SSH_KEY_PATH"
exit 1
fi
# 设置私钥文件权限(rsync 要求私钥文件权限为 600)
chmod 600 "$SSH_KEY_PATH" 2>/dev/null || true
SSH_CMD="ssh -i $SSH_KEY_PATH -o StrictHostKeyChecking=no"
print_info "使用 SSH 私钥: $SSH_KEY_PATH"
else
# 检查是否在 ~/.ssh/config 中配置了密钥
print_info "未指定 SSH 私钥,使用默认 SSH 配置"
fi
# 检查服务器上是否安装了 rsync
print_info "检查服务器环境..."
SERVER_USER_HOST=$(echo "$DEPLOY_TARGET" | sed 's|:.*||')
if ! $SSH_CMD "$SERVER_USER_HOST" "command -v rsync" &>/dev/null; then
print_warn "服务器上未安装 rsync"
print_info "正在尝试自动安装 rsync(需要 sudo 权限)..."
# 尝试自动安装 rsync(需要 sudo 权限,可能需要密码)
INSTALL_SUCCESS=false
# 尝试 Ubuntu/Debian
if $SSH_CMD "$SERVER_USER_HOST" "sudo apt-get update && sudo apt-get install -y rsync" 2>&1 | grep -q "rsync is already"; then
INSTALL_SUCCESS=true
elif $SSH_CMD "$SERVER_USER_HOST" "sudo apt-get update && sudo apt-get install -y rsync" &>/dev/null 2>&1; then
INSTALL_SUCCESS=true
fi
# 尝试 CentOS/RHEL
if [ "$INSTALL_SUCCESS" = false ] && $SSH_CMD "$SERVER_USER_HOST" "sudo yum install -y rsync" &>/dev/null 2>&1; then
INSTALL_SUCCESS=true
fi
# 尝试 Fedora
if [ "$INSTALL_SUCCESS" = false ] && $SSH_CMD "$SERVER_USER_HOST" "sudo dnf install -y rsync" &>/dev/null 2>&1; then
INSTALL_SUCCESS=true
fi
if [ "$INSTALL_SUCCESS" = false ]; then
print_error ""
print_error "无法自动安装 rsync,请手动在服务器上安装:"
print_error ""
print_error " 方法一:SSH 登录服务器后执行:"
print_error " Ubuntu/Debian: sudo apt-get update && sudo apt-get install rsync"
print_error " CentOS/RHEL: sudo yum install rsync"
print_error " Fedora: sudo dnf install rsync"
print_error ""
print_error " 方法二:使用以下命令一键安装:"
print_error " $SSH_CMD $SERVER_USER_HOST 'sudo apt-get update && sudo apt-get install -y rsync'"
print_error " 或"
print_error " $SSH_CMD $SERVER_USER_HOST 'sudo yum install -y rsync'"
print_error ""
print_error "安装完成后,请重新运行部署脚本"
exit 1
else
print_info "rsync 安装成功 ✓"
fi
else
print_info "服务器已安装 rsync ✓"
fi
# 构建 rsync 命令参数
RSYNC_ARGS=(-avz --delete --exclude='.git' --exclude='node_modules')
# 如果指定了 SSH 私钥,添加到 rsync 命令中
if [ -n "$SSH_KEY_PATH" ]; then
RSYNC_ARGS+=(-e "$SSH_CMD")
fi
# 上传到服务器
print_info "上传文件到服务器: $DEPLOY_TARGET"
rsync "${RSYNC_ARGS[@]}" "$LOCAL_DIST/" "$DEPLOY_TARGET"
if [ $? -eq 0 ]; then
print_info "部署成功!"
else
print_error "部署失败!"
exit 1
fi
}
# 主函数
main() {
print_info "=== VuePress 博客部署脚本 ==="
# 构建项目
build_project
# 部署到服务器(如果指定了目标)
deploy_to_server
print_info "=== 部署完成 ==="
}
# 运行主函数
main💡 使用提示:将上述代码保存为
deploy.sh文件后,需要添加执行权限:chmod +x deploy.sh
nginx.conf.example 配置文件详解
nginx.conf.example 是 Nginx 配置文件的模板,提供了 VuePress 博客的最佳实践配置。
配置文件结构
配置文件包含以下主要部分:
- HTTP 服务器配置:监听 80 端口
- 静态资源缓存:优化静态资源加载
- Gzip 压缩:减少传输大小
- 安全头设置:提升安全性
- HTTPS 配置示例:SSL/TLS 配置(注释状态)
关键配置说明
1. 基本服务器配置
server {
listen 80;
server_name your-domain.com; # 修改为你的域名或 IP 地址
# 构建产物路径(根据实际部署路径修改)
root /var/www/vuepress-blog/docs/.vuepress/dist;
index index.html;
}配置项说明:
listen 80:监听 80 端口(HTTP)server_name:服务器名称,可以是域名或 IP 地址root:网站根目录,指向 VuePress 构建产物目录index:默认首页文件
2. Vue Router History 模式支持
location / {
try_files $uri $uri/ /index.html;
}这个配置非常重要,用于支持 Vue Router 的 history 模式。当访问 /blog/article 这样的路由时,Nginx 会先尝试查找对应的文件,如果不存在则返回 index.html,由前端路由处理。
3. 静态资源缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
access_log off;
}配置说明:
expires 1y:设置缓存时间为 1 年Cache-Control "public, immutable":告诉浏览器这些资源不会改变,可以永久缓存access_log off:不记录静态资源的访问日志,减少日志文件大小
优势:
- 减少服务器负载
- 提升页面加载速度
- 节省带宽
4. 禁止访问隐藏文件
location ~ /\. {
deny all;
access_log off;
log_not_found off;
}防止访问 .git、.env 等隐藏文件,提升安全性。
5. Gzip 压缩
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_comp_level 6;
gzip_types
text/plain
text/css
text/xml
text/javascript
application/x-javascript
application/xml+rss
application/javascript
application/json
application/xml
image/svg+xml;配置说明:
gzip on:启用 Gzip 压缩gzip_vary on:添加 Vary 头,支持代理缓存gzip_min_length 1024:只压缩大于 1024 字节的文件gzip_comp_level 6:压缩级别(1-9,6 是平衡点)gzip_types:指定需要压缩的文件类型
效果:
- 减少 60-80% 的传输大小
- 显著提升页面加载速度
6. 安全头设置
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;安全头说明:
X-Frame-Options:防止页面被嵌入到 iframe 中(防止点击劫持)X-Content-Type-Options:防止 MIME 类型嗅探X-XSS-Protection:启用浏览器 XSS 过滤器
使用方法
步骤 1:复制配置文件
# 从本地上传到服务器(请替换 user 和 server 为实际值)
scp -i ~/.ssh/id_rsa nginx.conf.example user@your-server-ip:/tmp/nginx.conf.example步骤 2:修改配置
SSH 登录服务器后,编辑配置文件:
# SSH 登录(请替换 user 和 server 为实际值)
ssh -i ~/.ssh/id_rsa user@your-server-ip
# 复制到 Nginx 配置目录
# Ubuntu/Debian
sudo cp /tmp/nginx.conf.example /etc/nginx/sites-available/vuepress-blog
# CentOS/RHEL
sudo cp /tmp/nginx.conf.example /etc/nginx/conf.d/vuepress-blog.conf
# 编辑配置文件
sudo nano /etc/nginx/sites-available/vuepress-blog
# 或
sudo nano /etc/nginx/conf.d/vuepress-blog.conf必须修改的配置项:
server_name:改为你的域名或 IP 地址server_name your-domain.com; # 或 your-server-iproot:改为实际的构建产物路径root /var/www/vuepress-blog/docs/.vuepress/dist;
步骤 3:启用配置
Ubuntu/Debian 系统:
# 创建软链接启用站点
sudo ln -s /etc/nginx/sites-available/vuepress-blog /etc/nginx/sites-enabled/
# 删除默认配置(可选)
sudo rm /etc/nginx/sites-enabled/default 2>/dev/null || trueCentOS/RHEL/Fedora 系统:
这些系统不使用 sites-available 和 sites-enabled,配置文件直接放在 /etc/nginx/conf.d/ 目录即可。
步骤 4:测试并重启
# 测试配置文件语法
sudo nginx -t
# 如果测试通过,重新加载配置
sudo systemctl reload nginx
# 检查状态
sudo systemctl status nginxHTTPS 配置
配置文件末尾包含了 HTTPS 配置示例(注释状态)。使用 Let's Encrypt 配置 HTTPS 后,可以取消注释并修改相关配置。
使用 Certbot 自动配置 HTTPS
# 安装 Certbot
sudo apt-get update
sudo apt-get install certbot python3-certbot-nginx
# 自动配置 HTTPS(会自动修改 Nginx 配置)
sudo certbot --nginx -d your-domain.comCertbot 会自动:
- 获取 SSL 证书
- 修改 Nginx 配置
- 设置 HTTP 到 HTTPS 的重定向
- 配置自动续期
性能优化建议
启用 HTTP/2:在 HTTPS 配置中添加
http2listen 443 ssl http2;调整缓存策略:根据实际需求调整静态资源缓存时间
使用 CDN:将静态资源托管到 CDN,进一步加速
启用 Brotli 压缩:比 Gzip 压缩率更高(需要额外配置)
日志文件
配置文件指定了日志文件位置:
access_log /var/log/nginx/vuepress-blog-access.log;
error_log /var/log/nginx/vuepress-blog-error.log;查看日志:
# 查看访问日志
sudo tail -f /var/log/nginx/vuepress-blog-access.log
# 查看错误日志
sudo tail -f /var/log/nginx/vuepress-blog-error.log完整配置文件代码
以下是 nginx.conf.example 的完整源代码,你可以复制并保存为 nginx.conf.example 文件:
# Nginx 配置文件示例
#
# 使用方法:
#
# 1. 安装 Nginx(如果未安装):
# Ubuntu/Debian: sudo apt-get update && sudo apt-get install nginx
# CentOS/RHEL: sudo yum install nginx
# Fedora: sudo dnf install nginx
#
# 2. 复制此文件到服务器:
# scp nginx.conf.example user@your-server-ip:/etc/nginx/sites-available/vuepress-blog
# 或在服务器上: sudo cp nginx.conf.example /etc/nginx/sites-available/vuepress-blog
#
# 3. 编辑配置文件,修改 server_name 和 root 路径:
# sudo nano /etc/nginx/sites-available/vuepress-blog
#
# 4. 创建软链接启用站点(Ubuntu/Debian):
# sudo ln -s /etc/nginx/sites-available/vuepress-blog /etc/nginx/sites-enabled/
# 注意: CentOS/RHEL 可能不需要软链接,直接放在 /etc/nginx/conf.d/ 目录
#
# 5. 删除默认配置(可选,避免冲突):
# sudo rm /etc/nginx/sites-enabled/default
#
# 6. 测试配置:
# sudo nginx -t
#
# 7. 重启 Nginx:
# sudo systemctl restart nginx
# 或重新加载配置(不中断服务): sudo systemctl reload nginx
server {
listen 80;
server_name your-domain.com; # 修改为你的域名或 IP 地址
# 构建产物路径(根据实际部署路径修改)
root /var/www/vuepress-blog/docs/.vuepress/dist;
index index.html;
# 日志文件
access_log /var/log/nginx/vuepress-blog-access.log;
error_log /var/log/nginx/vuepress-blog-error.log;
# 支持 Vue Router 的 history 模式
location / {
try_files $uri $uri/ /index.html;
}
# 静态资源缓存(1年)
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
access_log off;
}
# 禁止访问隐藏文件
location ~ /\. {
deny all;
access_log off;
log_not_found off;
}
# Gzip 压缩
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_comp_level 6;
gzip_types
text/plain
text/css
text/xml
text/javascript
application/x-javascript
application/xml+rss
application/javascript
application/json
application/xml
image/svg+xml;
# 安全头
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
}
# HTTPS 配置(使用 Let's Encrypt 后会自动添加)
# server {
# listen 443 ssl http2;
# server_name your-domain.com;
#
# ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
# ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
#
# # SSL 配置
# ssl_protocols TLSv1.2 TLSv1.3;
# ssl_ciphers HIGH:!aNULL:!MD5;
# ssl_prefer_server_ciphers on;
#
# # 其他配置与 HTTP 相同
# root /var/www/vuepress-blog/docs/.vuepress/dist;
# index index.html;
#
# location / {
# try_files $uri $uri/ /index.html;
# }
#
# # ... 其他配置
# }
#
# # HTTP 重定向到 HTTPS
# server {
# listen 80;
# server_name your-domain.com;
# return 301 https://$server_name$request_uri;
# }💡 使用提示:将上述配置保存为
nginx.conf.example文件后,记得修改server_name和root路径以匹配你的实际环境。
最佳实践
部署流程
- 本地开发:在本地开发和测试
- 构建部署:使用
deploy.sh一键部署 - 配置 Nginx:首次部署需要配置 Nginx
- 验证访问:检查网站是否正常访问
- 配置 HTTPS:使用 Let's Encrypt 配置 HTTPS
安全建议
- 使用 SSH 私钥:避免使用密码登录
- 设置文件权限:确保文件权限正确
- 定期更新:保持系统和软件更新
- 配置防火墙:只开放必要的端口
- 启用 HTTPS:使用 SSL/TLS 加密传输
维护建议
- 定期备份:备份构建产物和配置文件
- 监控日志:定期检查 Nginx 日志
- 性能监控:监控服务器资源使用情况
- 更新部署:使用
deploy.sh定期更新内容
总结
deploy.sh 和 nginx.conf.example 是 VuePress 博客部署的核心工具:
- deploy.sh:自动化部署流程,简化部署操作
- nginx.conf.example:提供最佳实践的 Nginx 配置
通过合理使用这些工具,可以:
- ✅ 简化部署流程
- ✅ 提升网站性能
- ✅ 增强安全性
- ✅ 降低维护成本
相关资源:
贡献者
更新日志
2025/11/21 09:32
查看所有更新日志
d0c9b-docs(blog): 更新三篇技术分享文章的创建时间于f3af2-docs(blog): 添加 VuePress 博客部署完整指南和技术详解于
版权所有
版权归属:ntzw
许可证:CC0 1.0 通用 (CC0)
