VuePress 2 博客搭建与部署

本指南基于 VuePress 2 + vuepress-theme-hope 主题，涵盖从本地开发、内容编写到部署至阿里云 ECS（Nginx）及域名备案的完整步骤。适用于个人技术博客或知识库的搭建。

1. 环境准备

Node.js：需要 v18 或更高版本。前往 Node.js 官网下载 LTS 版本安装。
- 验证：node -v、npm -v
Git：用于版本管理。
文本编辑器：推荐 VS Code 或 Typora（用于 Markdown 写作）。

2. 创建项目

手动创建（推荐，避免脚手架网络问题）

# 创建项目目录并进入
mkdir my-docs
cd my-docs

# 初始化 npm 项目
npm init -y

# 创建文档源目录
mkdir docs
mkdir docs\.vuepress

3. 安装依赖

3.1 安装 VuePress 2、主题和打包器

bash

npm install -D vuepress@next vuepress-theme-hope @vuepress/bundler-vite --legacy-peer-deps

若遇到版本冲突，可使用 --legacy-peer-deps 参数。若想完全兼容，可指定版本：
bash
npm install -D vuepress@2.0.0-rc.30 vuepress-theme-hope@2.0.0-rc.107 @vuepress/bundler-vite@2.0.0-rc.30 --legacy-peer-deps

3.2 安装 Sass 编译器（主题依赖）

bash

npm install -D sass-embedded --legacy-peer-deps

4. 配置项目

4.1 修改 `package.json` 添加启动脚本

打开 package.json，将 "scripts" 部分修改为：

json

"scripts": {
  "docs:dev": "vuepress dev docs",
  "docs:build": "vuepress build docs"
}

4.2 创建配置文件 `docs/.vuepress/config.js`

在 docs/.vuepress/ 下新建 config.js，内容如下（根据个人情况修改标题、导航等）：

javascript

import { defineUserConfig } from "vuepress";
import { viteBundler } from "@vuepress/bundler-vite";
import { hopeTheme } from "vuepress-theme-hope";

export default defineUserConfig({
  lang: "zh-CN",
  title: "我的技术博客",
  description: "Java、Python 学习笔记与总结",

  bundler: viteBundler(),  // 关键：指定打包工具

  theme: hopeTheme({
    hostname: "https://你的域名.com",
    author: {
      name: "你的名字",
    },
    sidebar: "structure",  // 自动生成侧边栏
    navbar: [
      { text: "首页", link: "/" },
      { text: "Java", link: "/java/" },
      { text: "Python", link: "/python/" },
      { text: "关于", link: "/about.md" },
    ],
  }),
});

注意：保存文件时必须使用 UTF-8 编码，否则会报 stream did not contain valid UTF-8。

4.3 创建首页和示例内容

docs/README.md：

markdown

# 欢迎来到我的技术博客

这里记录我的 Java、Python 学习笔记与总结。

docs/about.md：

markdown

# 关于我

一名热爱技术的开发者，专注于 Java 后端与 Python 自动化。

docs/java/README.md（分类首页）：

markdown

# Java 笔记

## 目录
- [HashMap 原理](./hashmap.md)

docs/java/hashmap.md（示例文章）：

markdown

# HashMap 核心原理

这是关于 HashMap 数据结构和源码分析的笔记。

docs/python/README.md（分类首页）：

markdown

# Python 笔记

常用工具脚本与数据分析案例。

5. 编写内容

将所有 Markdown 文件放入 docs/ 下对应的分类目录。
侧边栏会自动根据目录结构生成（因为配置了 sidebar: "structure"）。

如果是 Word 笔记，可以使用 Pandoc 批量转换为 Markdown：

bash

# 安装 pandoc 后执行
for file in *.docx; do
    pandoc "$file" -t markdown -o "${file%.docx}.md"
done

6. 本地预览

bash

npm run docs:dev

浏览器访问 http://localhost:8080，实时预览效果。

7. 构建静态文件

bash

npm run docs:build

生成的文件在 docs/.vuepress/dist/ 目录下。

8. 部署到阿里云 ECS

8.1 打包并上传

bash

# 进入 dist 目录打包
cd docs/.vuepress
tar -czf blog.tar.gz dist/

# 上传到服务器
scp blog.tar.gz root@你的服务器IP:/opt/

8.2 服务器解压

bash

cd /opt
tar -xzf blog.tar.gz
# 解压后得到 /opt/dist 目录

8.3 配置 Nginx

创建站点配置文件：

bash

sudo vim /etc/nginx/sites-available/my-docs

写入以下内容（根据备案情况选择监听端口）：

nginx

server {
    listen 80;          # 备案通过后使用 80；临时可用 8081
    server_name 你的域名.com www.你的域名.com;

    root /opt/dist;     # 指向你的静态文件目录
    index index.html;

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

启用站点并重载 Nginx：

bash

sudo ln -s /etc/nginx/sites-available/my-docs /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

8.4 安全组放行端口

在阿里云安全组入方向添加规则：

如果使用 80 端口：放行 TCP 80，授权对象 0.0.0.0/0
如果使用 8081 端口（备案未通过时）：放行 TCP 8081，授权对象 0.0.0.0/0

9. 域名解析与备案

9.1 域名解析（阿里云）

在阿里云云解析 DNS 中添加 A 记录：

记录类型	主机记录	记录值	说明
A	`@`	你的服务器公网 IP	根域名指向服务器
A	`blog`	你的服务器公网 IP	子域名指向服务器

9.2 ICP 备案

只有部署在中国大陆服务器上的网站才需要备案。
在阿里云备案系统提交备案，审核约 7-20 个工作日。
备案期间 80 和 443 端口会被拦截，可使用高位端口（如 8081）访问。
备案通过后，将备案号添加至网站页脚（可在 VuePress 主题中配置）。

10. 日常更新流程

每次写完新笔记或修改旧笔记后：

bash

# 1. 本地预览确认
npm run docs:dev

# 2. 生成静态文件
npm run docs:build

# 3. 打包上传
cd docs/.vuepress
tar -czf blog.tar.gz dist/
scp blog.tar.gz root@你的服务器IP:/opt/

# 4. 服务器解压（SSH 登录后）
cd /opt
tar -xzf blog.tar.gz
# 无需重启 Nginx，静态文件直接生效

更高效的方式：使用 Git 仓库 + CI/CD 自动化部署（如 Gitee Pages 或 GitHub Actions），后续可另行配置。

11. 常见问题

11.1 `npm install` 报 ERESOLVE 版本冲突

解决方法：在安装命令末尾加上 --legacy-peer-deps，或使用完全兼容的版本组合。

11.2 `npm run docs:dev` 报 `stream did not contain valid UTF-8`

原因：config.js 文件编码不是 UTF-8。解决：用 VS Code 或记事本另存为 UTF-8 编码。

11.3 报 `No VuePress bundler is detected`

原因：缺少打包器。解决：安装 @vuepress/bundler-vite，并在 config.js 中添加 bundler: viteBundler()。

11.4 报 `Preprocessor dependency "sass-embedded" not found`

解决：执行 npm install -D sass-embedded。

11.5 部署后访问 404

原因：Nginx 配置中 try_files 未正确设置，或静态文件路径错误。解决：检查 root 路径是否正确，确保 try_files $uri $uri/ /index.html; 存在。