目的:提交代码,自动触发构建,并发布到 Github Pages 上
不详细讲为什么,只讲在怎么做
项目准备
- 先在
github
上准备一个前端项目,我使用vue3
搭建了一个前端项目,技术栈为:vue3、vite、element-plus、pinia、vue-router、headlessui、tailwindcss、typescript
如何搭建可看这篇:《vue3 + vite + element-plus + tailwindcss + typescript 实战项目》
- 前端项目情况:只有
main
分支;项目文件如下图,代码在这

Github Pages 配置
可以理解为免费的线上服务器,可展示 build 后的前端项目
- 开启配置
- 开启配置后,再刷新下页面(没有的话可强刷、关闭重进),可以看到访问地址

- 访问下地址,发现页面是空白的,打开控制台,发现有 html 结构,原因是:会默认加载了该 github 项目下根目录的 index.html 文件

- 现在去改一下该 github 项目根目录的 index.html 文件,加个点文字,然后提交代码

等个 1、2 分钟,再刷新访问网址,就能看到最新的内容
- 至此简单的 github pages 配置完成,可以放只有一个 .html 的在线简历
Github Actions 配置
可以理解为 CI、CD
入门文档可看这篇:GitHub Actions 入门教程 - 阮一峰的网络日志
可以配合上面的 Github Pages,实现提交代码,自动构建并发布的效果。
- 更改
Github Pages
配置,改为Github Actions
形式

- 创建
Github Actions
的配置

- 会帮我们生成了一个最基本的配置,然后我们提交到
mian
分支上
- 提交后,我们进入
Actions
下,可看到第一个workflows

- 现在去改一下该 github 项目根目录的 index.html 文件,再加点文字,然后提交代码

- 然后去
Actions
下,看又有了一个workflow

- 然后等它成功后,访问下该项目的 Github Pages,看到内容也变化了

- 至此简单的 github actions 配置完成,结合 github pages 可以放只有一个 .html 的在线简历,实现提交代码自动部署功能(虽然没啥用)
Vue3 + Vite 项目接入
上面的流程比较简单,真正的项目是需要:提交代码后,触发构建、生成 dist、部署 dist,最终实现页面内容的更新
本次项目的线上代码地址:在这
- 将项目拉取到本地:
git clone xxx
- 先在本地跑下构建命令,确定没得问题
- 更改
vite.config.ts
配置,将打包目录改为 github 项目目录

- 更改
.github/workflows/static.yml
配置,加入打包流程:

- 完整代码如下(pnpm 版):
yml
# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages
on:
# Runs on pushes targeting the default branch
push:
branches: ['main']
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: 'pages'
cancel-in-progress: false
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- uses: pnpm/action-setup@v2
with:
version: 8
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 20
cache: 'pnpm'
- name: Install dependencies
run: pnpm install
- name: Build
run: pnpm run build
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
# Upload entire repository
path: './dist'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
- 完整代码如下(npm 版):
yml
# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages
on:
# Runs on pushes targeting the default branch
push:
branches: ['main']
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: 'pages'
cancel-in-progress: false
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 20
cache: 'npm'
- name: Install dependencies
run: npm install
- name: Build
run: npm run build
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
# Upload entire repository
path: './dist'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
- 提交一下代码,然后去看
Actions
状态

- 如果觉得频繁跳到 github 麻烦,可以安装 VScode 插件:GitHub Actions,然后在 VScode 里面直接看,并且还可点击直接打开网页的
github actions
内

- actions 成功后,打开项目的 github pages 访问地址,看看是否对了,已经对了

- 然后点点页面,跳转下路由,都是对的
- 但是刷新下发现就 404 了,这不是浪费感情吗?
别急,这个原因是前端项目采用了history
的路由模式,对github pages
来说,访问https://mrhzq.github.io/vue3-vite-element-plus-tailwindcss-typescript/about
是访问/about
目录下的index.html
但我们哪有/about
目录,所以就去找访问目录(我们配的/dist
)下的404.html
,没找到就显示官方的 404 页面
问题处理
Github Pages 刷新后,页面 404
原因上面一行就有写,不赘述;正确的处理方式是:配置 nginx,将其他路径的访问全部都指向 index.html。但 Github Pages 我们没法这样去处理,所以只能"取巧"
1、前端项目采用hash
模式,重新触发actions
后,就完全正常了,但地址就不好看,看个人选择 。只需改路由就行,然后提交代码,等actions
成功,就可以任意刷新

2、在访问目录(我们配的/dist
)下的创建一个404.html
,内容跟index.html
一模一样,这样显示404.html
时也跟正常显示index.html
一样
我们可以在打包成功了,复制下
index.html
,命名为404.html
就行
a、package.json
新增一个404build
命令,用于生成404.html
json
{
// ...
"scripts": {
// ...
"404build": "cp dist/index.html dist/404.html"
},
}
b、.github/workflows/static.yml
新增一个404Build
步骤

yml
- name: 404Build
run: npm run 404build
c、提交代码,等actions
成功,就可以任意刷新

Github Actions 失败处理
失败的,github 会发邮件给你哦
- 找到失败的

- 进入详情


报错:Supported file patterns: package-lock.json,npm-shrinkwrap.json,yarn.lock
因为我使用的是 pnpm,所以项目中没有 package-lock.json 文件。
处理方式:npm i
,生成一个package-lock.json
然后提交代码