博客的起步

2022/5/10大约 3 分钟

博客的起步

date: 2022-05-10

update: 2026-05-17

author: 海语、西风

location: 深圳，华为软件中心；南京，麒麟科创园

环境准备

本博客基于 VuePress 2.0.0-rc.29 + vuepress-theme-hope 搭建。

安装node.js

最低要求 16.19.0，推荐使用 20.x LTS 版本（VuePress 2 不再支持 Node.js 8/10/12）

项目初始化

# 新建文件夹
mkdir my-vuepress-blog
cd my-vuepress-blog

# 初始化 package.json（自动启用 ESM 模式）
npm init -y
npm pkg set type=module

创建docs文件夹，并建立首页

# 新建文档主目录
mkdir docs
cd docs

# 创建首页文件
echo "# Hello VuePress" > docs/README.md

配置工程脚本和VuePress依赖打开根目录下的package.json，写入脚本：

  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",
    "docs:preview": "vuepress preview docs"
  },
  "devDependencies": {
    "@vuepress/bundler-vite": "^2.0.0-rc.29",
    "@vuepress/plugin-search": "^2.0.0-rc.29",
    "vuepress": "^2.0.0-rc.29",
    "vuepress-theme-hope": "^2.0.0-rc.105",
    "sass-embedded": "^1.77.2"
  }

npm安装并启动

npm install
npm run docs:dev

VuePress 会在 http://localhost:8080 启动本地热重载的开发服务器。

项目结构说明

博客内容以 Markdown 文件存储在 docs 目录及其子目录下
支持任意层级的子目录嵌套（不再限制为一层）
静态资源（图片、图标等）放在 docs/.vuepress/public/ 目录下

配置文件

在 docs/.vuepress/ 目录下创建 config.js 文件，使用 ESM 格式：

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

export default defineUserConfig({
  // 基础配置
  title: '***',
  description: '***',
  lang: 'zh-CN',

  // 必须配置：打包工具
  bundler: viteBundler(),

  // 主题配置
  theme: hopeTheme({
    //开启内置搜索
    plugins: {
      search: true
    },
    //配置顶部导航栏
    navbar: [
      { text: '首页', link: '/' },
      { text: '***', link: '***'}
    ],
    //配置侧边栏
    sidebar: [
      {
        text: '欢迎光临',
        path: '/',
        collapsible: false,
        children: [
          { text: "主页", path: '/' }
        ]
      }
    ],

    // 上下页链接
    nextLinks: true,
    prevLinks: true
  })
})

自动部署到 GitHub Pages

最新部署方式（2026 年更新）

不再使用过时的 jenkey2011/vuepress-deploy，改用官方推荐的 peaceiris/actions\-gh\-pages，解决了 Git 安全限制问题，更稳定可靠。

申请 GitHub Personal Access Token (PAT)，勾选 repo 权限
在项目仓库的 Settings → Secrets and variables → Actions 中添加密钥
在项目根目录下创建 .github/workflows/deploy.yml 文件：

name: Build and Deploy
on: 
  push:
    branches: [main]
    paths:
      - 'docs/**'
  workflow_dispatch:

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.ACCESS_TOKEN }}
          fetch-depth: 0

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build VuePress site
        run: npm run docs:build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.STUDIO_SECRET }}
          external_repository: westlei/westlei.github.io
          publish_branch: master
          publish_dir: docs/.vuepress/dist
          commit_message: Auto deploy Github Pages
          force_orphan: true

部署说明

每次推送到 main 分支的 docs 目录时，会自动触发构建和部署
部署完成后，访问Pages对应链接即可查看博客
首次部署需要在目标仓库的 Settings → Pages 中启用 GitHub Pages 功能

更新说明

2026.05 更新：全面升级到 VuePress 2 + vuepress-theme-hope，改用官方推荐的部署方式，彻底解决旧部署工具的兼容性和安全性问题

参考链接

本次更新基于AI支持