本文档详细介绍如何从本地开发环境将 VuePress 博客项目部署到 Linux 服务器，包括 SSH 配置、自动化部署脚本使用、Nginx 配置以及常见问题排查。

前置要求

本地环境要求

• Node.js 18+ 和 pnpm（或 npm/yarn）
• Git
• SSH 客户端
• 服务器 SSH 访问权限

服务器环境要求

• Linux 服务器（Ubuntu/CentOS/Debian 等）
• Nginx（或其他 Web 服务器）
• rsync（用于文件同步，部署脚本会自动检测并安装）

💡 提示：部署脚本会自动处理大部分服务器端配置，你只需要确保服务器已安装 Nginx 和开放 SSH 访问。

快速开始

使用部署脚本一键部署：

# 使用 SSH 私钥部署（请替换 user 和 your-server 为实际值）
./deploy.sh user@your-server-ip:/var/www/vuepress-blog --key ~/.ssh/id_rsa

# 或使用环境变量
export SSH_KEY_PATH=~/.ssh/id_rsa
./deploy.sh user@your-server-ip:/var/www/vuepress-blog

部署脚本会自动完成：

• ✅ 本地构建项目
• ✅ 上传构建产物到服务器
• ✅ 支持 SSH 私钥认证
• ✅ 自动检测并安装服务器上的 rsync
• ✅ 增量同步（只上传更改的文件）
• ✅ 自动清理服务器上的旧文件

💡 提示：本文档提供快速部署指南。如需深入了解 deploy.sh 脚本和 nginx.conf.example 配置文件的详细使用方法，请参考 VuePress 部署脚本和 Nginx 配置详解。

详细部署步骤

第一步：配置 SSH 私钥访问

如果服务器需要通过 SSH 私钥访问，需要先配置：

1.1 确保私钥文件权限正确

chmod 600 ~/.ssh/id_rsa

1.2 测试 SSH 连接

# 请替换 user 和 your-server 为实际值
ssh -i ~/.ssh/id_rsa user@your-server-ip

1.3 确保服务器上已添加公钥

# 查看本地公钥
cat ~/.ssh/id_rsa.pub

# 在服务器上添加到 authorized_keys
# 方法一：使用 ssh-copy-id（推荐，请替换 user 和 your-server 为实际值）
ssh-copy-id -i ~/.ssh/id_rsa.pub user@your-server-ip

# 方法二：手动添加
# ssh user@server
# echo "你的公钥内容" >> ~/.ssh/authorized_keys
# chmod 600 ~/.ssh/authorized_keys

第二步：使用部署脚本部署项目

在项目根目录运行部署脚本：

# 使用 SSH 私钥部署（请替换 user 和 your-server 为实际值）
./deploy.sh user@your-server-ip:/var/www/vuepress-blog --key ~/.ssh/id_rsa

# 或使用环境变量
export SSH_KEY_PATH=~/.ssh/id_rsa
./deploy.sh user@your-server-ip:/var/www/vuepress-blog

部署脚本会自动完成：

• ✅ 在本地构建项目（pnpm docs:build）
• ✅ 使用 rsync 上传构建产物到服务器
• ✅ 自动检测并安装服务器上的 rsync（如果未安装）
• ✅ 增量同步（只上传更改的文件）
• ✅ 自动清理服务器上的旧文件

📖 详细说明：想了解更多关于 deploy.sh 脚本的使用方法、参数说明和工作原理？请查看 VuePress 部署脚本和 Nginx 配置详解。

第三步：配置 Nginx

3.1 确保服务器已安装 Nginx

如果服务器未安装 Nginx，需要先安装：

Ubuntu/Debian 系统：

# 请替换 user 和 your-server 为实际值
ssh -i ~/.ssh/id_rsa user@your-server-ip
sudo apt-get update
sudo apt-get install -y nginx
sudo systemctl start nginx
sudo systemctl enable nginx

CentOS/RHEL 系统：

# 请替换 user 和 your-server 为实际值
ssh -i ~/.ssh/id_rsa user@your-server-ip
sudo yum install -y nginx
sudo systemctl start nginx
sudo systemctl enable nginx

3.2 从本地上传 Nginx 配置文件

使用 scp 手动上传

# 上传配置文件到服务器临时目录（请替换 user 和 your-server 为实际值）
scp -i ~/.ssh/id_rsa nginx.conf.example user@your-server-ip:/tmp/nginx.conf.example

📖 配置详解：想了解 Nginx 配置文件的详细说明、每个配置项的作用以及性能优化建议？请查看 VuePress 部署脚本和 Nginx 配置详解。

