持续运维

Appearance

VitePress快速搭建个人网站 ​

本文介绍VitePress搭建个人网站，并使用Docker容器化部署。

安装 ​

安装步骤概述：

  1. 前置准备：宿主机安装docker、node等开发环境
  2. 安装向导：基于VitePress脚手架初始化项目
  3. 运行启动：打包镜像并运行容器

前置准备 ​

  • Node.js 18及以上版本
  • Docker:
  • 命令行终端（Windows Powershell、MacOS终端）
  • 开发集成环境（IDE）: VSCode、Webstorm

在项目文件夹中（推荐VscodeProjects或WebstormProjects）创建空项目文件夹docker-vitepress

shell
mkdir docker-vitepress && cd docker-vitepress

推荐使用pnpm安装VitePress

shell
# 安装pnpm
npm install -g pnpm@latest
# 安装vitepress
pnpm add -D vitepress

安装向导 ​

VitePress附带一个命令行设置向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令启动向导

shell
pnpm vitepress init

根据命令提示，初始化项目

shell
┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run pnpm run docs:dev and start writing.

安装后项，目录结构下图所示：

shell
.
├── README.md
├── docs
│    ├── api-examples.md
│    ├── index.md
│    └── markdown-examples.md
├── node_modules
│    └── vitepress -> .pnpm/vitepress@1.3.4_@algolia+client-search@4.24.0_postcss@8.4.47_search-insights@2.17.2/node_modules/vitepress
├── package.json
└── pnpm-lock.yaml

运行启动 ​

查看package.json下启动脚本

