知识篇：（三）VitePress 博客搭建指南：轻量化与高性能的完美结合

VitePress 博客搭建指南：轻量化与高性能的完美结合

使用 VitePress 搭建博客是一个简单高效的选择。下面是详细的步骤，帮助你搭建一个基于 VitePress 的技术博客：

my-vitepress-blog/
├── docs/
│   ├── .vitepress/
│   │   └── config.js          # VitePress 配置文件，定义站点的基本信息、主题配置和导航结构
│   ├── guide/                 # 存放博客文章的目录
│   │   ├── index.md           # 指南页面的 Markdown 文件，作为该部分的入口
│   │   ├── vue-intro.md       # Vue.js 入门的博客文章
│   ├── index.md               # 主页的 Markdown 文件，通常用于介绍博客的内容和主题
├── package.json                # npm 项目的配置文件，定义项目依赖和脚本
└── node_modules/              # 项目依赖包的目录，由 npm 自动生成

一. 安装 VitePress

首先，确保你的开发环境中安装了 Node.js。然后在你的计算机上创建一个新的项目文件夹并进入该文件夹：

mkdir my-vitepress-blog
cd my-vitepress-blog

接下来，初始化一个新的 npm 项目：

npm init -y

然后安装 VitePress：

npm install -D vitepress

二. 创建目录结构

在项目根目录下创建一个 docs 文件夹，VitePress 会在此文件夹中查找文档。

mkdir docs

在 docs 目录中，创建一个 index.md 文件，这是你的博客首页：

echo '# 我的 VitePress 技术博客' > docs/index.md

三. 配置 VitePress

在 docs 目录中创建一个 .vitepress 文件夹，并在其中创建一个 config.js 文件，用于配置你的博客。

mkdir docs/.vitepress

在 docs/.vitepress/config.js 文件中，添加以下基本配置：

import { defineConfig } from 'vitepress';export default defineConfig({title: '我的 VitePress 技术博客',description: '专注于 Vite 和 Vue.js 的技术分享',themeConfig: {nav: [{ text: '指南', link: '/guide/' },{ text: '关于', link: '/about/' },],sidebar: [{text: '指南',items: [{ text: 'VitePress 使用指南', link: '/guide/' },{ text: 'Vue.js 入门', link: '/guide/vue-intro' },],},],},
});

四. 创建博客文章

在 docs 目录下创建一个 guide 文件夹，并在其中添加 Markdown 文件作为博客文章。

mkdir docs/guide
echo '# VitePress 使用指南' > docs/guide/index.md
echo '# Vue.js 入门' > docs/guide/vue-intro.md

你可以在这两个 Markdown 文件中添加你的博客内容，例如：

docs/guide/index.md：

# VitePress 使用指南VitePress 是一个基于 Vite 的静态网站生成器，适用于编写文档和博客。

docs/guide/vue-intro.md：

# Vue.js 入门Vue.js 是一个渐进式的 JavaScript 框架，适合构建用户界面。

五. 启动开发服务器

在项目根目录下，使用以下命令启动 VitePress 的开发服务器：

npx vitepress dev docs

然后在浏览器中访问 http://localhost:3000，你就能够看到你的博客主页。

5.1.xxx报错了不要着急

这个错误提示表明你的 Node.js 版本不支持 VitePress 中使用的某些最新语法（如空值合并赋值 ??=）。为了修复这个问题，通常可以通过以下几个步骤来解决：

5.1.1. 检查 Node.js 版本

确保你使用的 Node.js 版本是 VitePress 所支持的版本。VitePress 目前建议使用 Node.js 14 及以上版本，最佳选择是使用 Node.js 16 或更高版本。

你可以通过以下命令检查当前的 Node.js 版本：

node -v

5.1.2. 升级 Node.js

如果你的 Node.js 版本低于 14，可以通过以下方式进行升级：

• 使用 Node Version Manager (NVM)（推荐）：可以安装 NVM，然后使用它来安装和管理不同版本的 Node.js。

  nvm install 16
  nvm use 16
  