3.3 在服务器上配置 Nginx

SSH 登录服务器后，执行以下操作：

手动配置步骤：

1. 复制配置文件到 Nginx 配置目录

   Ubuntu/Debian 系统：

   sudo cp /tmp/nginx.conf.example /etc/nginx/sites-available/vuepress-blog
   sudo ln -s /etc/nginx/sites-available/vuepress-blog /etc/nginx/sites-enabled/
   sudo rm /etc/nginx/sites-enabled/default 2>/dev/null || true

   CentOS/RHEL/Fedora 系统：

   sudo cp /tmp/nginx.conf.example /etc/nginx/conf.d/vuepress-blog.conf
   sudo rm /etc/nginx/conf.d/default.conf 2>/dev/null || true

2. 编辑配置文件

   需要修改以下两个关键配置：

   • server_name：改为你的域名或 IP 地址
   • root：改为你的构建产物路径（通常是 /var/www/vuepress-blog/docs/.vuepress/dist）

   # Ubuntu/Debian
   sudo nano /etc/nginx/sites-available/vuepress-blog
   
   # CentOS/RHEL
   sudo nano /etc/nginx/conf.d/vuepress-blog.conf

   配置文件示例：

   server {
       listen 80;
       server_name your-domain.com;  # ← 修改这里
   
       root /var/www/vuepress-blog/docs/.vuepress/dist;  # ← 修改这里
       index index.html;
   
       location / {
           try_files $uri $uri/ /index.html;
       }
   
       location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
           expires 1y;
           add_header Cache-Control "public, immutable";
       }
   
       gzip on;
       gzip_vary on;
       gzip_min_length 1024;
       gzip_types text/plain text/css text/xml text/javascript 
                  application/x-javascript application/xml+rss 
                  application/javascript application/json;
   }

3. 测试并重启 Nginx

   # 测试配置文件语法
   sudo nginx -t
   
   # 如果测试通过，重新加载配置
   sudo systemctl reload nginx
   
   # 检查状态
   sudo systemctl status nginx

4. 配置防火墙（如果需要）

   # Ubuntu/Debian
   sudo ufw allow 'Nginx Full'
   
   # CentOS/RHEL
   sudo firewall-cmd --permanent --add-service=http
   sudo firewall-cmd --reload

常见问题排查

1. 网站显示 500 错误

快速排查：

# 1. 查看 Nginx 错误日志（最重要！）
sudo tail -f /var/log/nginx/error.log

# 2. 检查构建产物是否存在
ls -la /var/www/vuepress-blog/docs/.vuepress/dist

# 3. 检查文件权限
ls -ld /var/www/vuepress-blog/docs/.vuepress/dist

常见原因和解决方案：

原因 1: 构建产物路径不存在或为空

解决： 在本地重新部署

# 在本地重新运行部署脚本（请替换 user 和 your-server 为实际值）
./deploy.sh user@your-server-ip:/var/www/vuepress-blog --key ~/.ssh/id_rsa

原因 2: 文件权限问题

# Ubuntu/Debian
sudo chown -R www-data:www-data /var/www/vuepress-blog
sudo chmod -R 755 /var/www/vuepress-blog

# CentOS/RHEL
sudo chown -R nginx:nginx /var/www/vuepress-blog
sudo chmod -R 755 /var/www/vuepress-blog

原因 3: SELinux 权限问题（CentOS/RHEL）

# 检查 SELinux 状态
getenforce

# 如果显示 Enforcing，设置 SELinux 上下文
sudo chcon -R -t httpd_sys_content_t /var/www/vuepress-blog

原因 4: Nginx 配置中的 root 路径错误

# 检查配置文件中的 root 路径
sudo cat /etc/nginx/conf.d/vuepress-blog.conf | grep root

# 修改配置文件
sudo nano /etc/nginx/conf.d/vuepress-blog.conf
# 确保 root 路径正确
sudo nginx -t && sudo systemctl reload nginx

2. Nginx 服务未运行

错误： nginx.service is not active, cannot reload

解决：

# 启动 Nginx
sudo systemctl start nginx

# 检查状态
sudo systemctl status nginx

# 设置开机自启
sudo systemctl enable nginx

3. rsync 未安装

错误： rsync: 未找到命令

解决：

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install rsync

# CentOS/RHEL
sudo yum install rsync

# Fedora
sudo dnf install rsync

💡 提示：部署脚本会自动检测并尝试安装 rsync。

4. 配置文件测试失败

错误： nginx: [emerg] open() "/var/www/vuepress-blog/docs/.vuepress/dist" failed

原因： 构建产物路径不存在

