VuePress 教程：一步步创建你的静态网站

1. 内容处理引擎#

VuePress 使用 Markdown 作为主要的内容格式，所有页面内容都是以 .md 文件的形式存储。VuePress 内置了 remarkable 或 markdown-it 作为 Markdown 解析器，将 Markdown 内容转换为 HTML 结构。此外，VuePress 还支持 Vue 组件嵌入，允许开发者在 Markdown 中直接使用 Vue 组件，增强页面的交互性。

2. 主题系统#

VuePress 的主题系统是其一大亮点。主题决定了网站的整体外观和布局，包括导航栏、侧边栏、页脚等内容。VuePress 提供了默认主题（@vuepress/theme-default），同时支持自定义主题。开发者可以通过修改主题文件或创建新主题来实现个性化的网站风格。

3. 插件系统#

VuePress 的插件系统非常灵活，允许开发者通过安装和配置插件来扩展功能。常见的插件包括：

• 搜索插件：增强网站的搜索功能。
• SEO 插件：优化网站的搜索引擎排名。
• 代码高亮插件：支持多种编程语言的代码高亮显示。
• 多语言支持：适用于国际化网站。

4. 构建与部署机制#

VuePress 使用 Vite 或 Webpack 作为构建工具，负责将源码编译成最终的静态资源。构建完成后，网站可以部署到任意静态托管平台，如 GitHub Pages、Netlify 或 Vercel。

通过理解 VuePress 的架构，我们可以更好地掌控其工作原理，并在实际开发中发挥其最大价值。

安装 Node.js 与 npm#

首先，确保你已经安装了 Node.js 和 npm（Node Package Manager）。你可以通过访问 https://nodejs.org 下载最新版本的 Node.js。安装完成后，在终端或命令行中运行以下命令检查是否安装成功：

1
node -v
2
npm -v

如果输出了版本号，则说明安装成功。

初始化 VuePress 项目#

VuePress 可以通过 create-vuepress 工具快速初始化项目。运行以下命令：

1
npx create-vuepress my-site

该命令会提示你选择项目类型（如“docs”或“blog”），并创建相应结构的目录。例如，选择“docs”类型后，将会生成如下目录结构：

1
my-site/
2
├── docs/
3
│   ├── .vuepress/
4
│   │   └── config.js
5
│   ├── README.md
6
│   └── guide/
7
│       └── intro.md
8
└── package.json

其中，docs/ 是存放内容的主目录，.vuepress/ 是配置目录，config.js 是 VuePress 的配置文件。

安装依赖#

进入项目目录并安装依赖：

1
cd my-site
2
npm install

此时，项目已准备好，可以启动开发服务器进行测试。

启动开发服务器#

运行以下命令启动开发服务器：

1
npm run dev

浏览器将自动打开 http://localhost:8080，此时你可以在本地预览网站内容。

通过以上步骤，我们完成了 VuePress 项目的基本初始化。接下来，我们可以进入下一步，进行基础配置。

1. 配置主题#

VuePress 默认使用 @vuepress/theme-default 作为主题。若需更换主题，可以在 package.json 中添加依赖：

1
{
2
  "dependencies": {
3
    "@vuepress/theme-reco": "^1.0.0"
4
  }
5
}

然后在 .vuepress/config.js 中指定主题：

1
module.exports = {
2
  theme: '@vuepress/reco',
3
};

2. 导航栏配置#

导航栏是用户浏览网站的主要路径之一。VuePress 允许通过 navbar 配置项自定义导航栏内容。例如，可以添加首页、文档、关于等链接：

1
module.exports = {
2
  navbar: [
3
    { text: '首页', link: '/' },
4
    { text: '文档', link: '/docs/' },
5
    { text: '关于', link: '/about/' },
6
  ],
7
};

3. 侧边栏配置#

侧边栏通常用于展示当前页面的目录结构或相关链接。VuePress 支持两种方式配置侧边栏：sidebar 和 autoSidebar。

1
module.exports = {
2
  sidebar: {
3
    '/docs/': [
4
      '',
5
      'guide',
6
      'api'
7
    ]
8
  }
9
};

1
module.exports = {
2
  sidebar: true,
3
};

4. 站点信息配置#

站点信息包括标题、描述、作者等，可以在 config.js 中设置：

1
module.exports = {
2
  title: '我的 VuePress 网站',
3
  description: '这是一个基于 VuePress 构建的静态网站示例',
4
  author: 'Your Name',
5
};

5. 其他常用配置#

