VuePress + Github Pages搭建博客 01

2022/6/10

一直都是使用 CSDN 写一些博文,最近突发奇想想试用下免费的 Github Pages 搭建一下博客,跟上大家的脚步 👣,VuePress 官网文档写得还算是挺全面的,但是我在进行部署的时候踩了不少坑,记录下来方便大家上手,减少踩坑。

源码:https://github.com/Jessie-jzn/blog-vuepress (opens new window)

博客地址:https://jessie-jzn.github.io/Jessie-blog/ (opens new window)

# 快速搭建 VuePress

一个 VuePress 网站是一个由  Vue (opens new window) (opens new window)Vue Router (opens new window) (opens new window)和  webpack (opens new window) (opens new window)驱动的单页应用

# 快速上手 (opens new window)

  1. 创建并进入一个新目录
mkdir blog
cd blog
  1. 使用npm进行初始化
npm init
  1. VuePress安装为本地依赖(我使用的是 v1.x 版本)
npm install -D vuepress
  1. 新建一个docs新目录,并且创建一个新文档(因为 VuePress 使用 docs 作为根目录,所以这个 README.md 相当于主页)
mkdir docs && echo '# Hello VuePress' > docs/README.md
  1. 在  package.json  中添加 script
{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
  1. docs目录下创建一个  .vuepress  目录,并创建一个新的 config.js 文件
cd docs
mkdir .vuepress

此时你的目录结构为

├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json
  1. 在本地启动服务器
npm run docs:dev

此刻 VuePress 会在  http://localhost:8080 (opens new window) (opens new window)启动一个热重载的开发服务器。

现在,我们已经实现了一个简单可用的 VuePress 文档。

# 简单配置

一个 VuePress 网站必要的配置文件是  .vuepress/config.js,所以我们在config.js内配置所需要的信息,以下所有的代码块都是写在config.js文件内,包在module.exports对象中

# 基础信息

module.exports = {
  title: "Jessie的个人技术博客",
  description: "办法总比问题多",
};

# 配置中文

module.exports = {
  title: "Jessie的个人技术博客",
  description: "办法总比问题多",
  locales: {
    "/": {
      lang: "zh-CN",
    },
  },
};

# 配置主题及路由

module.exports = {
    title: 'Jessie的个人技术博客',
    description: '办法总比问题多',
    theme: "reco",
    themeConfig: {
        nav: [
            { text: '首页', link: '/' },
            {
                text: 'Jessie的博客',
                items: [
                    { text: 'Github', link: 'https://github.com/Jessie-jzn' },
                    { text: 'CSDN', link: 'https://blog.csdn.net/zn740395858?spm=1010.2135.3001.5343' }
                    { text: '掘金', link: 'https://juejin.cn/user/2524134425764375' }
                ]
            }
        ],
        sidebar:[
            {
                title: "博客搭建",
                path: "/construction/Blog1",
                collapsable: false, // 不折叠
                children: [
                    { title: "博客 01", path: "/construction/Blog1" },
                ],
            }
        ]
    }
}

此刻的博客页面效果如下

WX20220611-211257.png

# 部署到 GitHub

  1. 在自己的 github 上新建一个项目,我这边是叫 Jessie-blog 4d74fe1b04374112b72dae8de8039f7d~tplv-k3u1fbpfcp-watermark.image.png

  2. 回到本地的项目上,在.vuepress/config.js中新增一个  base  路径配置,这个非常重要‼️

module.exports = {
    title: 'Jessie的个人技术博客',
    description: '办法总比问题多',
    base: '/Jessie-blog/', // 这个路径名称就是你刚才所配置的项目名!!!,斜杠不能漏!!!⚠️
    theme: "reco",
    themeConfig: {
        nav: [
            { text: '首页', link: '/' },
            {
                text: 'Jessie的博客',
                items: [
                    { text: 'Github', link: 'https://github.com/Jessie-jzn' },
                    { text: 'CSDN', link: 'https://blog.csdn.net/zn740395858?spm=1010.2135.3001.5343' }
                    { text: '掘金', link: 'https://juejin.cn/user/2524134425764375' }
                ]
            }
        ],
        sidebar:[
            {
                title: "博客搭建",
                path: "/construction/Blog1",
                collapsable: false, // 不折叠
                children: [
                    { title: "博客 01", path: "/construction/Blog1" },
                ],
            }
        ]
    }
}


  1. 回到本地的项目上,新建一个 deploy.sh 文件在根目录下,这里需要配置下你自己的 git 地址和 git 项目名称和分支。(如果有学习 git 和工作 git 想分开配置的话,可以看下我之前写的博客:git 操作之一台 mac 电脑绑定两个 git 账号,用于工作和学习区分 (opens new window)
#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件

npm run docs:build

# 进入生成的文件夹

cd docs/.vuepress/dist

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io/<REPO>
# 应为我本地有两个git,我学习的git命名是git@study.github.com
git push -f git@study.github.com:Jessie-jzn/Jessie-blog.git master:blog-pages
#git push -f git@github.com:你的git名/你的git项目名.git master:你的git分支

cd -

这就相当于把打包好的 dist 代码直接放在blog-pages下,到时候在 git 上配置部署的Source分支为这个字分支就行了,默认就会是渲染 index.html

  1. 回到 github 项目上,配置 github pages 部署的资源,在这里我踩坑了,一开始我只选择了分支,并没有选择是/docs,导致发生 vuepress 部署在 github 上出现样式问题,最后发现不能使用默认的/root,而是要改成/docs,😭 这个问题让我看了一晚上,一直以为是路径问题

1654953825918.jpg

最后生成的地址就是https://jessie-jzn.github.io/Jessie-blog/ (opens new window)

基础使用 VuePress + GitHub Pages 搭建博客也就完成了。

# 踩坑

# 如果遇到部署上 github 后,vuepress 样式丢失的情况,请检查

  • 是否是路径问题,.vuepress/config.js中的  base  路径是否正常
  • github 上的资源部署路径是否正确,有没有选对分支,有没有选对资源文件夹

# 浏览器展示Mermaid图不生效

在github上展示得出来,但是在deploy后的浏览器页面却不生效了,目前没有找到解决办法。

备用方案是在Online FlowChart & Diagrams Editor - Mermaid Live Editor(https://mermaid.live/edit (opens new window))生成Mermaid图,然后复制图片展示

# 使用deploy脚本提交代码时报错

报错内容: error: src refspec master does not match any error: failed to push some refs to 'github.com:Jessie-jzn/Jessie-blog.git'

报错原因: 这个错误通常是因为正在尝试推送到一个不存在的分支,或者本地分支与远程分支不匹配导致的。 实际上是因为 Github/Git 没有默认的“master”分支。“master”已更改为“main”分支

解决方案:

git push -f git@github.com:Jessie-jzn/Jessie-blog.git master:blog-pages

改成

git push -f git@github.com:Jessie-jzn/Jessie-blog.git main:blog-pages
上次更新: 2024/2/26 02:20:28