• 直接下载：前往 Node.js 官网 下载并安装最新版本。

5.1.3. 清除缓存并重试

在升级 Node.js 后，建议清除 npm 缓存，并重新安装 VitePress：

npm cache clean --force
npm install -D vitepress

然后再次尝试启动 VitePress 开发服务器：

npx vitepress dev docs

5.2又又又又又报错了！！！

这个错误表明你正在尝试使用 CommonJS 模块 (require) 来加载 VitePress，而 VitePress 是一个 ES 模块（ESM）格式的包。为了修复这个问题，请按照以下步骤操作：

5.2.1. 确保 Node.js 版本支持 ESM

确保你的 Node.js 版本是 12.17.0 或更高版本（推荐使用 14 或 16）。你可以用以下命令检查当前版本：

node -v

如果需要升级 Node.js，请按照前面提到的方法进行升级。

5.2.2. 确保项目配置正确

确保你的 package.json 文件中包含 "type": "module"，这样 Node.js 会将你的代码视为 ESM 模块。这可以确保你在项目中使用 ES 模块语法。

在你的 package.json 中添加或修改如下：

{"name": "my-vitepress-blog","version": "1.0.0","type": "module","scripts": {"docs:dev": "vitepress dev docs","docs:build": "vitepress build docs"},"devDependencies": {"vitepress": "^1.4.1"}
}

准备撒花🎉

六. 启动本地预览

你可以使用以下命令在本地启动预览，以检查构建后的效果：

npx vitepress dev docs

在浏览器中打开 http://localhost:4173（默认端口），你就可以预览你的博客。

npx vitepress dev docs 和 npx vitepress preview docs 是 VitePress 中的两个不同命令，主要用于不同的场景。以下是这两个命令的详细区别：

1. npx vitepress dev docs

• 目的：用于开发阶段。
• 功能：
  • 启动一个本地开发服务器，通常监听 http://localhost:3000。
  • 提供热更新（Hot Module Replacement, HMR），意味着当你修改 Markdown 文件时，页面会自动更新，无需手动刷新。
  • 适合在开发过程中使用，实时查看修改效果，方便调试和编辑内容。
• 使用场景：你在本地修改和编辑文档时，使用该命令可以实时查看效果，调整布局和内容。

2. npx vitepress preview docs

• 目的：用于预览已构建的静态文件。
• 功能：
  • 启动一个本地服务器，以预览通过 vitepress build docs 命令生成的静态文件。
  • 通常用于查看生产环境下的效果，确保在实际部署前没有问题。
  • 不支持热更新，页面更新需要手动刷新。
• 使用场景：在你完成内容编辑并构建文档后，可以使用该命令来预览构建后的静态文件，以检查最终效果和布局。

总结

• 开发模式（vitepress dev）：实时预览，支持热更新，适合在编辑和调试时使用。
• 预览模式（vitepress preview）：预览已构建的静态文件，不支持热更新，适合在准备部署前检查最终效果。

选择哪个命令取决于你的当前需求。在开发过程中，你会主要使用 dev 命令，而在构建完成后，使用 preview 命令来确保一切正常。

七. 部署博客

当你完成博客的开发后，可以使用以下命令构建静态文件：

npx vitepress build docs

生成的文件将会在 docs/.vitepress/dist 目录下。你可以将该目录中的文件上传到你的静态文件托管服务，如 GitHub Pages、Netlify 或 Vercel。

恭喜你！VitePress 的构建已经成功完成。

7.1. 查看构建结果

构建完成后，你可以在 docs/.vitepress/dist 目录中找到生成的静态文件。这些文件可以部署到任何支持静态文件托管的服务器上。

八. 未来扩展

• 添加更多的技术文章：分享关于 Vite、Vue.js 和前端开发的最佳实践。
• 集成评论系统：可以使用多种服务（如 Disqus）集成评论功能。
• 美化设计：使用 CSS 或现成的主题来增强博客的外观。

通过以上步骤，你将能够创建一个基于 VitePress 的技术博客。