用vuepress2搭建自己的github网站

最近打算自己做一个博客网站记笔记,然后部署到github上,最终选择了vuepress的最新版本v2(使用的是vue3和TypeScript开发,默认使用Vite作为打包工具)。

一、根据官方示例搭建项目

直接根据官方文档先初始化项目就行了,注意文档的版本,v1和v2还是有很多地方不同的。

二、将代码推到github上

最终我们是要部署到github上,所以直接在github上新建一个自己的项目仓库就好了

三、用 GitHub Actions 部署到 GitHub Pages

具体的各个站点和CI工具的部署,vuepress文档上也有写,我们这里选择用 GitHub Actions 部署到 GitHub Pages,根据步骤直接操作就行了,需要注意的几个地方:

1、官方提供的GitHub Actions脚本可以直接复制用,直接在默认的main分支根目录新建 .github/workflows/docs.yml 文件来配置工作流,注意如果你就改了默认分支名比如master,脚本里的main也要同步改下;

2、文档上写的项目自动生成的打包命令是:yarn docs:dev和yarn docs:build,实际使用中我们往往会直接改成 yarn dev和yarn build,如果改了GitHub Actions里的打包命令也要同步改下;

3、仓库里的Pages设置分支要选到gh-pages分支,后面的一项直接选根目录/(root),切记最后要点一下后面的save保存,否则不生效哟;

4、如果输入直接的网站地址打开发现是404,就是没部署成功

去代码仓库的Actions里去看下流水线有没有成功,失败了会是一个红色的小叉叉,点进去可以看到具体的错误位置,成功了是一个绿色的小勾

流水线成功了gh-pages分支里就会自动生成最终打包出来的文件,像下面这这样的:

5、如果部署成功了,但是发现样式和交互都不生效,基本就是css、js和图片等静态资源路径有问题,就是文档上第一步说明的,如果代码仓库名不是和自己账号名相同(* 相同的话最后访问地址是这样的 https://USERNAME.github.io/,不同的话是要在后面加上仓库名 https://USERNAME.github.io/REPO/)

解决方法:在 docs/.vuepress/config.js 里将部署站点的基础路径 base 设置为仓库名就可以了,注意前后要加/,示例:base:"/REPO/"。

项目里本地引用的图片这类静态资源尽量都用相对路径,vuepress打包的时候会根据 base 自动处理。

base(部署站点的基础路径) 这个参数你根据名字也能看出来最后是针对部署到服务器上用的,所以本地直接打包yarn build出来的文件用一些第三方的插件如:serve直接运行可能会出错,因为base没生效,要本地查看build效果base可以先设置成默认的 "/"。

四、vuepress v2版本的坑

最新的v2版本和v1有很大的不同,网上大部分的教程都是针对v1版的,在v2中并不起作用。

1. 模块化

有的地方使用import导入文件会报错,如config.js里的配置,这里导出配置用的 module.exports,本身就是node的CommonJS模块规范导出规范,导入要用require来引入(当你在开发一个 VuePress 应用时,由于所有的页面在生成静态 HTML 时都需要通过 Node.js 服务端渲染)

2. vue组件中使用CommonJS的require导入报错

vuepress最新的v2版本默认打包方式是Vite(只支持 ES 规范,不支持 CommonJS 规范),在组件中直接用CommonJS的require其他文件会报错:ReferenceError: require is not defined,vue3的官方文档上也有介绍:

Vite 是一个 web 开发构建工具,由于其原生 ES 模块导入方式,可以实现闪电般的冷服务器启动

3. markdown中使用vue组件

v2版本中像v1所谓的“主题目录结构约定”不再存在,所以 .vuepress/components下的组件并不会被自动全局注册,需要自己手动注册或者借助 @vuepress/plugin-register-components 插件来配置