Github Pages部署 ​

要将项目的Web示例/文档部署到Github Pages，主要需要完成以下两步：

• 项目打包配置：项目内部配置，实现本地手动/Github Action自动的打包推送；
• Github配置：在Github上进行配置，主要配置用于展示的分支/路径以及权限。

示例项目：Warehouse Page

项目打包配置 ​

Vite项目 ​

基于Vite构建的项目发布到Github Pages可以参考：

• Github Pages：此处是基于Github Action触发流水线自动打包并推送；
• v3.GitHub Pages：此处是在本地通过执行脚本进行打包，并推送打包好的静态文件至公开的Github仓库的指定分支。比较适合私有项目，可以只对外暴露打包好的文件，而不暴露私有项目的源代码。

VitePress文档 ​

基于VitePress构建的博客或者文档可以参考VitePress官方文档Github Pages配置。

此博客亦是基于VitePress构建，打包推送需结合ACCESS_TOKEN实现，相关配置与官方文档略有不同，详见deploy.yml。

其中参数ACCESS_TOKEN生成及配置可参考ACCESS_TOKEN.

VuePress文档 ​

基于VuePress(v2版本)构建的博客或者文档可以参考VuePress官方文档Github Pages配置。

亦可参考本人实践过得项目配置：docs.yml

Github配置 ​

配置发布源 ​

在公开的Github项目中配置用于展示Github Pages的分支及路径。

详情参考为 GitHub Pages 站点配置发布源。

当有新的commit提交到配置的分支/路径时，Github Action会自动触发部署。

ACCESS_TOKEN ​

如果打包配置中没有用到ACCESS_TOKEN,可跳过此步骤。

参数ACCESS_TOKEN需在Github项目中进行配置：

• 生成方式：可参考创建 personal access token(此token需具有推送权限，因此权限选中repo即可)。
• 配置方式：可参考为存储库创建加密的Secrets

踩坑记录 ​

Github Pages展示404错误 ​

基于Vite打包好了Web示例，本地执行vite preview指令，Web示例本地运行正常。

使用脚本将其推送到Github Pages，示例网页加载失败，查看console显示类似以下错误：

• Failed to load resource: the server responded with a status of 404
• net::ERR_ABORTED 404

反复检查之后，最终发现是问题是因为移除了脚本中的如下内容：

# place .nojekyll to bypass Jekyll processing
echo > .nojekyll

# place .nojekyll to bypass Jekyll processing
echo > .nojekyll

上述脚本作用及原因如下(摘自.nojekyll 文件是什么)：

Github Pages默认是基于Jekyll构建，Jekyll是一个将纯文本转换为静态网站的工具，它构建的网站下各种目录都是特定的以下划线开头命名的文件夹，例如 _layouts、_posts ，它会忽略掉其它的以下划线开头的文件夹和文件。

.nojekyll就是告诉Github Pages当前网站不是基于Jekyll构建的，不要忽略掉下划线开头的文件和文件夹。