来认真学一下，项目部署到 github pages

本文主要分享基于 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 来访问。

方式二：gh-pages

刚才这种方式确实比较简单，但是每次都需要把打包文件提交到 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 感受效果。