• logo: 设置网站 logo。
• darkMode: 开启深色模式。
• themeConfig: 用于配置主题相关参数。

通过以上配置，我们可以进一步优化网站的结构和外观，使其更符合实际需求。

1. 创建 Markdown 页面#

在 docs/ 目录下，可以创建新的 .md 文件。例如，新建一个 hello-world.md 文件，并在其中编写内容：

1
# Hello World
2

3
这是第一个 VuePress 页面。
4

5
- 列表项 1
6
- 列表项 2
7

8
```java
9
public class HelloWorld {
10
    public static void main(String[] args) {
11
        System.out.println("Hello, VuePress!");
12
    }
13
}

2. 使用 Vue 组件#

VuePress 支持在 Markdown 中直接使用 Vue 组件。例如，可以创建一个自定义组件 MyComponent.vue，并在 .md 文件中引用它：

1
<MyComponent />

这使得页面内容更加丰富和互动。

3. 生成页面结构#

VuePress 会根据 docs/ 目录下的文件结构自动生成页面。例如，假设 docs/ 目录结构如下：

1
docs/
2
├── index.md
3
├── guide/
4
│   ├── intro.md
5
│   └── usage.md
6
└── api/
7
    └── reference.md

则生成的页面结构为：

• index.html → 对应 index.md
• guide/intro.html → 对应 guide/intro.md
• guide/usage.html → 对应 guide/usage.md
• api/reference.html → 对应 api/reference.md

4. 管理页面顺序#

可以通过 sidebar 配置项控制页面的显示顺序。例如，可以调整侧边栏中的页面顺序，以提升用户体验。

5. 添加元数据#

Markdown 文件顶部可以添加 Front Matter，用于设置页面的元数据，如标题、描述、作者等。例如：

1
---
2
title: 我的页面
3
description: 这是一个示例页面
4
author: 张三
5
---
6

7
# 我的页面
8
这是页面正文。

通过以上方法，我们可以有效地创建和管理 VuePress 的内容页面，构建一个结构清晰、内容丰富的网站。

1. vuepress-plugin-seo（SEO 插件）#

SEO 插件可以帮助优化网站的搜索引擎排名。安装方式如下：

1
npm install vuepress-plugin-seo --save

在 docs/.vuepress/config.js 中配置插件：

1
module.exports = {
2
  plugins: [
3
    'seo'
4
  ]
5
};

配置完成后，插件会自动为每一页生成合适的 <meta> 标签，提高搜索引擎的可见性。

2. vuepress-plugin-codecopy（代码复制插件）#

此插件允许用户一键复制代码块，提升用户体验。安装方式如下：

1
npm install vuepress-plugin-codecopy --save

配置插件：

1
module.exports = {
2
  plugins: [
3
    'codecopy'
4
  ]
5
};

启用后，代码块右上角会出现“复制”按钮，点击即可复制代码内容。

3. vuepress-plugin-i18n（多语言支持插件）#

如果你的网站需要支持多语言，可以使用此插件。安装方式如下：

1
npm install vuepress-plugin-i18n --save

配置插件：

1
module.exports = {
2
  plugins: [
3
    {
4
      name: 'i18n',
5
      locales: {
6
        en: {
7
          lang: 'en-US',
8
          title: 'My Site',
9
          description: 'A site for developers.'
10
        },
11
        zh: {
12
          lang: 'zh-CN',
13
          title: '我的网站',
14
          description: '一个面向开发者的网站。'
15
        }
16
      }
17
    }
18
  ]
19
};

此配置允许用户切换语言，提升国际用户的访问体验。

4. vuepress-plugin-search（搜索功能插件）#

此插件为网站添加搜索功能，方便用户查找内容。安装方式如下：

1
npm install vuepress-plugin-search --save

配置插件：

1
module.exports = {
2
  plugins: [
3
    'search'
4
  ]
5
};

启用后，用户可以在导航栏看到搜索框，输入关键词即可找到相关内容。

通过使用这些插件，我们可以极大地扩展 VuePress 的功能，使其更加灵活和实用。

1. 构建静态网站#

VuePress 提供了一个命令行工具 npm run build 来生成静态文件。在项目根目录下运行以下命令：

1
npm run build

该命令将根据 docs/ 目录下的内容，生成完整的静态网站。构建完成后，所有页面将被编译为 HTML、CSS 和 JavaScript 文件，并保存在 dist/ 目录中。

注意：构建后的文件是纯静态资源，不依赖于任何服务器端逻辑，因此可以部署到任何静态托管平台。

2. 常见部署方式#