json
{
  "devDependencies": {
    "vitepress": "^1.3.4"
  },
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

项目根目录启动终端，执行

shell
# vitepress docs:dev
pnpm run docs:dev

根据提示，在浏览器中打开：http://localhost:5173/

项目停止

shell
# MacOS
Command+C
# Windows
Ctrl+C

容器打包，将在docs/.vitepress下生成dist包，该包用于在生产环境部署

shell
# vitepress docs:build
pnpm run docs:build

容器化部署 ​

前端资源在生产环境中部署时，将源文件打包为dist，然后nginx作为Web服务器对静态资源代理。简而言之，在生产环境，dist+nginx可以实现前端部署。

容器化 ​

创建nginx配置文件nginx.conf

nginx
server {
    listen       8080;
    listen  [::]:8080;
    server_name localhost;

    access_log  /var/log/nginx/host.access.log  main;

    # 静态资源代理，前端Web服务器
    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
        try_files $uri $uri/ /index.html;
    }
    #error_page  404              /404.html;

    # redirect server error pages to the assets page /50x.html
    #
    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

项目根目录下新建Dockerfile

shell
touch Dockerfile

粘贴如下Dockerfile模板，根据个人信息更改部分内容。安装npm和pnpm时默认使用腾讯云资源镜像加速，如果你在阿里云或华为云上部署该项目，若容器构建失败请更改资源镜像。

dockerfile
FROM node:22-alpine3.20 as build-stage
# 作者信息
LABEL authors="test@test.com"

# 设置工作目录
WORKDIR /app

# 复制所有文件到工作目录
COPY . .

# 安装 pnpm Qcloud腾讯云加速
RUN npm install -g pnpm --registry=http://mirrors.cloud.tencent.com/npm/

# 安装依赖 Qcloud腾讯云加速
RUN pnpm install --registry=http://mirrors.cloud.tencent.com/npm/

# 构建生产环境下到Vue项目
RUN pnpm run docs:build

FROM nginx:alpine3.20-perl

COPY nginx.conf /etc/nginx/conf.d/default.conf

COPY --from=build-stage /app/docs/.vitepress/dist /usr/share/nginx/html

# 暴露端口
EXPOSE 8080

# 启动Nginx服务
CMD ["nginx", "-g", "daemon off;"]

容器构建，并将容器命名为my-vitepress/hello:0.0.1

shell
docker build -t my-vitepress/hello:0.0.1 .

完成一个VitePress Docker容器的构建，查看镜像

shell
docker ps | grep hello:0.0.1

创建并运行容器（以下两种方式任选其一）

docker直接运行

shell
# 将vitepress/hello:0.0.1作为镜像启动容器，以后台方式运行，映射本地端口80，容器命名为my-vitepress
docker run -d --name vitepress-test -p 80:8080 my-vitepress/hello:0.0.1

停止容器

shell
docker stop vitepress-test

删除容器

shell
docker rm vitepress-test

docker-compose构建并运行，需创建docker-compose.yaml配置文件。（也支持自定义文件名，使用-f docker-compose-local.yaml指定该配置）

shell
# docker compose up -d 
docker-compose up -d

停止容器并卸载

shell
# docker compose down
docker-compose down

在浏览器中打开 http://localhost（http默认端口号为80） 即可查看部署效果。

Workflow项目托管 ​

将项目托管到GitHub，方便项目分发。任何拥有Docker环境的服务器都可以快速部署该项目。

将本项目托管到GitHub或Gitee（码云，GitHub国内版），以GitHub为例

注册并登录GitHub ​

过程概述，详细过程略

项目托管建议参考GitHub官方文档Get started

  1. 注册并登录：https://github.com/
  2. 设置github-ssh密钥，将公钥添加到GitHub设置的密钥中
  3. 创建项目仓库： docker-vitepress
  4. 本地git仓库与GitHub仓库关联，推送本地项目

创建.gitignore ​

shell
touch .gitignore

在git仓库中忽略本地IDE配置文件，以及build后生成的包

docs/.vitepress/cache
docs/.vitepress/dist/
node_modules
# Jetbrains软件配置文件
.idea

GitHub Actions-Workflow配置文件 ​

在该项目的GitHub仓库Settings中配置仓库密钥

  1. Settings
  2. Security -> Secrets and variables -> Actions
  3. 创建新的仓库密钥： New repository secret
  4. 密钥命名为VITE_TOKEN，密钥为上一小节中获取的一串TOKEN

更新本项目中的github-actions.yaml中个性化参数

yaml
token: ${{secrets.VITE_TOKEN}}
git-config-name: GitHub用户名
git-config-email: GitHub用户邮箱
yaml
# 部分内容
name: Deploy 🚀
  uses: JamesIves/github-pages-deploy-action@v4
  with:
  token: ${{secrets.VITE_TOKEN}}
  folder: docs/.vitepress/dist
  git-config-name: xiaolinstar
  git-config-email: xing.xiaolin@foxmail.com

push到GitHub仓库后，会自动触发GitHub Actions；

workflow_dispatch支持「点击按钮」手动触发。

添加域名前缀 ​

GitHub Actions部署和普通云服务器部署域名区别：

  • 云服务域名：http://vitepress-qucikstart或https://vitepress-quickstart
  • GitHub域名：https://xiaolinstar.github.io/docker-vitepress/

GitHub部署方式比云服务器部署多了仓库名前缀，需要在项目部署时做区分和处理，以兼容这两类部署方式。

VitePress项目的主要配置文件包括两个：

  • docs/index.md
  • docs/.vitepress/config.mts

只需在config.mts中添加2行代码即可区分项目部署方式。 修改后的config.mts内容如下（添加的代码以用注释标注）

ts
import { defineConfig } from 'vitepress'

// @ts-ignore (*) 网站基础路径，区分GitHub部署和常规部署
const basePath = process.env.GITHUB_ACTIONS === 'true' ? '/docker-vitepress/' : '/'

// https://vitepress.dev/reference/site-config
export default defineConfig({
   base: basePath, // (*) 设置域名前缀
   title: "My Awesome Project",
   description: "A VitePress Site",
   themeConfig: {
      // https://vitepress.dev/reference/default-theme-config
      nav: [
         { text: 'Home', link: '/' },
         { text: 'Examples', link: '/markdown-examples' }
      ],

      sidebar: [
         {
            text: 'Examples',
            items: [
               { text: 'Markdown Examples', link: '/markdown-examples' },
               { text: 'Runtime API Examples', link: '/api-examples' }
            ]
         }
      ],

      socialLinks: [
         { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
      ]
   }
})

项目维护 ​

文章创作 ​

本项目使用markdown语法来编写文档。用户的创作行为都应在IDE集成工具（如WebStorm）中完成：

  • 新建文章：
    1. 在docs目录下新建md格式的文本，如hello.md，进行内容创作
    2. 在docs/.vitepress/config.mts中创建项目配置
  • 修改文章：直接修改原文档即可
  • 删除文章：
    1. 删除docs目录下的指定文档
    2. 修改docs/.vitepress/config.mts中的文章配置，避免出现404

网站更新 ​

在文章创作后，将「变化」部署到项目网站中，开发环境中测试：

shell
pnpm run docs:dev

项目推送push到GitHub，在仓库中的Actions中查看变更。

下一步工作 ​

想要持续维护该项目或打造个性化网站，请参考VitePress官方文档：VitePress

References ​

[1]. VitePress由Vite和Vue驱动的静态站点生成器，https://vitepress.dev/zh/

[2]. Git started，开始你的旅程，https://docs.github.com/zh/get-started/start-your-journey/about-github-and-git

[3]. GitHub Actions，https://docs.github.com/zh/actions/writing-workflows/quickstart

[4]. GitHub Pages，https://docs.github.com/zh/pages

[5]. Gitee，https://gitee.com

联系作者 ​

如果您有需要技术咨询，或者有想法使本文档变得更好。

联系作者：xing.xiaolin@foxmail.com

微信公众号：持续运维，掘金：老实巴交的麻匪

Copyright © 2025 XingXiaolin