解决：

# 检查路径是否存在
ls -la /var/www/vuepress-blog/docs/.vuepress/dist

# 如果不存在，需要先构建项目
cd /var/www/vuepress-blog
pnpm install
pnpm docs:build

5. 页面 404 错误

• 确保 Nginx 配置中包含 try_files $uri $uri/ /index.html;
• 检查构建产物是否正确上传
• 检查部署路径是否与 Nginx 配置的 root 路径一致

6. 无法访问网站

检查清单：

• Nginx 是否运行：sudo systemctl status nginx
• 防火墙是否开放 80 端口
• 服务器安全组是否开放 80 端口（云服务器）
• 域名 DNS 是否解析正确（如果使用域名）
• 查看 Nginx 错误日志：sudo tail -f /var/log/nginx/error.log

配置 HTTPS（可选，推荐）

部署完成后，建议配置 HTTPS 以提升安全性。使用 Let's Encrypt 免费 SSL 证书：

# SSH 登录服务器（请替换 user 和 your-server 为实际值）
ssh -i ~/.ssh/id_rsa user@your-server-ip

# 安装 Certbot
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install certbot python3-certbot-nginx

# CentOS/RHEL
sudo yum install certbot python3-certbot-nginx

# 获取证书（替换为你的域名）
sudo certbot --nginx -d your-domain.com

# 测试自动续期
sudo certbot renew --dry-run

配置完成后，Nginx 会自动重定向 HTTP 到 HTTPS，并自动续期证书。

更新部署

当博客内容更新后，只需在本地重新运行部署脚本即可：

# 从本地更新（会自动构建并上传，请替换 user 和 your-server 为实际值）
./deploy.sh user@your-server-ip:/var/www/vuepress-blog --key ~/.ssh/id_rsa

部署脚本会自动：

• 在本地构建最新代码
• 增量同步到服务器（只上传更改的文件）
• 清理服务器上的旧文件

💡 提示：如果修改了 Nginx 配置，需要 SSH 登录服务器手动重新加载配置：sudo systemctl reload nginx

性能优化建议

1. 启用 Nginx 缓存：对静态资源设置长期缓存
2. 使用 CDN：将静态资源托管到 CDN
3. 启用 Gzip/Brotli 压缩：减少传输大小
4. 使用 HTTP/2：提升加载性能

监控和维护

• 定期检查 Nginx 日志：/var/log/nginx/access.log 和 /var/log/nginx/error.log
• 监控服务器资源使用情况
• 定期备份构建产物和配置文件

总结

本文档详细介绍了从本地将 VuePress 博客部署到 Linux 服务器的完整流程，包括：

1. ✅ SSH 私钥配置和测试
2. ✅ 使用自动化部署脚本一键部署
3. ✅ Nginx 配置和优化
4. ✅ 常见问题排查和诊断
5. ✅ 更新部署流程

核心部署流程：

# 1. 配置 SSH 私钥
chmod 600 ~/.ssh/id_rsa
# 请替换 user 和 your-server 为实际值
ssh -i ~/.ssh/id_rsa user@your-server-ip

# 2. 一键部署（请替换 user 和 your-server 为实际值）
./deploy.sh user@your-server-ip:/var/www/vuepress-blog --key ~/.ssh/id_rsa

# 3. 配置 Nginx（首次部署）
# 上传配置文件（请替换 user 和 your-server 为实际值）
scp -i ~/.ssh/id_rsa nginx.conf.example user@your-server-ip:/tmp/nginx.conf.example
# SSH 登录服务器后手动配置（详见第三步）
ssh -i ~/.ssh/id_rsa user@your-server-ip

# 4. 更新部署（后续，请替换 user 和 your-server 为实际值）
./deploy.sh user@your-server-ip:/var/www/vuepress-blog --key ~/.ssh/id_rsa

按照本文档的步骤，你应该能够成功从本地部署 VuePress 博客到服务器。如果遇到问题，请参考常见问题部分或使用项目提供的诊断脚本。

---

相关资源：

• VuePress 部署脚本和 Nginx 配置详解 - 深入了解 deploy.sh 和 nginx.conf.example 的使用方法
• VuePress 官方文档
• Nginx 官方文档
• 项目部署脚本说明

贡献者

ntzw

更新日志

2025/11/21 09:32

查看所有更新日志

• d0c9b-docs(blog): 更新三篇技术分享文章的创建时间于 2025/11/21
• f3af2-docs(blog): 添加 VuePress 博客部署完整指南和技术详解于 2025/11/21

版权所有

版权归属：ntzw

许可证：CC0 1.0 通用 (CC0)