VitePress个人博客搭建

一、环境准备与项目初始化

1. 安装 Node.js 确保 Node.js 版本 ≥ 18，可通过 node -v 验证版本。

2. 创建项目目录

   mkdir vitepress-blog && cd vitepress-blog
   npm init -y  # 或使用 pnpm init

3. 安装 VitePress

   npm install -D vitepress  # 或 pnpm add -D vitepress

4. 初始化项目结构

   npx vitepress init

---

二、目录结构与基础配置

1. 文件结构

vitepress-blog/
├── docs/
│   ├── .vitepress/        # 配置和主题文件
│   │   └─ config.mts      # 主配置文件
│   ├── public/            # 静态资源（图片、图标等）
│   ├── index.md           # 首页
│   └── posts/             # 博客文章目录
└── package.json

2. 核心配置 (docs/.vitepress/config.mts)

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: '技术博客',          // 网站标题
  description: '个人技术博客', // SEO 描述
  head: [['link', { rel: 'icon', href: '/favicon.ico' }]], // 网站图标
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '归档', link: '/archives' }
    ],
    sidebar: [
      {
        text: '指南',
        items: [
          { text: '快速开始', link: '/guide/' },
          { text: '写作规范', link: '/guide/writing-rules' }
        ]
      }
    ],
    socialLinks: [{ icon: 'github', link: 'https://github.com/yourusername' }]
  }
})

• 导航栏与侧边栏：通过 nav 和 sidebar 配置菜单结构1618。
• 静态资源：图片等文件需放在 public 目录，通过 /image.png 引用13。

---

三、首页与文章编写

1. 定制首页 (docs/index.md)

---
layout: home
title: 我的技术博客
hero:
  name: 技术成长之路
  text: 记录 | 分享 | 成长
  image:
    src: /logo.png
  actions:
    - theme: brand
      text: 开始阅读
      link: /posts/
features:
  - title: 技术专题
    details: 前端框架、工程化等深度解析
---

2. 文章规范(参照)

• 文章存放在 posts 目录，推荐按日期命名（如 2024-03-02-first-post.md）。
• 支持 Markdown 扩展语法（代码块、表格、自定义容器等）1518。

---

四、本地开发与构建

1. 启动开发服务器

   npm run docs:dev  # 访问 http://localhost:5173

2. 构建生产文件

   npm run docs:build  # 生成静态文件到 docs/.vitepress/dist

---

五、部署到服务器

方案一：GitHub Pages

1. 创建 GitHub 仓库 仓库名格式为 <username>.github.io（个人页）或普通仓库。

2. 配置 GitHub Actions 创建 .github/workflows/deploy.yml：

   name: Deploy to GitHub Pages
   on:
     push:
       branches: [main]
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: pnpm/action-setup@v2  # 安装 pnpm
         - uses: actions/setup-node@v3
           with:
             node-version: 18
         - run: pnpm install && pnpm build
         - uses: peaceiris/actions-gh-pages@v3
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: docs/.vitepress/dist

3. 启用 GitHub Pages 在仓库设置中选择 gh-pages 分支作为发布源。

方案二：自有服务器部署 (本站使用的方案)

博主使用的是Ubuntu22.04系统，若有不同，请自行修改对应指令

服务器使用的是阿里云的2G2核，大家可自行到各大厂商找到适合自己的服务器

1. 将 dist 目录上传至服务器（如 Nginx 的 /var/www/html）。

2. 配置 Nginx：

   server {
     listen 80;
     server_name yourdomain.com;
     root /var/www/html;
     index index.html;
   }

3. 配置防火墙：

   # 启用防火墙
   sudo ufw enable
   # 允许 SSH（假设默认端口为 22）
   sudo ufw allow 22
   # 开放80、443端口
   sudo ufw allow 80
   sudo ufw allow 443

4. 配置安全组：

   找到对应云服务器的安全组，设置对应规则，否则会被拒绝访问。

   80端口和443端口可以选择0.0.0.0，其余建议设置本地IP即可

---

六、常见问题处理

1. 样式丢失
   • 确保静态资源在 public 目录，构建后检查路径。
   • 在 dist 目录添加 .nojekyll 文件（防止 GitHub Pages 处理错误）。
2. 自动化部署失败
   • 检查 Node.js 和 pnpm 版本是否匹配12。
   • 确保 base 配置与仓库名一致（如 base: '/repo-name/'）1218。

---

七、进阶优化

• 主题定制：通过 theme/style.css 修改颜色变量（如 --vp-c-brand）。
• Algolia 搜索：申请 API Key 并配置搜索功能16。
• PWA 支持：添加 Manifest 和 Service Worker15。
• 评论功能：配置Giscus，与GitHub绑定
• 自动化部署：使用GitHubAction，配置对应的deploy.yml文件(yml配置指南)

---

通过以上步骤，你可以从零开始搭建一个 VitePress 博客并部署到服务器。如需完整代码示例或进一步调试，可参考 VitePress 官方文档 或上述引用中的实践案例。