搬瓦工部署 VitePress 文档站教程

VitePress 是基于 Vite 和 Vue 3 的静态站点生成器，专为技术文档设计。它是 VuePress 的精神继承者，拥有更快的构建速度和更现代的开发体验。VitePress 生成的静态页面加载极快，非常适合部署在搬瓦工 VPS 上。本文将介绍完整的部署流程。购买搬瓦工 VPS 请参考全部方案，使用优惠码 NODESEEK2026 可享受 6.77% 的折扣。

一、安装 Node.js

apt update && apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs git
node -v && npm -v

二、创建 VitePress 项目

mkdir -p /opt/mydocs && cd /opt/mydocs
npm init -y
npm install vitepress --save-dev
npx vitepress init

初始化向导会引导你设置项目结构、标题和主题等基本配置。

2.1 项目结构

# 典型的 VitePress 项目结构
# /opt/mydocs/
#   docs/
#     .vitepress/
#       config.mts
#     index.md
#     guide/
#       getting-started.md
#   package.json

2.2 配置文件

cat > /opt/mydocs/docs/.vitepress/config.mts << 'EOF'
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: "项目文档",
  description: "使用 VitePress 搭建的技术文档",
  lang: 'zh-CN',
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/getting-started' },
      { text: 'API', link: '/api/' }
    ],
    sidebar: [
      {
        text: '指南',
        items: [
          { text: '快速开始', link: '/guide/getting-started' },
          { text: '安装配置', link: '/guide/installation' },
          { text: '基本用法', link: '/guide/basic-usage' }
        ]
      }
    ],
    socialLinks: [
      { icon: 'github', link: 'https://github.com/your-org' }
    ],
    search: {
      provider: 'local'
    },
    footer: {
      message: '基于 VitePress 构建',
      copyright: 'Copyright 2026'
    }
  }
})
EOF

三、编写文档

mkdir -p /opt/mydocs/docs/guide

cat > /opt/mydocs/docs/index.md << 'EOF'
---
layout: home
hero:
  name: "项目文档"
  text: "简洁高效的技术文档"
  tagline: 使用 VitePress 构建
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/getting-started
    - theme: alt
      text: API 参考
      link: /api/
features:
  - title: 快速
    details: 基于 Vite 构建，毫秒级热更新
  - title: 简洁
    details: 以 Markdown 为核心，专注内容创作
  - title: 可定制
    details: 基于 Vue 3，可灵活扩展
---
EOF

cat > /opt/mydocs/docs/guide/getting-started.md << 'EOF'
# 快速开始

本节介绍如何快速上手使用本项目。

## 前提条件

- Node.js 18 或更高版本
- 基本的命令行操作知识

## 安装

按照以下步骤完成安装和初始配置。
EOF

四、构建与部署

4.1 添加构建脚本

# 在 package.json 中添加脚本
npm pkg set scripts.docs:dev="vitepress dev docs"
npm pkg set scripts.docs:build="vitepress build docs"
npm pkg set scripts.docs:preview="vitepress preview docs"

4.2 构建

npm run docs:build

构建产物在 docs/.vitepress/dist/ 目录中。

4.3 Nginx 部署

apt install nginx -y

cat > /etc/nginx/sites-available/vitepress.conf << 'EOF'
server {
    listen 80;
    server_name docs.yourdomain.com;
    root /opt/mydocs/docs/.vitepress/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
}
EOF

ln -sf /etc/nginx/sites-available/vitepress.conf /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl restart nginx

五、SSL 与自动部署

apt install certbot python3-certbot-nginx -y
certbot --nginx -d docs.yourdomain.com

# 自动部署脚本
cat > /opt/mydocs/deploy.sh << 'EOF'
#!/bin/bash
cd /opt/mydocs
git pull origin main
npm install
npm run docs:build
echo "[$(date)] VitePress deployed"
EOF
chmod +x /opt/mydocs/deploy.sh

六、常见问题

构建失败

确认 Node.js 版本 >= 18。VitePress 需要较新的 Node.js 运行时。使用 node -v 检查版本。

路由 404

VitePress 默认使用静态路由，Nginx 需要配置 try_files 以支持直接访问子路径。确保配置了 try_files $uri $uri/ /index.html。

总结

VitePress 是 Vue 生态中最优秀的文档站生成器，构建速度快、界面美观。在搬瓦工 VPS 上部署非常简便。其他文档工具还有 MkDocs、Docusaurus 等。购买搬瓦工 VPS 请访问 bwh81.net，使用优惠码 NODESEEK2026 可享受 6.77% 的折扣。