Lue Jiang

Appearance

VitePress 部署教程 ​

本文记录如何将 VitePress 部署到自己的 Ubuntu 服务器，实现 Git 推送自动部署。

Requirements ​

  • 一台公网服务器(安装了 Nginx)
  • 一个域名(DNS 已经指向服务器 IP)

第一步：安装 Node.js ​

由于服务器无法访问 raw.githubusercontent.com，这里手动下载官方二进制包：

bash
# 进入临时目录
cd /tmp

# 下载 Node.js 20 LTS 二进制包（官方源）
wget https://nodejs.org/dist/v20.12.2/node-v20.12.2-linux-x64.tar.xz
tar -xf node-v20.12.2-linux-x64.tar.xz
sudo mv node-v20.12.2-linux-x64 /usr/local/nodejs

添加到 PATH，这里我的 shell 用的是 fish

bash
# 手动编辑配置文件：
mkdir -p ~/.config/fish
echo 'set -gx PATH /usr/local/nodejs/bin $PATH' >> ~/.config/fish/config.fish
# 或者直接用永久设置：
# fish -c 'set -Ux PATH /usr/local/nodejs/bin $PATH'

验证安装

bash
node -v
npm -v

第二步：配置用户权限 ​

创建部署目录

bash
# 创建网站根目录
sudo mkdir -p /var/www/<你的域名>

# 修改目录所有者
sudo chown -R <你的用户名>:<你的用户名> /var/www/<你的域名>

第三步：配置 Git 自动部署 ​

编辑 Git 裸仓库的 hook 文件

bash
# 编辑 post-receive 脚本
vim <你的git仓库绝对路径>/hooks/post-receive

添加以下内容：

bash
#!/bin/bash

# VitePress 自动部署脚本

GIT_DIR=<你的git仓库绝对路径>
WORK_TREE=/tmp/blog-build
DEPLOY_DIR=/var/www/<你的域名>

echo "===== 开始部署 ====="

# 检出代码到临时目录
mkdir -p $WORK_TREE
git --work-tree=$WORK_TREE --git-dir=$GIT_DIR checkout -f main

cd $WORK_TREE

echo "安装依赖..."
npm ci

echo "构建中..."
npm run build

# 检查构建是否成功
if [ ! -d "$WORK_TREE/docs/.vitepress/dist" ]; then
    echo "构建失败！"
    exit 1
fi

echo "同步到部署目录..."
rsync -av --delete $WORK_TREE/docs/.vitepress/dist/ $DEPLOY_DIR/

# 设置正确权限
chmod -R 755 $DEPLOY_DIR

echo "===== 部署完成 ====="
echo "网站已更新: https://<你的域名>"

赋予执行权限

bash
chmod +x <你的git仓库绝对路径>/hooks/post-receive

第四步：配置 Nginx ​

创建站点配置文件

bash
sudo vim /etc/nginx/sites-available/<你的域名>

添加以下内容：

nginx
server {
    listen 80;
    server_name <你的域名>;

    # 网站根目录
    root /var/www/<你的域名>;
    index index.html;

    # 允许 Let's Encrypt 验证（必须在其他 location 之前）
    location ^~ /.well-known/acme-challenge/ {
        allow all;
        default_type "text/plain";
        root /var/www/<你的域名>;
    }

    # Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    # 静态文件缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|otf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    # 所有路由指向 index.html（支持前端路由 + VitePress cleanUrls）
    location / {
        # 关键修复：添加 $uri.html 以支持 cleanUrls
        # 顺序：原始路径 → .html后缀 → 目录 → index.html
        try_files $uri $uri.html $uri/ /index.html;
    }
    # 404 页面
    error_page 404 /404.html;
}
# HTTPS 配置（如果已启用 Let's Encrypt）
server {
    listen 443 ssl http2;
    server_name <你的域名>;
    ssl_certificate /etc/letsencrypt/live/<你的域名>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/<你的域名>/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    root /var/www/<你的域名>;
    index index.html;
    location ^~ /.well-known/acme-challenge/ {
        allow all;
        default_type "text/plain";
        root /var/www/<你的域名>;
    }
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|otf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
    location / {
        try_files $uri $uri.html $uri/ /index.html;
    }
    error_page 404 /404.html;
}

启用站点

bash
# 创建软链接
sudo ln -s /etc/nginx/sites-available/<你的域名> /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 重载 Nginx
sudo systemctl reload nginx

检查防火墙，确保 80 端口开放

bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

第六步：本地推送测试 ​

在本地项目目录提交并推送到服务器

bash
git commit

git push origin main

推送时会自动触发 post-receive 钩子，看到类似输出说明部署成功：

===== 开始部署 =====
安装依赖...
构建中...
同步到部署目录...
===== 部署完成 =====
网站已更新: <你的域名>

第五步：配置 HTTPS（Let's Encrypt） ​

安装 Certbot

bash
sudo apt update
sudo apt install -y certbot python3-certbot-nginx

申请证书

bash
# 自动配置 HTTPS
sudo certbot --nginx -d 1634.ltd
# 按提示操作：输入邮箱、同意协议、选择是否重定向到 HTTPS（建议选 2：全部重定向）

Let's Encrypt 证书有效期 90 天，Certbot 会自动配置续期任务。验证续期：

bash
sudo certbot renew --dry-run

打开浏览器访问：

  • HTTP: http://<你的域名>
  • HTTPS: https://<你的域名>

参考 ​