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 部署變得如此簡單！🚀