VitePress 宝塔面板部署完全指南 | 自动化静态网站发布教程
VitePress 是 Vue 团队推出的下一代静态站点生成器，而宝塔面板是国内最流行的服务器管理面板。将两者结合，可以让非专业运维人员也能轻松部署高性能的静态网站。本文将详细介绍从零开始的完整部署流程。
1. 部署环境
系统要求
- 服务器系统：CentOS 7+/8+、Ubuntu 20.04+、Debian 10+
- 宝塔面板版本：7.9+（推荐使用最新版）
- 内存要求：建议 2GB+（构建过程需要较多内存）
- 磁盘空间：至少 10GB 可用空间
为什么选择宝塔面板？
| 优势 | 说明 |
|---|---|
| 🎯 图形化界面 | 无需记忆复杂的 Linux 命令 |
| 🔒 一键 SSL | 自动申请和续期 Let's Encrypt 证书 |
| 📦 软件商店 | Node.js、Nginx 等一键安装 |
| ⏰ 计划任务 | 可视化配置自动化构建任务 |
| 📊 资源监控 | 实时监控服务器状态 |
2. 宝塔软件安装
Nginx/Apache
根据个人需求任意安装一个，用于反向代理做域名绑定或80端口访问使用
Nginx vs Apache 选择建议
| 特性 | Nginx | Apache |
|---|---|---|
| 性能 | ⚡⚡⚡ 高并发优秀 | ⚡⚡ 中等 |
| 静态文件 | ✅ 非常适合 | ✅ 适合 |
| 配置复杂度 | 中等 | 简单 |
| 模块生态 | 丰富 | 非常丰富 |
| 推荐场景 | 高流量网站 | 传统应用 |
推荐：对于 VitePress 静态网站，Nginx 是更好的选择，因为它在处理静态文件时性能更优。
Node.js版本管理器
划重点
是Node.js版本管理器，不是PM2管理器
TIP
命令运行版本默认状态是：未设置，这里我们需要选择一下版本，否则后面安装vitepress无法使用命令行模式。
Node.js 版本选择
bash
# 推荐的 Node.js 版本
- Node.js 18.x (LTS) - 稳定可靠
- Node.js 20.x (LTS) - 最新长期支持版本
- Node.js 22.x (Current) - 最新特性
# 查看当前版本
node -v
npm -v版本兼容性：
- VitePress 2.x 需要 Node.js 18.19+ 或 20.6+
- 建议使用 LTS 版本以获得最佳稳定性
3. 开放8080端口
服务器开放端口
宝塔面板开放端口
宝塔面板左侧菜单栏找到【安全】点击进入，填写端口后点击【放行】
【注意】如果服务器8080端口已被占用，可使用其他端口，如：8081等...
端口开放检查
bash
# 检查端口是否被占用
netstat -tuln | grep 8080
# 如果被占用，查找占用进程
lsof -i :8080
# 或者使用其他端口
# 8080, 8081, 8082, 3000, 5173 等防火墙配置
bash
# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload
# Ubuntu/Debian (ufw)
sudo ufw allow 8080/tcp
sudo ufw reload4. 建立网站及运行目录
注意
数据库选择 【不创建】，PHP版本选择【纯静态】
注意
user.ini文件无法被批量删除，就点击文件右侧的删除按钮进行删除
详细配置步骤
4.1 添加站点
- 登录宝塔面板
- 点击左侧菜单【网站】
- 点击【添加站点】
- 填写配置：
- 域名：输入你的域名（如：docs.example.com）
- 根目录：默认即可（如：/www/wwwroot/docs.example.com）
- 数据库：选择【不创建】
- PHP版本：选择【纯静态】
- 备注：可选，用于标识
4.2 清理默认文件
bash
# 进入网站目录
cd /www/wwwroot/你的域名
# 删除默认文件
rm -rf .htaccess .user.ini index.html 404.html
# 验证清理
ls -la4.3 申请 SSL 证书
- 在网站列表中，点击域名右侧的【设置】
- 切换到【SSL】标签页
- 选择【Let's Encrypt】
- 勾选你的域名
- 点击【申请】
- 申请成功后，开启【强制 HTTPS】
SSL 证书优势：
- ✅ 免费自动续期
- ✅ 浏览器信任度高
- ✅ 提升 SEO 排名
- ✅ 保障数据传输安全
5. 命令行部署vitepress
在网站目录下打开宝塔终端并执行以下命令
sh
# 在你的项目中安装
npm add -D vitepress
# 设置向导
npx vitepress init
# 开始写作
npm run docs:dev
# 构建静态文件（一定要构建静态文件，否则域名或IP访问403错误）
npm run docs:build
在网站设置中，重新设置网站目录，定位到：/www/wwwroot/你的网站目录/.vitepress/dist
TIP
注意关闭放跨站攻击
5.1 初始化 VitePress 详解
bash
# 进入网站目录
cd /www/wwwroot/你的域名
# 初始化 package.json（如果还没有）
npm init -y
# 安装 VitePress
npm add -D vitepress
# 运行初始化向导
npx vitepress init初始化向导会询问：
┌ Welcome to VitePress!
│
◇ Where should VitePress initialize the config?
│ ./docs
│
◇ Site title:
│ My Awesome Project
│
◇ Site description:
│ A VitePress Site
│
◇ Root directory:
│ ./docs
│
◇ Use TypeScript for config and theme files?
│ Yes / No
│
◇ Add VitePress npm scripts to package.json?
│ Yes
└ Done! Now run npm run docs:dev and start writing.5.2 项目结构
你的域名/
├── docs/
│ ├── .vitepress/
│ │ ├── config.js # 配置文件
│ │ └── theme/ # 自定义主题
│ ├── index.md # 首页
│ └── guide/ # 文档目录
│ └── getting-started.md
├── package.json
└── package-lock.json5.3 修改网站根目录
- 在宝塔面板中，点击【网站】
- 找到你的站点，点击【设置】
- 切换到【网站目录】标签
- 修改运行目录为：
/.vitepress/dist - 点击【保存】
重要配置：
- ✅ 取消勾选【防跨站攻击(open_basedir)】
- ✅ 确保路径正确：
/www/wwwroot/你的域名/.vitepress/dist
5.4 测试访问
bash
# 本地预览构建结果
cd /www/wwwroot/你的域名
npm run docs:preview
# 或在浏览器访问
# http://你的域名:8080
# https://你的域名 (如果已配置 SSL)6. 关于自动构建静态
1.打开宝塔的【计划任务】 ，新建shell脚本类型计划任务，执行周期根据自己情况设置
（构建静态过程中非常消耗服务器配置，建议最短每天一次，推荐一周一次）
在计划任务中添加 cd /你的网站目录 && npm run docs:build
sh
cd /www/wwwroot/vitepress && npm run docs:build6.1 配置计划任务详解
步骤 1：创建计划任务
- 登录宝塔面板
- 点击左侧菜单【计划任务】
- 点击【添加计划任务】
- 配置如下：
- 任务类型：Shell 脚本
- 任务名称：VitePress 自动构建
- 执行周期：根据需求选择
- N分钟：每 N 分钟执行（测试用）
- N小时：每 N 小时执行
- 每天：每天固定时间执行（推荐）
- 每周：每周固定时间执行（推荐）
- 脚本内容：
bash
#!/bin/bash
# 进入网站目录
cd /www/wwwroot/你的域名
# 清理旧的构建文件
rm -rf .vitepress/dist
# 拉取最新代码（如果使用 Git）
# git pull origin main
# 安装依赖（如果 package.json 有更新）
npm install
# 构建静态文件
npm run docs:build
# 记录日志
echo "VitePress build completed at $(date)" >> /var/log/vitepress-build.log步骤 2：执行周期建议
| 场景 | 推荐周期 | 说明 |
|---|---|---|
| 频繁更新 | 每天凌晨 3:00 | 避开访问高峰 |
| 偶尔更新 | 每周日凌晨 3:00 | 节省服务器资源 |
| 测试阶段 | 每小时 | 快速验证配置 |
| 生产环境 | 手动触发 + Webhook | 按需构建 |
步骤 3：查看执行日志
bash
# 查看计划任务执行日志
cat /var/spool/cron/root
# 查看自定义日志
tail -f /var/log/vitepress-build.log
# 查看宝塔计划任务日志
cat /www/server/panel/logs/cron.log6.2 高级自动化方案
方案 1：Git Webhook 自动触发
bash
# 创建 webhook 接收脚本
cat > /www/wwwroot/你的域名/webhook.sh << 'EOF'
#!/bin/bash
# 验证密钥（可选）
if [ "$1" != "your-secret-key" ]; then
echo "Unauthorized"
exit 1
fi
# 进入项目目录
cd /www/wwwroot/你的域名
# 拉取最新代码
git pull origin main
# 安装依赖
npm install
# 构建
npm run docs:build
# 记录日志
echo "Auto build triggered at $(date)" >> /var/log/vitepress-webhook.log
EOF
# 赋予执行权限
chmod +x webhook.sh方案 2：使用 rsync 同步到多台服务器
bash
# 在主服务器构建后同步到其他服务器
rsync -avz --delete /www/wwwroot/你的域名/.vitepress/dist/ user@server2:/path/to/site/方案 3：CDN 刷新缓存
bash
# 如果使用 CDN，构建后刷新缓存
# 以腾讯云 CDN 为例
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"urls":["https://你的域名/*"]}' \
https://cdn.tencentcloudapi.com/purge7. 性能优化建议
7.1 Nginx 配置优化
nginx
# 在宝塔面板的网站配置中添加
# 启用 Gzip 压缩
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/json application/javascript;
# 浏览器缓存
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
# HTML 文件不缓存
location ~* \.html$ {
expires -1;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}7.2 构建优化
javascript
// .vitepress/config.js
export default {
// 启用预渲染
vite: {
build: {
// 压缩选项
minify: 'terser',
terserOptions: {
compress: {
drop_console: true, // 移除 console.log
drop_debugger: true
}
}
}
}
}7.3 资源优化
bash
# 安装图片优化工具
npm install -D vite-plugin-imagemin
# 在 config.js 中配置
import viteImagemin from 'vite-plugin-imagemin'
export default {
vite: {
plugins: [
viteImagemin({
gifsicle: { optimizationLevel: 7 },
optipng: { optimizationLevel: 7 },
mozjpeg: { quality: 75 },
pngquant: { quality: [0.65, 0.90] }
})
]
}
}8. 常见问题排查
问题 1：403 Forbidden 错误
bash
# 原因：网站根目录配置错误
# 解决方案：
# 1. 确认构建成功
ls -la /www/wwwroot/你的域名/.vitepress/dist
# 2. 检查网站目录设置
# 宝塔面板 -> 网站 -> 设置 -> 网站目录
# 确保指向：/.vitepress/dist
# 3. 关闭防跨站攻击
# 取消勾选 open_basedir问题 2：构建失败 - 内存不足
bash
# 错误：JavaScript heap out of memory
# 解决方案 1：增加 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=4096"
npm run docs:build
# 解决方案 2：升级服务器配置
# 建议至少 2GB 内存
# 解决方案 3：优化构建
# 减少页面数量或使用增量构建问题 3：Node.js 命令找不到
bash
# 错误：command not found: node
# 解决方案：
# 1. 在宝塔面板设置 Node.js 默认版本
# Node.js版本管理器 -> 选择版本 -> 设为默认
# 2. 或在脚本中指定路径
/www/server/nvm/versions/node/v18.19.0/bin/npm run docs:build问题 4：SSL 证书申请失败
bash
# 检查域名解析
ping 你的域名
# 确认 80 端口开放
telnet 你的域名 80
# 重新申请证书
# 宝塔面板 -> 网站 -> SSL -> 重新申请
# 或使用 DNS 验证方式
# 更适合内网或 80 端口被封的情况问题 5：计划任务不执行
bash
# 检查 cron 服务
systemctl status crond
# 查看执行日志
cat /www/server/panel/logs/cron.log
# 手动测试脚本
bash /www/wwwroot/你的域名/build.sh
# 检查脚本权限
chmod +x /www/wwwroot/你的域名/build.sh9. 备份与恢复
9.1 自动备份配置
bash
# 创建备份脚本
cat > /root/backup-vitepress.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/backup/vitepress"
DATE=$(date +%Y%m%d_%H%M%S)
SITE_DIR="/www/wwwroot/你的域名"
# 创建备份目录
mkdir -p $BACKUP_DIR
# 备份网站文件
tar -czf $BACKUP_DIR/site_$DATE.tar.gz -C $SITE_DIR .
# 备份数据库（如果有）
# mysqldump -u root -p database > $BACKUP_DIR/db_$DATE.sql
# 保留最近 7 天的备份
find $BACKUP_DIR -name "site_*.tar.gz" -mtime +7 -delete
echo "Backup completed: $DATE"
EOF
chmod +x /root/backup-vitepress.sh
# 添加到计划任务（每天凌晨 2 点）
0 2 * * * /root/backup-vitepress.sh9.2 快速恢复
bash
# 恢复网站文件
tar -xzf /backup/vitepress/site_20240101_020000.tar.gz -C /www/wwwroot/你的域名
# 重新构建
cd /www/wwwroot/你的域名
npm run docs:build总结
通过宝塔面板部署 VitePress 的优势：
- ✅ 操作简单：图形化界面，无需复杂命令
- ✅ 自动化强：计划任务实现自动构建
- ✅ 安全可靠：一键 SSL，自动续期
- ✅ 易于维护：可视化管理，监控方便
- ✅ 性能优秀：Nginx 静态文件加速
关键步骤回顾：
bash
1. 安装 Node.js 版本管理器
2. 创建纯静态网站
3. 安装并初始化 VitePress
4. 构建静态文件 (npm run docs:build)
5. 设置网站根目录为 .vitepress/dist
6. 配置计划任务自动构建下一步学习：
使用宝塔面板，让 VitePress 部署变得如此简单！🚀