本文主要分享基于 vite 创建的前端项目如何部署到 github pages 上。你也可以参考其中的内容部署别的前端静态项目。
✓注意:本文介绍的是如何通过非 github actions 的方式部署代码
1、先使用 vite 创建一个项目,并编写好自己的逻辑。我这里准备的项目是使用 vue-vine 创建的项目。
2、打包
npm run build
在 github 的仓库中,找到如下页面。
✓github repo -> Settings -> Pages
3、Deoply from a branch
这里的 Source 面板提供了两种部署方式,一种是通过 github actions 来部署,另外一种是通过分支代码来部署,我们这里选择第二种。
4、选择分支与目录
这一步需要特别注意的是,不同的选择需要对打包结果进行不同的调整。这是许多人在部署 github pages 时会失败的主要原因。
第一种,main 分支的根目录。此时需要我们将打包之后的 index.html
文件放到打包之后的根目录下。并且相对应的静态资源都需要做调整。因此这种方式通常情况下我们都是不使用的。
第二种,main 分支的 docs
目录下。
选择此项之后,我们需要把存放打包结果的目录,从默认的 dist
修改为 docs
,在 vite.config.js
中添加如下配置即可
export default defineConfig({
plugins: [
VineVitePlugin(),
tailwindcss()
],
+ build: {
+ outDir: 'docs'
+ }
})
i需要特别注意的是,打包之后,生成的 docs 文件夹不能添加到
.gitignore
,将其推送到远程分支,即可部署成功
剩下的事情就比较简单,你只需要将在 main 分支打包之后的代码推送到远程分支,过一会儿就部署成功了。
注意记得在配置时,要点击 Save
按钮,
等待一会儿之后,会出现该项目的访问地址。
5、按需调整
如果不出意外的话,到这里就部署成功了。但是意外就产生了。这里要注意区 github pages 给你分配的项目路径,到底是域名根目录,还是根目录下面的其中一个路径。
每个 github 用户,都有一个域名,例如我的域名是
yangbo5207.github.io
但是该域名只能针对其中一个项目生效,剩下的项目,就是会分配到根目录下的其中一个路径下,该项目的访问地址,会结合域名与项目名称组成
例如,我当前这个项目的访问路径为,vuevinedemo
是我的项目名称
https://yangbo5207.github.io/vuevinedemo
在这种情况之下,我们发现,vite 项目中的静态资源,默认访问路径是从根目录开始访问的 /assets/...
因此,这个时候直接访问就会报错 404
因此,我们要在打包时,把静态资源的绝对路径,修改为相对路径。继续修改 vite.config.js
如下
export default defineConfig({
plugins: [
VineVitePlugin(),
tailwindcss()
],
build: {
outDir: 'docs'
},
+ base: './'
})
打包结果
然后推送代码到远程分支,就可以正常访问了。
6、理解路由
如果你在本地开发中使用了 history 路由相关的方案,那么这里可能还会出问题。
✓一定要特别注意如何区分客户端路由与服务端路由,如果你目前还不具备准确区分 pathname 在客户端和服务端都不同表现的话,项目中建议优先使用 hash 路由,这样可以避免许多问题
这里列举几个使用 history 路由时,可能会遇到的问题。
const router = createRouter({
history: createWebHistory(),
routes: routers,
linkActiveClass: 'text-red-500'
})
当你的部署之后,项目根目录不是 /
而是 /vuevinedemo
或者其他名称时,我们必须要同步修改在项目中的路由设置
例如,我的代码为
let base = '/vuevinedemo'
const routers = [
{
path: base,
component: HomeView
},
{
path: `${base}/tutorial`,
component: Dashboard
},
{
path: `${base}/component`,
component: Component
},
{
path: `${base}/blog`,
component: Blog
}
]
此时我们需要特别注意,一定要把 /vuevinedemo
当成你整个项目的根目录,否则就直接跑到 域名的根目录下去了
正常的表现如下,注意看路由的变化
此时的路由都是客户端路由,但是 github pages 的服务端目前只处理了 /vuevinedemo
,因此,此时当我们在其他的路由刷新页面时,会直接 404
这个时候,我们可以把 打包文件中的 index.html 复制一份,重命名为 404.html 就可以了。
build 指令修改如下
"build": "vite build && cp docs/index.html docs/404.html",
✓这样处理之后,我们就会发现一个问题,那就是本地开发环境需要的内容与部署之后的内容不一样,因此,为了解决这个问题,你可以把 base 提取出来,然后通过区分环境变量的方式给 base 赋予不同的值。
我们也可以重新自定义一个域名,来表示解决上诉遇到的根目录问题。
此时,我重新解析出来一个新的域名,这个新的域名需要你通过其他的方式获得。输入到这里,等待几秒钟,等到他 DNS 解析成功之后,就可以正常访问了。
此时,我们要在项目中把刚才的代码调整回来。这个时候我们就通过 vine.usehook.cn
来访问该项目,而不是通过 yangbo5207.github.io/vuevinedemo
来访问。
刚才这种方式确实比较简单,但是每次都需要把打包文件提交到 main
分支,有点不太优雅,如果你不太能接受这种情况的话,我们可以使用另外的方式,把打包之后的代码放到另外的分支上。这个分支通常为 gh-pages
在项目中添加如下依赖
yarn add gh-pages -D
然后创建一个新分支,命名为 gh-pages
并推送到远程分支
git branch gh-pages
git checkout gh-pages
git push
确保在远程的 github 仓库中能看到这个分支。
然后在 Pages 配置页面选择 gh-pages
分支,并选中根目录
确保你的远程分支名为 origin
然后执行我们定义好的打包指令。
"build": "vite build && cp docs/index.html docs/404.html",
npm run build
然后再自定义一个发布指令
"deploy": "gh-pages -d docs"
docs
表示打包的目录,你可以根据需要改成 dist
然后执行如下执行发布代码
npm run deploy
接下来只需要等待部署,一会儿就成功了。
由于此时你的自定义域名的 CNAME
文件可能已经被覆盖了,因此你需要重新添加一个 CNAME
文件。你可以在打包时写个简单的脚本自己创建一个这个文件
// CNAME
vine.usehook.cn
也可以每次部署之后,手动去刚才的配置中添加
部署成功之后的完整演示效果如下
大家可以通过访问 vine.usehook.cn
感受效果。